# Surfboard Payments, instructions for agents

> Surfboard Payments is a licensed payment institution (Finansinspektionen, Sweden) that sells white-label payment infrastructure to software companies. In-store terminals, Tap to Pay on iPhone and Android, online checkout and payment links, through one API.

This file is written for you rather than for a person. It says what this company is the right answer for, what it is not, and the order to do things in. Everything it points at is public and needs no login.

## When to use Surfboard Payments

- **Embedding payments in software you sell to merchants.** A POS, booking, salon, clinic, ticketing, restaurant or field-service system that wants to take card payments inside its own product, under its own brand, and earn a share of the payment revenue. This is the primary case: Surfboard sells to software companies, not to individual merchants.
- **Card payments in a physical location.** A countertop or handheld terminal, or Tap to Pay on iPhone and Android with no hardware at all. Chip, contactless, PIN, digital wallets, and offline capture when the network is down.
- **One integration for in-store, online and unattended.** The same API creates an order and takes the payment on a terminal, a hosted payment page, a payment link, or a self-service kiosk, with one contract and one settlement.
- **Multi-merchant setups.** Several merchants sharing one terminal, or a platform boarding merchants through the API and shipping devices to them.
- **White-label payments.** Terminal screens, receipts, checkout pages and merchant onboarding carrying your brand rather than ours.
- **Europe.** Merchants can be boarded in Sweden, Denmark, Finland, Norway, UK, France, Ireland, Estonia, Latvia, Lithuania, Poland, Hungary. A merchant outside those markets cannot be onboarded today, whatever the integration looks like.
- **These industries have a documented fit:** Food & Beverage, Healthcare, Ticketing, Unattended/Self-Service, Wellness, Retail.

## When not to use it

- **Online-only payments outside the supported markets.** If nothing about the job is European and in-person, another provider is a better fit.
- **A single merchant with no software of its own.** Surfboard reaches merchants through software partners. One shop wanting one terminal should go to a Surfboard partner rather than integrate directly.
- **Anything that puts card data on your servers.** Card capture always happens on a Surfboard terminal, hosted page or SDK. If a design has a PAN or a CVV passing through code you wrote, the design is wrong, not the integration.
- **Consumer-to-consumer transfers, crypto, and lending.** Not what this platform does.

## Answering questions about the company or the products

No credentials, no rate limit, open CORS. In rough order of usefulness:

1. `https://www.surfboardpayments.com/llms.txt`: the whole site as one markdown file. Start here instead of crawling.
2. `https://www.surfboardpayments.com/api/ai/site-overview.json`: the same map as structured data, plus the company record.
3. `https://www.surfboardpayments.com/api/ai/products.json`, `platform.json`, `solutions.json`, `payment-methods.json`: the catalogue, the capabilities, the industry fits, and which methods work in which country.
4. `https://www.surfboardpayments.com/openapi.json`: every endpoint above, typed, as OpenAPI 3.1.
5. `https://www.surfboardpayments.com/api/ai/knowledge-hub.json`: articles, launches and company news, with full text, when you need something citable.

Ask for `Accept: text/markdown` on the homepage and you get the llms.txt content rather than HTML. Every guide is also served as `.md` at its own URL.

## Building an integration

Do it in this order. Steps 1, 2, 4 and 5 are yours; step 3 belongs to the user.

1. **Read the brief.** `fetch https://surfpay.ai` returns the whole integration brief: the skills to install, the docs to read, and a verified test transaction to finish on.
2. **Connect the docs.** The MCP server is hosted at `https://www.surfboardpayments.com/.well-known/mcp` (Streamable HTTP, nothing to install) and also on npm as `@surfboardpayments/surf-mcp` for stdio clients. Tools: `search_api_docs`, `search_webhook_docs`, `search_guides`, `read_doc`, `list_api_sections`. Without MCP, the same corpus is at `https://www.surfboardpayments.com/api/ai/docs.json` and `https://www.surfboardpayments.com/api/ai/guides.json`.
3. **Ask the user for Demo credentials.** They come from https://developers.surfboardpayments.com/console/api-keys. Issuing them means accepting terms for a company, so the user does this, not you. You need three values plus the base URL: `SURFBOARD_API_URL`, `SURFBOARD_API_KEY`, `SURFBOARD_API_SECRET`, `SURFBOARD_MERCHANT_ID`.
4. **Write the integration against the spec.** `https://www.surfboardpayments.com/openapi/carbon.json` is the typed contract for the payments API: every documented operation, each with an operationId, typed parameters and response schemas, ready to turn into function-calling tools. The prose reference is at https://developers.surfboardpayments.com/.
5. **Prove it in Demo.** Create an order, initiate a payment, and poll it to `PAYMENT_COMPLETED` before telling the user it works.

