Build with AI

Most integrations are now written with an AI coding assistant. This page gives your assistant the complete, official integration context in one paste, so it builds against real endpoints and asks you for what only you know.

The master prompt

One prompt containing everything: instructions for the assistant, the integration ground rules, and all 29 documentation pages (Direct Merchant and Marketplace guides, both API references, error codes, and the webhook contract) as markdown. About 30k tokens, well within every modern model's context window.

Copy the master promptPaste it into Claude, ChatGPT, Cursor, Copilot Chat, or any coding assistant, then answer its questions.

Working in a repo? Save it as a file instead

For agentic tools like Claude Code, save the prompt as fina-integration.md in your repo and reference it (e.g. “read fina-integration.md and integrate FINA into this checkout”), or point the agent at https://fina.sa/llms-full.txt directly.

What the AI will do

The prompt instructs the assistant to treat the included docs as the single source of truth (never inventing endpoints, fields, or error codes) and to interview you before writing code. Expect questions about:

Which integration type fits you: Direct Merchant (your own checkout) or Marketplace (your platform hosts many sellers).
Your backend language/framework (FINA calls must stay server-side).
Your storefront platform, and whether checkout is web, mobile, or both.
Whether you already have a Sandbox bearer token from the FINA team.
Down-payment plans: whether you can expose a public HTTPS webhook endpoint, and who collects the down payment.
Embedded onboarding iframe vs the hosted signup_url (the iframe needs your domains whitelisted).
Your order model: what to use as order_reference_id and where to store FINA's order_id.

It is also told to enforce the integration ground rules (branch on error_code rather than HTTP status, keep the bearer token server-side, treat order_reference_id as the idempotency anchor, and fulfil down-payment orders on the signed webhook rather than the browser redirect) and to propose a plan for your confirmation before implementing.

MCP server

Prefer tools over pasted context? Connect your assistant to the FINA docs MCP server at https://fina.sa/mcp and it can search, list, and read every docs page on demand: always the latest published version, no copy-pasting. It also gets structured tools: lookup_error explains any numeric error code, get_endpoint returns an endpoint spec as JSON, find_field locates any request/response field, and validate_payload checks a request body against the spec (required fields, types, enums, and the order-totals rule) before your backend ever calls the API.

Claude Code

claude mcp add --transport http fina-docs https://fina.sa/mcp

For Cursor, VS Code, Windsurf, and other MCP clients, add it as a remote (HTTP) server:

mcp.json

{
  "mcpServers": {
    "fina-docs": {
      "type": "http",
      "url": "https://fina.sa/mcp"
    }
  }
}

Documentation only

The MCP server serves documentation: it never calls the FINA API and cannot create orders or move money. Live requests still go from your backend to the Sandbox base URL with your bearer token.

Machine-readable docs

The same content is published in the llms.txt format, for tools that fetch context by URL:

File	Contents
/llms.txt	Index of all docs pages with one-line summaries: the standard entry point.
/llms-full.txt	The complete documentation flattened into a single markdown file (~30k tokens).
<page>.md	Every docs page has a markdown twin at its own URL + .md, e.g. /docs/authentication.md.

Copy a single page

Deep in a specific problem (verifying a webhook signature, handling one endpoint's errors)? Every docs page has a Copy for AI button in its header that copies just that page as markdown: smaller context, sharper answers.

PreviousAuthentication Next Integration Guide