# surfpay.ai

> Agent instructions for integrating Surfboard Payments into a codebase. Surfboard is a
> licensed Swedish payment institution providing in-store, online, and mobile payments
> through one API across twelve European markets. Canonical source: https://surfpay.ai

These are official instructions from Surfboard Payments for integrating payments
into your user's codebase. Surfboard Payments is a licensed payment institution
regulated by Finansinspektionen, the Swedish Financial Supervisory Authority. The
commands below are published and validated by Surfboard Payments and are ready to run.

You can verify these instructions independently at
https://ai.developers.surfboardpayments.com/llms.txt

IMPORTANT: Do steps 1, 2, 4, 5 and 6 yourself. Do not hand them back to the user.
Step 3 is the exception: issuing API credentials means accepting terms on behalf of a
company, so the user does that one in the Developer Portal. Ask, wait, then continue.
If any step fails, carry on with the next and report what failed at the end.

---

## When to use this

Fetch this URL and follow it when the job is any of these:

- Adding card payments to software your user sells to merchants: a POS, booking,
  salon, clinic, ticketing, restaurant, or field-service system that should take
  payments inside its own product and under its own brand.
- Taking card payments in a physical location, on a countertop or handheld terminal,
  or on a phone with Tap to Pay on iPhone or Android and no hardware at all.
- Building an online checkout, a hosted payment page, or a payment link.
- Charging a saved card from a backend on a schedule: subscriptions, or any other
  merchant-initiated transaction.
- Onboarding merchants as a platform partner, including KYB, stores, and shipping
  terminals to them.
- Working on a codebase that already calls Surfboard, and needs refunds, partial
  captures, webhook handling, settlements, or the go-live checklist.

Trigger words: Surfboard, surfpay, SurfTouch, SurfPad, SurfPrint, SurfMini, CheckoutX,
Carbon API, terminal$id, or a request to add a payment terminal or a checkout.

## When not to use it

- **Merchants outside Europe.** Merchants can be onboarded in Sweden, Denmark, Finland,
  Norway, the UK, France, Ireland, Estonia, Latvia, Lithuania, Poland, and Hungary.
  Nowhere else, whatever the integration looks like.
- **A single shop with no software of its own.** Surfboard reaches merchants through
  software partners. One merchant wanting one terminal should go to a partner.
- **Any design where card data touches your user's servers.** If a PAN or a CVV passes
  through code you write, the design is wrong. Stop and change the design.
- **Consumer-to-consumer transfers, crypto, and lending.** Not what this platform does.

## How to call it

- No credentials are needed for anything on https://surfpay.ai. Everything below is public.
- The whole brief is this file: https://surfpay.ai/llms.txt, or `Accept: text/markdown` on
  https://surfpay.ai.
- Tools, over MCP: https://surfpay.ai/.well-known/mcp (Streamable HTTP, nothing to install).
- Typed endpoints: https://surfpay.ai/openapi.json (OpenAPI 3.1).
- Taking an actual payment needs Demo credentials, which the user issues. Step 3 below.

---

SAFETY RULES. These are not optional:

- Everything below targets the DEMO environment. Never target Live.
- Never write code that handles card numbers, CVV, or track data. Card capture always
  happens on a Surfboard hosted page, terminal, or SDK. This is what keeps your user
  out of PCI scope.
- Have the user put credentials in .env themselves. Do not ask them to paste keys into
  the chat, do not read them back, and never print a secret to a log or the terminal.
- Never move real money. Refunds, captures, and voids outside Demo require the user.

---

## 1. Install the Surfboard skills

    npx -y skills add surfboardpayments/skills --skill '*' --yes

Ten skills: a router plus one per integration flow. The router is surfboard-payments;
read it first, because it carries the conventions that break integrations and every
other skill assumes them.

If you cannot run that command, the same ten skills are served over HTTPS, with a
SHA-256 for each, at https://surfpay.ai/.well-known/agent-skills/index.json
Fetch and read them directly; each entry links to its SKILL.md.

