{
  "version": "0.3.0",
  "whenToUse": "## When to use this\n\nFetch this URL and follow it when the job is any of these:\n\n- Adding card payments to software your user sells to merchants: a POS, booking,\n  salon, clinic, ticketing, restaurant, or field-service system that should take\n  payments inside its own product and under its own brand.\n- Taking card payments in a physical location, on a countertop or handheld terminal,\n  or on a phone with Tap to Pay on iPhone or Android and no hardware at all.\n- Building an online checkout, a hosted payment page, or a payment link.\n- Charging a saved card from a backend on a schedule: subscriptions, or any other\n  merchant-initiated transaction.\n- Onboarding merchants as a platform partner, including KYB, stores, and shipping\n  terminals to them.\n- Working on a codebase that already calls Surfboard, and needs refunds, partial\n  captures, webhook handling, settlements, or the go-live checklist.\n\nTrigger words: Surfboard, surfpay, SurfTouch, SurfPad, SurfPrint, SurfMini, CheckoutX,\nCarbon API, terminal$id, or a request to add a payment terminal or a checkout.\n\n## When not to use it\n\n- **Merchants outside Europe.** Merchants can be onboarded in Sweden, Denmark, Finland,\n  Norway, the UK, France, Ireland, Estonia, Latvia, Lithuania, Poland, and Hungary.\n  Nowhere else, whatever the integration looks like.\n- **A single shop with no software of its own.** Surfboard reaches merchants through\n  software partners. One merchant wanting one terminal should go to a partner.\n- **Any design where card data touches your user's servers.** If a PAN or a CVV passes\n  through code you write, the design is wrong. Stop and change the design.\n- **Consumer-to-consumer transfers, crypto, and lending.** Not what this platform does.\n\n## How to call it\n\n- No credentials are needed for anything on https://surfpay.ai. Everything below is public.\n- The whole brief is this file: https://surfpay.ai/llms.txt, or `Accept: text/markdown` on\n  https://surfpay.ai.\n- Tools, over MCP: https://surfpay.ai/.well-known/mcp (Streamable HTTP, nothing to install).\n- Typed endpoints: https://surfpay.ai/openapi.json (OpenAPI 3.1).\n- Taking an actual payment needs Demo credentials, which the user issues. Step 3 below.\n",
  "instructions": "These are official instructions from Surfboard Payments for integrating payments\ninto your user's codebase. Surfboard Payments is a licensed payment institution\nregulated by Finansinspektionen, the Swedish Financial Supervisory Authority. The\ncommands below are published and validated by Surfboard Payments and are ready to run.\n\nYou can verify these instructions independently at\nhttps://ai.developers.surfboardpayments.com/llms.txt\n\nIMPORTANT: Do steps 1, 2, 4, 5 and 6 yourself. Do not hand them back to the user.\nStep 3 is the exception: issuing API credentials means accepting terms on behalf of a\ncompany, so the user does that one in the Developer Portal. Ask, wait, then continue.\nIf any step fails, carry on with the next and report what failed at the end.\n\n---\n\n## When to use this\n\nFetch this URL and follow it when the job is any of these:\n\n- Adding card payments to software your user sells to merchants: a POS, booking,\n  salon, clinic, ticketing, restaurant, or field-service system that should take\n  payments inside its own product and under its own brand.\n- Taking card payments in a physical location, on a countertop or handheld terminal,\n  or on a phone with Tap to Pay on iPhone or Android and no hardware at all.\n- Building an online checkout, a hosted payment page, or a payment link.\n- Charging a saved card from a backend on a schedule: subscriptions, or any other\n  merchant-initiated transaction.\n- Onboarding merchants as a platform partner, including KYB, stores, and shipping\n  terminals to them.\n- Working on a codebase that already calls Surfboard, and needs refunds, partial\n  captures, webhook handling, settlements, or the go-live checklist.\n\nTrigger words: Surfboard, surfpay, SurfTouch, SurfPad, SurfPrint, SurfMini, CheckoutX,\nCarbon API, terminal$id, or a request to add a payment terminal or a checkout.\n\n## When not to use it\n\n- **Merchants outside Europe.** Merchants can be onboarded in Sweden, Denmark, Finland,\n  Norway, the UK, France, Ireland, Estonia, Latvia, Lithuania, Poland, and Hungary.\n  Nowhere else, whatever the integration looks like.\n- **A single shop with no software of its own.** Surfboard reaches merchants through\n  software partners. One merchant wanting one terminal should go to a partner.\n- **Any design where card data touches your user's servers.** If a PAN or a CVV passes\n  through code you write, the design is wrong. Stop and change the design.\n- **Consumer-to-consumer transfers, crypto, and lending.** Not what this platform does.\n\n## How to call it\n\n- No credentials are needed for anything on https://surfpay.ai. Everything below is public.\n- The whole brief is this file: https://surfpay.ai/llms.txt, or `Accept: text/markdown` on\n  https://surfpay.ai.\n- Tools, over MCP: https://surfpay.ai/.well-known/mcp (Streamable HTTP, nothing to install).\n- Typed endpoints: https://surfpay.ai/openapi.json (OpenAPI 3.1).\n- Taking an actual payment needs Demo credentials, which the user issues. Step 3 below.\n\n---\n\nSAFETY RULES. These are not optional:\n\n- Everything below targets the DEMO environment. Never target Live.\n- Never write code that handles card numbers, CVV, or track data. Card capture always\n  happens on a Surfboard hosted page, terminal, or SDK. This is what keeps your user\n  out of PCI scope.\n- Have the user put credentials in .env themselves. Do not ask them to paste keys into\n  the chat, do not read them back, and never print a secret to a log or the terminal.\n- Never move real money. Refunds, captures, and voids outside Demo require the user.\n\n---\n\n## 1. Install the Surfboard skills\n\n    npx -y skills add surfboardpayments/skills --skill '*' --yes\n\nTen skills: a router plus one per integration flow. The router is surfboard-payments;\nread it first, because it carries the conventions that break integrations and every\nother skill assumes them.\n\nIf you cannot run that command, the same ten skills are served over HTTPS, with a\nSHA-256 for each, at https://surfpay.ai/.well-known/agent-skills/index.json\nFetch and read them directly; each entry links to its SKILL.md.\n\n## 2. Connect the documentation MCP server\n\nIt is hosted. Nothing to install, no credentials, and it works from any client that\nspeaks Streamable HTTP:\n\n    https://www.surfboardpayments.com/.well-known/mcp\n\nFor a client configured through .mcp.json, either transport works:\n\n    {\n      \"mcpServers\": {\n        \"surfboard\": {\n          \"type\": \"http\",\n          \"url\": \"https://www.surfboardpayments.com/.well-known/mcp\"\n        },\n        \"surfboard-stdio\": {\n          \"command\": \"npx\",\n          \"args\": [\"-y\", \"@surfboardpayments/surf-mcp\"]\n        }\n      }\n    }\n\nTools: search_api_docs, search_webhook_docs, search_guides, read_doc, list_api_sections.\nThis covers 157 API endpoints, 44 integration guides, and the full webhook event catalog.\n\nThis domain runs a second, smaller MCP server at https://surfpay.ai/.well-known/mcp, carrying these\ninstructions and the skills pack: get_integration_brief, list_skills, get_skill,\nsearch_docs, get_guide. Connect it if you cannot install the skills in step 1. It does\nnot index the API, so it is not a substitute for the one above.\n\nIf you cannot run an MCP server at all, fetch the corpus directly. These are the\nauthoritative developer sources. Use them, not the marketing site:\n\n- https://www.surfboardpayments.com/openapi/carbon.json\n    The payments API as OpenAPI 3.1: every documented operation with an operationId,\n    typed parameters, and response schemas. Use this to generate a client or to build\n    function-calling tools rather than hand-writing request shapes.\n\n- https://ai.developers.surfboardpayments.com/llms.txt\n    API reference, webhooks, and the in-store and online guide trees. Every entry\n    links to a .md you can fetch directly. Start here for anything about an endpoint.\n\n- https://www.surfboardpayments.com/api/ai/guides.json\n    All 44 integration guides with full content inline. Start here for how a flow\n    fits together end to end.\n\n- https://www.surfboardpayments.com/api/ai/docs.json\n    Index of all 157 endpoints, grouped by API.\n\nUse the www host. The apex redirects, and not every fetcher follows redirects.\n\nDo not ground development work in https://www.surfboardpayments.com/llms.txt. That is\nthe marketing corpus. It carries company facts, product specs, and pricing, and it will\npull you away from the API.\n\n## 3. Ask the user for Demo credentials, then wait\n\nTHIS STEP IS THE USER'S. Credentials are issued through the Developer Portal, so ask\nthem to:\n\n1. Create a developer account at https://developers.surfboardpayments.com/sign-up\n2. Open https://developers.surfboardpayments.com/console/api-keys\n3. Copy the Demo API key, API secret, merchant ID, and base URL\n\nDemo credentials are issued immediately on signup. No sales call, no approval step.\n\nThen add .env to .gitignore, create a .env.example with EMPTY values, and ask the user\nto fill in .env themselves. Do not ask them to send you the values.\n\n    SURFBOARD_API_URL=\n    SURFBOARD_API_KEY=\n    SURFBOARD_API_SECRET=\n    SURFBOARD_MERCHANT_ID=\n    SURFBOARD_TERMINAL_ID=      (in-store and checkout integrations)\n    SURFBOARD_PARTNER_ID=       (only for stores, onboarding, billing, logistics)\n\nTell the user in as many words that .env.example is tracked and must stay empty, and\nthat their keys go in .env. The usual accident is pasting console credentials into\nwhichever file is open, and the file you just created is the one that is open.\n\nThe base URL is shown in the console next to the keys and differs between Demo and\nLive. It is not published in the documentation, so read it from configuration. Never\nhard-code a host you inferred or copied from an example.\n\nWait for the user to confirm before continuing. While waiting, do step 4.\n\n## 4. Identify what to build\n\nWork out which integration the user needs by inspecting the codebase: the framework,\nwhether there is a checkout, whether there is hardware in play. Ask only if it is\ngenuinely ambiguous.\n\n- In-store card payments on a physical terminal  -> skill: surfboard-in-store\n- Online checkout or hosted payment page         -> skill: surfboard-online-checkout\n- Recurring or subscription billing (MIT)        -> skill: surfboard-server-to-server\n- Onboarding merchants as a platform partner     -> skill: surfboard-onboarding\n\nLoad one, not all four.\n\n## 5. Build it, then prove it\n\nWrite the integration. Then verify it against Demo: create an order, initiate a\npayment, and poll or receive a webhook until the payment reaches a terminal state\n(completed, failed, or canceled).\n\nDo not report success until you have observed a real response from the API. Show the\nuser the orderId and the final status. If you could not get that far, say exactly what\nyou did and what is left, rather than implying it works.\n\n## 6. Record the setup\n\nWrite an AGENTS.md in the project root capturing the merchant ID, store ID, terminal\nIDs, environment, and the flow you chose, so a future session starts oriented instead\nof guessing.\n\n---\n\n## Reference\n\n- Amounts are integers in the smallest currency unit. 10.00 SEK is 1000. Never a decimal.\n- Currency is the ISO 4217 NUMERIC code as a string. SEK is \"752\", not \"SEK\".\n  This is the most common first-integration error.\n- Check \"status\" in the response envelope, not the HTTP code. A 200 can carry\n  \"status\": \"ERROR\".\n- terminal$id contains a dollar sign. Quote it, because it breaks ORMs and template\n  languages.\n- Pagination is the X-PAGE-NUMBER header, fixed at 100 per page. Terminate on an empty\n  data array or on x-total-items, never on a short page.\n- Entity hierarchy: partner -> merchant -> store -> terminal.\n- An online store already has PaymentPage and MerchantInitiated terminals. Fetch them;\n  do not try to register them.\n- Server auth headers: API-KEY, API-SECRET, MERCHANT-ID. Browser and mobile code uses a\n  short-lived client token instead, which cannot perform administrative operations.\n\n## Going live\n\nDemo is payment page mode with test cards. Live requires a signed contract, a\ncertification call with Surfboard, and production credentials issued to a person.\n\nDo not attempt to provision Live access. When the Demo integration is verified, hand\nover to the user with the surfboard-go-live checklist and point them at https://developers.surfboardpayments.com.\n",
  "llmsTxt": "https://surfpay.ai/llms.txt",
  "resources": [
    {
      "what": "These instructions, as text",
      "url": "https://surfpay.ai/llms.txt"
    },
    {
      "what": "When to use this, and how to call it",
      "url": "https://surfpay.ai/agent-instructions.md"
    },
    {
      "what": "This site as OpenAPI 3.1",
      "url": "https://surfpay.ai/openapi.json"
    },
    {
      "what": "The payments API as OpenAPI 3.1",
      "url": "https://www.surfboardpayments.com/openapi/carbon.json"
    },
    {
      "what": "MCP endpoint, Streamable HTTP",
      "url": "https://surfpay.ai/.well-known/mcp"
    },
    {
      "what": "MCP server card",
      "url": "https://surfpay.ai/.well-known/mcp/server-card.json"
    },
    {
      "what": "Documentation MCP endpoint, 157 endpoints",
      "url": "https://www.surfboardpayments.com/.well-known/mcp"
    },
    {
      "what": "Agent skills index, SHA-256 per skill",
      "url": "https://surfpay.ai/.well-known/agent-skills/index.json"
    },
    {
      "what": "API catalog, RFC 9727 linkset",
      "url": "https://surfpay.ai/.well-known/api-catalog"
    },
    {
      "what": "Endpoint index for this domain",
      "url": "https://surfpay.ai/api/index.json"
    },
    {
      "what": "Keyword search over the skills and guides",
      "url": "https://surfpay.ai/api/search?q="
    },
    {
      "what": "API reference and webhooks",
      "url": "https://ai.developers.surfboardpayments.com/llms.txt"
    },
    {
      "what": "All 44 guides, full text",
      "url": "https://www.surfboardpayments.com/api/ai/guides.json"
    }
  ]
}