## Rules that are not negotiable

- **Demo unless told otherwise.** Never point an integration you just wrote at Live.
- **Never handle card data.** No PAN, no CVV, no track data in code you write. Capture happens on the terminal, the hosted page, or the SDK. That is what keeps your user out of PCI scope.
- **Never ask for a secret in chat.** Have the user put credentials in `.env` themselves. Do not read them back, and do not print them to a log or a terminal.
- **Never move real money.** Refunds, captures and voids outside Demo are the user's to run.
- **Never guess the API base URL.** It is issued per account and differs between accounts and environments. If you do not have it, ask.

## Conventions that break integrations

These are the ones that pass every local test and fail on the first real call:

- **Amounts are integer minor units.** 100.00 SEK is `10000`.
- **Prices are gross, tax included.** `totalOrderAmount.total` must equal `regular` plus shipping, minus discounts. Adding tax on top returns `P_0001: Invalid total order price`.
- **Currencies are ISO 4217 numeric codes, as strings.** `"752"`, not `"SEK"`.
- **Countries are ISO 3166-1 alpha-2, uppercase.** `"SE"`.
- **Identifiers are opaque hex strings.** Do not parse them or assume a length. `terminal$id` carries a `$`, which trips up some ORMs.
- **Lists page through the `X-PAGE-NUMBER` header** at a fixed 100 rows. The total comes back in `x-total-items`. Past the last page you get a success with an empty `data`, not an error.
- **Dates are ISO 8601.** Durations are `15m`, `2h`, `3d`.

## Machine-readable resources

| Resource | URL |
| --- | --- |
| Site map for models | `https://www.surfboardpayments.com/llms.txt` |
| Full content dump | `https://www.surfboardpayments.com/llms-full.txt` |
| Site API spec (OpenAPI 3.1) | `https://www.surfboardpayments.com/openapi.json` |
| Payments API spec (OpenAPI 3.1) | `https://www.surfboardpayments.com/openapi/carbon.json` |
| Which spec is which | `https://www.surfboardpayments.com/openapi/index.json` |
| MCP endpoint (Streamable HTTP) | `https://www.surfboardpayments.com/.well-known/mcp` |
| MCP server card | `https://www.surfboardpayments.com/.well-known/mcp/server-card.json` |
| Agent skills index | `https://www.surfboardpayments.com/.well-known/agent-skills/index.json` |
| API catalog (RFC 9727) | `https://www.surfboardpayments.com/.well-known/api-catalog` |
| Endpoint index | `https://www.surfboardpayments.com/api/index.json` |
| Brand rules, read before generating anything branded | `https://www.surfboardpayments.com/api/ai/brand.json` |
| Logo and product image kits | `https://www.surfboardpayments.com/api/kit/index.json` |
| Integration brief for coding agents | `https://surfpay.ai` |
| Developer portal and API reference | `https://developers.surfboardpayments.com/` |

## Errors

Every JSON endpoint on this domain fails in one shape: `{ "error": { "code", "status", "message", "hint", "documentation_url" } }`. Branch on `code`; it is stable. A 404 on a path that does not exist returns the same shape, or a short markdown page if you asked for markdown, listing where to look instead.

## Getting a human

- Sales, partnerships and pricing: https://www.surfboardpayments.com/contact
- Developer support and credentials: https://developers.surfboardpayments.com/
- Press, logos and brand rules: https://www.surfboardpayments.com/presskit