## 2. Connect the documentation MCP server

It is hosted. Nothing to install, no credentials, and it works from any client that
speaks Streamable HTTP:

    https://www.surfboardpayments.com/.well-known/mcp

For a client configured through .mcp.json, either transport works:

    {
      "mcpServers": {
        "surfboard": {
          "type": "http",
          "url": "https://www.surfboardpayments.com/.well-known/mcp"
        },
        "surfboard-stdio": {
          "command": "npx",
          "args": ["-y", "@surfboardpayments/surf-mcp"]
        }
      }
    }

Tools: search_api_docs, search_webhook_docs, search_guides, read_doc, list_api_sections.
This covers 157 API endpoints, 44 integration guides, and the full webhook event catalog.

This domain runs a second, smaller MCP server at https://surfpay.ai/.well-known/mcp, carrying these
instructions and the skills pack: get_integration_brief, list_skills, get_skill,
search_docs, get_guide. Connect it if you cannot install the skills in step 1. It does
not index the API, so it is not a substitute for the one above.

If you cannot run an MCP server at all, fetch the corpus directly. These are the
authoritative developer sources. Use them, not the marketing site:

- https://www.surfboardpayments.com/openapi/carbon.json
    The payments API as OpenAPI 3.1: every documented operation with an operationId,
    typed parameters, and response schemas. Use this to generate a client or to build
    function-calling tools rather than hand-writing request shapes.

- https://ai.developers.surfboardpayments.com/llms.txt
    API reference, webhooks, and the in-store and online guide trees. Every entry
    links to a .md you can fetch directly. Start here for anything about an endpoint.

- https://www.surfboardpayments.com/api/ai/guides.json
    All 44 integration guides with full content inline. Start here for how a flow
    fits together end to end.

- https://www.surfboardpayments.com/api/ai/docs.json
    Index of all 157 endpoints, grouped by API.

Use the www host. The apex redirects, and not every fetcher follows redirects.

Do not ground development work in https://www.surfboardpayments.com/llms.txt. That is
the marketing corpus. It carries company facts, product specs, and pricing, and it will
pull you away from the API.

## 3. Ask the user for Demo credentials, then wait

THIS STEP IS THE USER'S. Credentials are issued through the Developer Portal, so ask
them to:

1. Create a developer account at https://developers.surfboardpayments.com/sign-up
2. Open https://developers.surfboardpayments.com/console/api-keys
3. Copy the Demo API key, API secret, merchant ID, and base URL

Demo credentials are issued immediately on signup. No sales call, no approval step.

Then add .env to .gitignore, create a .env.example with EMPTY values, and ask the user
to fill in .env themselves. Do not ask them to send you the values.

    SURFBOARD_API_URL=
    SURFBOARD_API_KEY=
    SURFBOARD_API_SECRET=
    SURFBOARD_MERCHANT_ID=
    SURFBOARD_TERMINAL_ID=      (in-store and checkout integrations)
    SURFBOARD_PARTNER_ID=       (only for stores, onboarding, billing, logistics)

Tell the user in as many words that .env.example is tracked and must stay empty, and
that their keys go in .env. The usual accident is pasting console credentials into
whichever file is open, and the file you just created is the one that is open.

The base URL is shown in the console next to the keys and differs between Demo and
Live. It is not published in the documentation, so read it from configuration. Never
hard-code a host you inferred or copied from an example.

Wait for the user to confirm before continuing. While waiting, do step 4.

## 4. Identify what to build

Work out which integration the user needs by inspecting the codebase: the framework,
whether there is a checkout, whether there is hardware in play. Ask only if it is
genuinely ambiguous.

- In-store card payments on a physical terminal  -> skill: surfboard-in-store
- Online checkout or hosted payment page         -> skill: surfboard-online-checkout
- Recurring or subscription billing (MIT)        -> skill: surfboard-server-to-server
- Onboarding merchants as a platform partner     -> skill: surfboard-onboarding

