{ "openapi": "3.1.0", "info": { "title": "Surfboard Payments, public site API", "version": "1.0.0", "summary": "Everything www.surfboardpayments.com serves to machines: content, brand assets, discovery documents and an MCP endpoint.", "description": "This is the public, unauthenticated surface of www.surfboardpayments.com. No key, no signup, no rate limit on the GET endpoints. CORS is open, so a browser agent can call it directly.\n\nIt is not the payments API. Taking a payment means the Carbon API, which is credentialed per account and described separately at /openapi/carbon.json. If you are here to build an integration, start with /agent-instructions.md.\n\nTwo rules worth knowing before you call anything:\n\n- Paths are case-sensitive and JSON endpoints keep their `.json` suffix.\n- Every failure, including a 404 on a path that does not exist, returns the Error schema with a `code` you can branch on.", "termsOfService": "https://www.surfboardpayments.com/terms-and-conditions", "contact": { "name": "Surfboard Payments", "url": "https://www.surfboardpayments.com/contact" }, "license": { "name": "Terms of use", "url": "https://www.surfboardpayments.com/terms-and-conditions" } }, "servers": [ { "url": "https://www.surfboardpayments.com", "description": "Production. The apex domain 301s here, path preserved." } ], "security": [], "externalDocs": { "description": "Developer portal and API reference", "url": "https://developers.surfboardpayments.com/" }, "tags": [ { "name": "Discovery", "description": "Start here: what exists on this domain and where." }, { "name": "Content", "description": "The site as data: company, products, capabilities, solutions, methods, articles." }, { "name": "Developer", "description": "The API reference, the integration guides, and search over both." }, { "name": "Brand", "description": "Brand guidelines and the asset kits cleared for outside use." }, { "name": "Agents", "description": "Instructions, skills and the MCP endpoint." } ], "paths": { "/api/ai/site-overview.json": { "get": { "operationId": "getSiteOverview", "summary": "Site overview, sitemap and company facts", "description": "The single best first call. Returns the company record, every public page grouped by section, the supported payment methods, and the URL of every other machine-readable resource on this domain. Call this before crawling: it replaces walking the sitemap.", "tags": [ "Content" ], "responses": { "200": { "description": "The site overview.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteOverview" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/company.json": { "get": { "operationId": "getCompany", "summary": "Company record", "description": "Legal entity, founding year, offices with addresses, leadership and board, licensing authority and licence type, certifications, infrastructure, partnerships and contact routes. Use this to answer \"who are Surfboard Payments\" without scraping the about page.", "tags": [ "Content" ], "responses": { "200": { "description": "The company record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/products.json": { "get": { "operationId": "listProducts", "summary": "Product catalogue", "description": "Every product, grouped by category: payment terminals, Tap to Pay on iPhone and Android, online checkout, and accessories. Each product carries its features, hardware specs and market availability. Use this to answer which device or product fits a described situation.", "tags": [ "Content" ], "responses": { "200": { "description": "The product catalogue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCatalogue" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/platform.json": { "get": { "operationId": "listPlatformCapabilities", "summary": "Platform capabilities", "description": "Every capability the platform exposes, from tokenization and offline payments to tipping, receipts and webhooks, each with the page that documents it. Use this to check whether something is supported before promising it.", "tags": [ "Content" ], "responses": { "200": { "description": "The capability list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformCapabilities" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/solutions.json": { "get": { "operationId": "listSolutions", "summary": "Solutions by industry and by audience", "description": "The industry solutions (retail, hospitality, healthcare, and the rest) and the audience solutions (ISVs, POS providers, marketplaces). Use this to map a described business onto the closest documented fit.", "tags": [ "Content" ], "responses": { "200": { "description": "The solution list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Solutions" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/payment-methods.json": { "get": { "operationId": "listPaymentMethods", "summary": "Supported payment methods", "description": "Every supported payment method with the countries and channels it covers, when to use it, and the three paths to switching it on (Partner Portal, Merchant Portal, Payment Methods API). Use this to answer \"can I take X in country Y\".", "tags": [ "Content" ], "responses": { "200": { "description": "The payment method list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethods" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/docs.json": { "get": { "operationId": "getApiReference", "summary": "Carbon API reference, every endpoint", "description": "The full API reference as data: every documented endpoint with its method, path, description and complete reference page in markdown. For a typed contract instead of prose, read the OpenAPI document at /openapi/carbon.json.", "tags": [ "Developer" ], "responses": { "200": { "description": "The API reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReference" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/guides.json": { "get": { "operationId": "listDeveloperGuides", "summary": "Integration guides", "description": "Every integration guide with its full markdown body: creating orders, taking payments, refunds, webhooks, SDKs, onboarding, terminal management. This is the corpus to ground an integration on. Large: fetch one guide instead when you know which you need.", "tags": [ "Developer" ], "responses": { "200": { "description": "Every guide, with bodies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperGuides" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/guides/{slug}.md": { "get": { "operationId": "getDeveloperGuideMarkdown", "summary": "One integration guide as markdown", "description": "The markdown source of a single guide, which is the cheap way to read one without pulling the whole collection. Slugs come from listDeveloperGuides. The same bytes are served at /developers/guides/{slug}.md.", "tags": [ "Developer" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Guide slug, from listDeveloperGuides.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "example": "create-an-order" } ], "responses": { "200": { "description": "The guide as markdown.", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/changelog.json": { "get": { "operationId": "getChangelog", "summary": "Product changelog", "description": "Release notes for every product, newest first, with version, build and full body. Use this to check whether a feature has shipped and in which version.", "tags": [ "Developer" ], "responses": { "200": { "description": "The changelog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changelog" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/knowledge-hub.json": { "get": { "operationId": "listKnowledgeHubArticles", "summary": "Knowledge hub articles", "description": "Every published article with its full body: payments explainers, market and regulation pieces, product launches and company news. Use this for background and for citable company statements.", "tags": [ "Content" ], "responses": { "200": { "description": "Every article, with bodies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeHub" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/partner-portal.json": { "get": { "operationId": "listPartnerPortalGuides", "summary": "Partner Portal guides", "description": "How-to guides for the Partner Portal: onboarding merchants, applications, billing plans, branding, terminals, shipments, reporting. Use this for questions about operating a partner account rather than about the API.", "tags": [ "Content" ], "responses": { "200": { "description": "Every Partner Portal guide, with bodies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerPortalGuides" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/merchant-portal.json": { "get": { "operationId": "listMerchantPortalGuides", "summary": "Merchant Portal guides", "description": "How-to guides for the Merchant Portal: dashboard, sales and reports, payment links, gift cards, products, stores, terminals, user levels. Use this for questions a merchant would ask.", "tags": [ "Content" ], "responses": { "200": { "description": "Every Merchant Portal guide, with bodies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPortalGuides" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/brand.json": { "get": { "operationId": "getBrandGuidelines", "summary": "Brand guidelines", "description": "Logo files and placement rules, the colour palette with its approved contrast pairings, typography, product naming, tone of voice, imagery rules and press boilerplate. Read this before generating anything that represents Surfboard Payments: a deck, a landing page, a badge, a press line.", "tags": [ "Brand" ], "responses": { "200": { "description": "The brand guidelines.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandGuidelines" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brand.md": { "get": { "operationId": "getBrandGuidelinesMarkdown", "summary": "Brand guidelines as markdown", "description": "The same guidelines as getBrandGuidelines, as one markdown document, for pasting into a prompt.", "tags": [ "Brand" ], "responses": { "200": { "description": "The brand guidelines as markdown.", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/kit/index.json": { "get": { "operationId": "listDownloadKits", "summary": "Download kits", "description": "Logo and product image kits cleared for partner and press use, with the URL templates for each kit manifest, zip and file.", "tags": [ "Brand" ], "responses": { "200": { "description": "Every kit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KitIndex" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/kit/{slug}.json": { "get": { "operationId": "getDownloadKit", "summary": "One kit manifest", "description": "Every file in one kit, each with a caption saying what it is and when to use it. Slugs come from listDownloadKits: a product slug, or \"brand\" for the logo kit.", "tags": [ "Brand" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kit slug, from listDownloadKits.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "example": "brand" } ], "responses": { "200": { "description": "The kit manifest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KitManifest" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/kit/{slug}.zip": { "get": { "operationId": "downloadKitArchive", "summary": "One kit as a zip", "description": "The whole kit as a zip, including a README carrying the usage terms.", "tags": [ "Brand" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kit slug, from listDownloadKits.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "example": "brand" } ], "responses": { "200": { "description": "The zip archive.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/kit/{slug}/{filename}": { "get": { "operationId": "downloadKitFile", "summary": "One file from a kit", "description": "A single asset, served as an attachment. Filenames come from getDownloadKit.", "tags": [ "Brand" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Kit slug, from listDownloadKits.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "example": "brand" }, { "name": "filename", "in": "path", "required": true, "description": "File name exactly as listed in the kit manifest, extension included.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]+$" }, "example": "surfboard-payments-primary.svg" } ], "responses": { "200": { "description": "The file.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/index.json": { "get": { "operationId": "getApiIndex", "summary": "Index of every endpoint on this domain", "description": "A flat listing of the endpoints in this spec, grouped by purpose. Human-first; prefer this spec for tooling.", "tags": [ "Discovery" ], "responses": { "200": { "description": "The endpoint index.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/llms.txt": { "get": { "operationId": "getLlmsTxt", "summary": "Site map for language models", "description": "The llms.txt document: the whole site as one markdown file, with a link and a one-line description for every page, plus when to use Surfboard Payments and how an agent should call it. Start here if you would otherwise crawl.", "tags": [ "Discovery" ], "responses": { "200": { "description": "The llms.txt document.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/llms-full.txt": { "get": { "operationId": "getLlmsFullTxt", "summary": "Full content dump for language models", "description": "Every page, guide and article as one markdown file. Large. Use getLlmsTxt first and fetch what you need.", "tags": [ "Discovery" ], "responses": { "200": { "description": "The full content dump.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-instructions.md": { "get": { "operationId": "getAgentInstructions", "summary": "When to use Surfboard Payments, and how to call it", "description": "The agent instruction file: the jobs Surfboard Payments is the right answer for, the ones it is not, the order to do an integration in, the safety rules that apply to payments work, and which endpoint or tool to reach for at each step.", "tags": [ "Agents" ], "responses": { "200": { "description": "The agent instructions as markdown.", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApiSpec", "summary": "This document", "description": "The OpenAPI 3.1 description of this domain. Served as YAML at /openapi.yaml.", "tags": [ "Discovery" ], "responses": { "200": { "description": "This OpenAPI document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/openapi/carbon.json": { "get": { "operationId": "getCarbonOpenApiSpec", "summary": "OpenAPI spec for the Carbon payments API", "description": "The OpenAPI 3.1 description of the Carbon API, the credentialed payments API behind terminals, orders, payments, merchants and webhooks. Generated from the published reference. Served as YAML at /openapi/carbon.yaml.", "tags": [ "Discovery" ], "responses": { "200": { "description": "The Carbon API OpenAPI document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/api-catalog": { "get": { "operationId": "getApiCatalog", "summary": "RFC 9727 API catalog", "description": "A linkset naming the service documentation and every machine-readable resource on this domain.", "tags": [ "Discovery" ], "responses": { "200": { "description": "The linkset.", "content": { "application/linkset+json": { "schema": { "$ref": "#/components/schemas/ApiCatalog" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/agent-skills/index.json": { "get": { "operationId": "getAgentSkillsIndex", "summary": "Agent Skills index", "description": "The skills published for this site, each a markdown file with a SHA-256 so it can be verified after download. Install them, or fetch and read them directly.", "tags": [ "Agents" ], "responses": { "200": { "description": "The skills index.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSkillsIndex" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/agent-skills/{skill}/SKILL.md": { "get": { "operationId": "getAgentSkill", "summary": "One agent skill", "description": "The markdown body of one skill. Names come from getAgentSkillsIndex.", "tags": [ "Agents" ], "parameters": [ { "name": "skill", "in": "path", "required": true, "description": "Skill name, from getAgentSkillsIndex.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "example": "surfboard-overview" } ], "responses": { "200": { "description": "The skill as markdown.", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/mcp/server-card.json": { "get": { "operationId": "getMcpServerCard", "summary": "MCP server card", "description": "How to reach the documentation MCP server: the hosted Streamable HTTP endpoint, the npm package for a stdio client, and the tools it exposes.", "tags": [ "Agents" ], "responses": { "200": { "description": "The server card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerCard" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/mcp": { "get": { "operationId": "describeMcpEndpoint", "summary": "Describe the MCP endpoint", "description": "A GET on the MCP endpoint returns the same server card, so a client that has only the URL can learn what it is talking to before opening a session. A GET asking for text/event-stream returns 405: this server answers over JSON, not a server-initiated stream.", "tags": [ "Agents" ], "responses": { "200": { "description": "The server card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerCard" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Sent for a GET that asks for text/event-stream. Use POST.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "callMcpEndpoint", "summary": "Call the MCP server (Streamable HTTP)", "description": "The Model Context Protocol endpoint, Streamable HTTP transport. POST a JSON-RPC 2.0 message: initialize to open a session, tools/list to enumerate tools, tools/call to run one. Responses come back as a single JSON object rather than an SSE stream. Tools cover the API reference, the webhook catalog and the integration guides.", "tags": [ "Agents" ], "requestBody": { "required": true, "description": "A JSON-RPC 2.0 request or notification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } } }, "responses": { "200": { "description": "The JSON-RPC response. Notifications get 202 with an empty body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "202": { "description": "The message was a notification, so there is nothing to return." }, "400": { "description": "The body was not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developer-search": { "post": { "operationId": "searchDeveloperDocs", "summary": "Ask a question about the developer docs", "description": "Natural-language search across the integration guides and the API reference. Returns a Server-Sent Events stream of answer tokens, terminated by \"data: [DONE]\". Rate limited per IP. An agent that can run MCP should prefer callMcpEndpoint, which returns whole documents rather than a prose answer.", "tags": [ "Developer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "minLength": 1, "description": "The question, in plain language." }, "messages": { "type": "array", "description": "Prior turns, oldest first, for a follow-up question.", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "An SSE stream of answer tokens.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "The body was not valid JSON, or question was missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No resource at this path. The body names where to look instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests from this address. Retry-After says when to come back.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Search is not configured on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "description": "Every failed request on this domain returns this shape. Branch on error.code, which is stable; error.message and error.hint are written for a human or an agent to read.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message", "hint" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Does not change for a given condition.", "enum": [ "not_found", "method_not_allowed", "invalid_request", "invalid_json", "unsupported_media_type", "rate_limited", "upstream_error", "internal_error", "not_configured" ] }, "status": { "type": "integer", "description": "The HTTP status, repeated in the body." }, "message": { "type": "string", "description": "What went wrong." }, "hint": { "type": "string", "description": "What to do about it." }, "documentation_url": { "type": "string", "format": "uri" }, "details": { "description": "Field-level detail, present on validation failures." } } } } }, "SiteOverview": { "type": "object", "description": "Company facts, the full sitemap, and pointers to every other machine-readable resource.", "required": [ "name", "description", "url", "sitemap", "aiEndpoints", "lastUpdated" ], "properties": { "name": { "type": "string" }, "tagline": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "founded": { "type": "integer" }, "headquarters": { "type": "string" }, "industry": { "type": "string" }, "regulation": { "type": "string", "description": "Licensing authority and licence type." }, "certifications": { "type": "array", "items": { "type": "string" } }, "infrastructure": { "type": "string" }, "uptime": { "type": "string" }, "setupRecord": { "type": "string" }, "employees": { "type": "string" }, "marketsServed": { "type": "array", "items": { "type": "string" }, "description": "Countries where merchants can be boarded." }, "offices": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "address": { "type": "string" } } } }, "keyPeople": { "type": "object", "additionalProperties": { "type": "string" } }, "pricing": { "type": "object", "additionalProperties": true }, "sitemap": { "type": "object", "description": "Every public page, grouped by section.", "additionalProperties": true }, "externalLinks": { "type": "object", "additionalProperties": { "type": "string" } }, "aiEndpoints": { "type": "object", "description": "The other JSON endpoints in this spec, keyed by name.", "additionalProperties": true }, "paymentMethodActivation": { "type": "object", "additionalProperties": true }, "supportedPaymentMethods": { "type": "array", "items": { "type": "string" } }, "lastUpdated": { "type": "string", "format": "date" } } }, "Company": { "type": "object", "description": "Structured company record: legal entity, offices, leadership, licensing, certifications, partnerships.", "required": [ "name", "legalName", "founded", "regulation", "lastUpdated" ], "properties": { "name": { "type": "string" }, "legalName": { "type": "string" }, "founded": { "type": "integer" }, "type": { "type": "string" }, "industry": { "type": "string" }, "description": { "type": "string" }, "mission": { "type": "string" }, "headquarters": { "type": "object", "additionalProperties": true }, "offices": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "employees": { "type": "string" }, "leadership": { "type": "object", "additionalProperties": true }, "boardMembers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string" } } } }, "regulation": { "type": "object", "additionalProperties": true }, "certifications": { "type": "array", "items": { "type": "string" } }, "infrastructure": { "type": "object", "additionalProperties": true }, "financials": { "type": "object", "additionalProperties": true }, "partnerships": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "targetMarket": { "type": "object", "additionalProperties": true }, "socialResponsibility": { "type": "object", "additionalProperties": true }, "contact": { "type": "object", "additionalProperties": true }, "lastUpdated": { "type": "string", "format": "date" } } }, "ProductCatalogue": { "type": "object", "description": "Terminals, Tap to Pay products, online products and accessories, grouped by category.", "required": [ "categories", "lastUpdated" ], "properties": { "lastUpdated": { "type": "string", "format": "date" }, "pricing": { "type": "object", "additionalProperties": true }, "categories": { "type": "array", "items": { "type": "object", "required": [ "name", "products" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "products": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string", "format": "uri-reference" }, "description": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "specs": { "type": "object", "additionalProperties": { "type": "string" } }, "availability": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "PlatformCapabilities": { "type": "object", "description": "Every platform capability with the page that documents it.", "required": [ "capabilities", "totalCapabilities" ], "properties": { "overviewUrl": { "type": "string", "format": "uri-reference" }, "totalCapabilities": { "type": "integer", "minimum": 0 }, "lastUpdated": { "type": "string", "format": "date" }, "capabilities": { "type": "array", "items": { "type": "object", "required": [ "name", "slug", "url", "description" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string", "format": "uri-reference" }, "description": { "type": "string" } } } } } }, "Solutions": { "type": "object", "description": "Solution pages, split by industry and by audience.", "required": [ "byIndustry", "byAudience" ], "properties": { "overviewUrl": { "type": "string", "format": "uri-reference" }, "totalSolutions": { "type": "integer", "minimum": 0 }, "lastUpdated": { "type": "string", "format": "date" }, "byIndustry": { "type": "array", "items": { "$ref": "#/components/schemas/NamedPage" } }, "byAudience": { "type": "array", "items": { "$ref": "#/components/schemas/NamedPage" } } } }, "NamedPage": { "type": "object", "required": [ "name", "slug", "url", "description" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string", "format": "uri-reference" }, "description": { "type": "string" } } }, "PaymentMethods": { "type": "object", "description": "Supported payment methods, the countries and channels each covers, and how a merchant enables it.", "required": [ "methods", "categories" ], "properties": { "activation": { "type": "object", "description": "The three ways a method gets switched on.", "additionalProperties": true }, "categories": { "type": "array", "items": { "type": "object", "required": [ "id", "label" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } } } }, "methods": { "type": "array", "items": { "type": "object", "required": [ "slug", "name", "category" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri-reference" }, "category": { "type": "string", "description": "Matches a categories[].id." }, "tagline": { "type": "string" }, "oneLiner": { "type": "string" }, "description": { "type": "string" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2, uppercase." }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "in-store", "online", "unattended" ] } }, "whenToUse": { "type": "string" }, "customerBase": { "type": "string" }, "useCases": { "type": "array", "items": { "type": "string" } }, "related": { "type": "array", "items": { "type": "string" } }, "externalUrl": { "type": "string", "format": "uri" } } } }, "indexUrl": { "type": "string", "format": "uri-reference" }, "lastUpdated": { "type": "string", "format": "date" } } }, "ApiReference": { "type": "object", "description": "Every documented Carbon API endpoint with its full reference page as markdown.", "required": [ "totalEndpoints", "apis", "endpoints" ], "properties": { "totalEndpoints": { "type": "integer", "minimum": 0 }, "lastUpdated": { "type": "string", "format": "date" }, "apis": { "type": "array", "items": { "type": "string" }, "description": "API section names, e.g. \"Payments API\"." }, "endpoints": { "type": "array", "items": { "type": "object", "required": [ "title", "slug", "api", "method", "path" ], "properties": { "title": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "api": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "path": { "type": "string", "description": "Path relative to the account base URL, with :params." }, "content": { "type": "string", "description": "The reference page as markdown." } } } } } }, "DeveloperGuides": { "type": "object", "description": "Integration guides, in-store and online.", "required": [ "totalGuides", "lastUpdated", "guides" ], "properties": { "totalGuides": { "type": "integer", "minimum": 0 }, "lastUpdated": { "type": "string", "format": "date", "description": "ISO 8601 date the collection was generated." }, "categories": { "type": "array", "items": { "type": "string" } }, "guides": { "type": "array", "description": "One guide per entry.", "items": { "type": "object", "description": "One document: its metadata plus the full markdown body.", "required": [ "title", "slug", "url", "content" ], "properties": { "title": { "type": "string" }, "slug": { "type": "string", "description": "URL segment, unique within the collection." }, "url": { "type": "string", "format": "uri-reference", "description": "Path to the rendered page." }, "description": { "type": "string" }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "content": { "type": "string", "description": "The full document body as markdown." } } } } } }, "PartnerPortalGuides": { "type": "object", "description": "Partner Portal how-to guides.", "required": [ "totalGuides", "lastUpdated", "guides" ], "properties": { "totalGuides": { "type": "integer", "minimum": 0 }, "lastUpdated": { "type": "string", "format": "date", "description": "ISO 8601 date the collection was generated." }, "categories": { "type": "array", "items": { "type": "string" } }, "guides": { "type": "array", "description": "One guide per entry.", "items": { "type": "object", "description": "One document: its metadata plus the full markdown body.", "required": [ "title", "slug", "url", "content" ], "properties": { "title": { "type": "string" }, "slug": { "type": "string", "description": "URL segment, unique within the collection." }, "url": { "type": "string", "format": "uri-reference", "description": "Path to the rendered page." }, "description": { "type": "string" }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "content": { "type": "string", "description": "The full document body as markdown." } } } } } }, "MerchantPortalGuides": { "type": "object", "description": "Merchant Portal how-to guides.", "required": [ "totalGuides", "lastUpdated", "guides" ], "properties": { "totalGuides": { "type": "integer", "minimum": 0 }, "lastUpdated": { "type": "string", "format": "date", "description": "ISO 8601 date the collection was generated." }, "categories": { "type": "array", "items": { "type": "string" } }, "guides": { "type": "array", "description": "One guide per entry.", "items": { "type": "object", "description": "One document: its metadata plus the full markdown body.", "required": [ "title", "slug", "url", "content" ], "properties": { "title": { "type": "string" }, "slug": { "type": "string", "description": "URL segment, unique within the collection." }, "url": { "type": "string", "format": "uri-reference", "description": "Path to the rendered page." }, "description": { "type": "string" }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "content": { "type": "string", "description": "The full document body as markdown." } } } } } }, "Changelog": { "type": "object", "description": "Release notes for every product, newest first.", "required": [ "totalEntries", "entries" ], "properties": { "totalEntries": { "type": "integer", "minimum": 0 }, "lastUpdated": { "type": "string", "format": "date" }, "products": { "type": "array", "items": { "type": "string" } }, "entries": { "type": "array", "items": { "type": "object", "required": [ "title", "slug", "product", "version", "date" ], "properties": { "title": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string", "format": "uri-reference" }, "product": { "type": "string" }, "version": { "type": "string" }, "build": { "type": [ "string", "null" ] }, "date": { "type": "string", "format": "date" }, "summary": { "type": "string" }, "content": { "type": "string", "description": "The release note as markdown." } } } } } }, "KnowledgeHub": { "type": "object", "description": "Published articles on payments, technology and company news, with full bodies.", "required": [ "totalArticles", "articles" ], "properties": { "totalArticles": { "type": "integer", "minimum": 0 }, "lastUpdated": { "type": "string", "format": "date" }, "categories": { "type": "array", "items": { "type": "string" } }, "articles": { "type": "array", "items": { "type": "object", "required": [ "title", "slug", "url", "date" ], "properties": { "title": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string", "format": "uri-reference" }, "date": { "type": "string", "format": "date" }, "dateModified": { "type": [ "string", "null" ], "format": "date" }, "blurb": { "type": "string" }, "author": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "coverImage": { "type": "string", "format": "uri" }, "content": { "type": "string", "description": "The article as markdown." } } } } } }, "BrandGuidelines": { "type": "object", "description": "The rules for representing Surfboard Payments: logo files and placement, colour palette with contrast pairings, typography, product naming, voice, imagery, and press boilerplate.", "required": [ "name", "instructions", "logo", "color", "typography" ], "properties": { "$schema": { "type": "string", "format": "uri" }, "name": { "type": "string" }, "description": { "type": "string" }, "instructions": { "type": "array", "items": { "type": "string" }, "description": "Read these first. They are the rules an agent generating brand material must follow." }, "naming": { "type": "object", "additionalProperties": true }, "logo": { "type": "object", "additionalProperties": true }, "color": { "type": "object", "additionalProperties": true }, "typography": { "type": "object", "additionalProperties": true }, "voice": { "type": "object", "additionalProperties": true }, "imagery": { "type": "object", "additionalProperties": true }, "boilerplate": { "type": "object", "additionalProperties": true }, "usage": { "type": "object", "additionalProperties": true }, "contact": { "type": "object", "additionalProperties": true }, "lastUpdated": { "type": "string", "format": "date" } } }, "KitIndex": { "type": "object", "description": "Every download kit, with the URL templates for its manifest, zip and individual files.", "required": [ "kits", "routes" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "routes": { "type": "object", "properties": { "manifest": { "type": "string", "description": "URL template, {slug} substituted." }, "zip": { "type": "string" }, "file": { "type": "string" } } }, "brand": { "type": "string", "format": "uri" }, "kits": { "type": "array", "items": { "type": "object", "required": [ "slug", "name", "assetCount", "manifest" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "assetCount": { "type": "integer", "minimum": 0 }, "page": { "type": "string", "format": "uri" }, "manifest": { "type": "string", "format": "uri" } } } } } }, "KitManifest": { "type": "object", "description": "One kit: every file in it, with a caption saying what the file is for.", "required": [ "slug", "assets", "downloadAll" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "page": { "type": "string", "format": "uri" }, "downloadAll": { "type": "string", "format": "uri", "description": "The whole kit as a zip." }, "assetCount": { "type": "integer", "minimum": 0 }, "assets": { "type": "array", "items": { "type": "object", "required": [ "file", "download", "format" ], "properties": { "file": { "type": "string" }, "caption": { "type": "string", "description": "What this file is, and when to reach for it." }, "kind": { "type": "string" }, "format": { "type": "string", "enum": [ "svg", "png", "jpg", "webp", "pdf" ] }, "download": { "type": "string", "format": "uri" }, "source": { "type": "string", "format": "uri" } } } } } }, "ApiIndexGroup": { "type": "object", "description": "One group of endpoints in the plain index.", "properties": { "description": { "type": "string" }, "endpoints": { "type": "array", "items": { "type": "object", "required": [ "path", "method" ], "properties": { "path": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "description": { "type": "string" } } } } } }, "ApiIndex": { "type": "object", "description": "A plain listing of every endpoint on this domain, grouped by purpose.", "required": [ "name", "ai" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "ai": { "$ref": "#/components/schemas/ApiIndexGroup" }, "kits": { "$ref": "#/components/schemas/ApiIndexGroup" }, "llm": { "$ref": "#/components/schemas/ApiIndexGroup" }, "developer": { "$ref": "#/components/schemas/ApiIndexGroup" }, "internal": { "$ref": "#/components/schemas/ApiIndexGroup" } }, "additionalProperties": { "type": "object", "properties": { "description": { "type": "string" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "method": { "type": "string" }, "description": { "type": "string" } } } } } } }, "JsonRpcRequest": { "type": "object", "description": "A JSON-RPC 2.0 request as defined by the Model Context Protocol.", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "description": "Omit for notifications. Present for requests that expect a response.", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "method": { "type": "string", "description": "One of initialize, tools/list, tools/call, ping, or notifications/initialized.", "examples": [ "initialize", "tools/list", "tools/call", "ping" ] }, "params": { "type": "object", "additionalProperties": true } } }, "JsonRpcResponse": { "type": "object", "description": "A JSON-RPC 2.0 response. Either result or error is present, never both.", "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "result": { "type": "object", "additionalProperties": true }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "description": "JSON-RPC error code, e.g. -32601 for an unknown method." }, "message": { "type": "string" }, "data": {} } } } }, "McpServerCard": { "type": "object", "description": "Describes the MCP server: how to install it, how to reach it over HTTP, and which tools it exposes.", "required": [ "serverInfo", "capabilities" ], "properties": { "$schema": { "type": "string", "format": "uri" }, "serverInfo": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" } } }, "transport": { "type": "object", "additionalProperties": true }, "transports": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "endpoint": { "type": [ "string", "null" ], "format": "uri", "description": "The Streamable HTTP endpoint, or null for a stdio-only server." }, "capabilities": { "type": "object", "additionalProperties": true }, "documentation": { "type": "string", "format": "uri" }, "repository": { "type": "string", "format": "uri" }, "homepage": { "type": "string", "format": "uri" } } }, "ApiCatalog": { "type": "object", "description": "RFC 9727 linkset naming the service docs and the machine-readable resources on this domain.", "required": [ "linkset" ], "properties": { "linkset": { "type": "array", "items": { "type": "object", "required": [ "anchor" ], "properties": { "anchor": { "type": "string", "format": "uri", "description": "The resource the links below belong to." } }, "additionalProperties": true } } } }, "AgentSkillsIndex": { "type": "object", "description": "Agent Skills index: each skill is a markdown file with a SHA-256 so it can be verified after download.", "required": [ "version", "skills" ], "properties": { "$schema": { "type": "string", "format": "uri" }, "version": { "type": "string" }, "skills": { "type": "array", "items": { "type": "object", "required": [ "name", "url", "sha256" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "prompt" ] }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } } } }, "OpenApiDocument": { "type": "object", "description": "An OpenAPI 3.1 document.", "required": [ "openapi", "info", "paths" ], "properties": { "openapi": { "type": "string" }, "info": { "type": "object", "additionalProperties": true }, "servers": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "paths": { "type": "object", "additionalProperties": true }, "components": { "type": "object", "additionalProperties": true } } } } }, "x-mcp": { "endpoint": "https://www.surfboardpayments.com/.well-known/mcp", "transport": "streamable-http", "serverCard": "https://www.surfboardpayments.com/.well-known/mcp/server-card.json" }, "x-agent-instructions": "https://www.surfboardpayments.com/agent-instructions.md" }