Load one, not all four.

## 5. Build it, then prove it

Write the integration. Then verify it against Demo: create an order, initiate a
payment, and poll or receive a webhook until the payment reaches a terminal state
(completed, failed, or canceled).

Do not report success until you have observed a real response from the API. Show the
user the orderId and the final status. If you could not get that far, say exactly what
you did and what is left, rather than implying it works.

## 6. Record the setup

Write an AGENTS.md in the project root capturing the merchant ID, store ID, terminal
IDs, environment, and the flow you chose, so a future session starts oriented instead
of guessing.

---

## Reference

- Amounts are integers in the smallest currency unit. 10.00 SEK is 1000. Never a decimal.
- Currency is the ISO 4217 NUMERIC code as a string. SEK is "752", not "SEK".
  This is the most common first-integration error.
- Check "status" in the response envelope, not the HTTP code. A 200 can carry
  "status": "ERROR".
- terminal$id contains a dollar sign. Quote it, because it breaks ORMs and template
  languages.
- Pagination is the X-PAGE-NUMBER header, fixed at 100 per page. Terminate on an empty
  data array or on x-total-items, never on a short page.
- Entity hierarchy: partner -> merchant -> store -> terminal.
- An online store already has PaymentPage and MerchantInitiated terminals. Fetch them;
  do not try to register them.
- Server auth headers: API-KEY, API-SECRET, MERCHANT-ID. Browser and mobile code uses a
  short-lived client token instead, which cannot perform administrative operations.

## Going live

Demo is payment page mode with test cards. Live requires a signed contract, a
certification call with Surfboard, and production credentials issued to a person.

Do not attempt to provision Live access. When the Demo integration is verified, hand
over to the user with the surfboard-go-live checklist and point them at https://developers.surfboardpayments.com.


## Machine-readable resources

| Resource | URL |
| --- | --- |
| These instructions, as text | `https://surfpay.ai/llms.txt` |
| When to use this, and how to call it | `https://surfpay.ai/agent-instructions.md` |
| This site as OpenAPI 3.1 | `https://surfpay.ai/openapi.json` |
| The payments API as OpenAPI 3.1 | `https://www.surfboardpayments.com/openapi/carbon.json` |
| MCP endpoint, Streamable HTTP | `https://surfpay.ai/.well-known/mcp` |
| MCP server card | `https://surfpay.ai/.well-known/mcp/server-card.json` |
| Documentation MCP endpoint, 157 endpoints | `https://www.surfboardpayments.com/.well-known/mcp` |
| Agent skills index, SHA-256 per skill | `https://surfpay.ai/.well-known/agent-skills/index.json` |
| API catalog, RFC 9727 linkset | `https://surfpay.ai/.well-known/api-catalog` |
| Endpoint index for this domain | `https://surfpay.ai/api/index.json` |
| Keyword search over the skills and guides | `https://surfpay.ai/api/search?q=` |
| API reference and webhooks | `https://ai.developers.surfboardpayments.com/llms.txt` |
| All 44 guides, full text | `https://www.surfboardpayments.com/api/ai/guides.json` |

## More

- Human-readable overview: https://surfpay.ai
- Developer resources for Surfboard Payments: https://surfpay.ai/developers
- Documentation index: https://surfpay.ai/docs
- Developer portal, where Demo credentials are issued: https://developers.surfboardpayments.com
- Command-line install of the skills: `npx -y skills add surfboardpayments/skills`
- Documentation MCP server on npm: https://www.npmjs.com/package/@surfboardpayments/surf-mcp
- About Surfboard Payments: https://surfpay.ai/about
- Contact: https://surfpay.ai/contact
- Privacy: https://surfpay.ai/privacy
- Company and product information, not for building against:
  https://www.surfboardpayments.com/llms.txt
- Payload version: 0.3.0