Developer Docs v2026.8.2

🤖 Machine-Readable Everything

Category: Developer Experience

Everything an agent needs was already documented; nothing said so in a format a machine reads. This publishes the missing half.

• OpenAPI in two documents. /openapi.json describes this domain’s public surface — 32 operations, no credentials. /openapi/carbon.json describes the payments API — 148 operations over 107 paths, generated from the reference so it cannot drift from it. Both are served as YAML too, and both pass redocly lint
• The Carbon base URL stays a server variable: it is issued per account in the console, so there is no host to publish and an agent must not guess one
• /.well-known/mcp is a live MCP server over Streamable HTTP, stateless and unauthenticated, exposing the same five tools as the npm package over the same corpus
• /agent-instructions.md says when to reach for Surfboard Payments and when not to, in the order an integration actually happens
• /developers/mcp exists so the server and the specs can be found by name rather than by guessing a URL

🧯 Errors That Say What To Do

Category: Developer Experience

• Every JSON endpoint now fails in one shape — { error: { code, status, message, hint } } — with a code to branch on and a hint that says what to do about it
• 404s answer in the caller’s language: a browser gets the designed page, a fetcher or crawler gets markdown pointing at llms.txt, the sitemap and the spec, and anything under an API prefix gets JSON

📊 Reports and Payouts, Reconciled

Category: Documentation

Partners kept asking why a monthly report and the payouts inside that month never agree, and the answer kept being given one thread at a time.

• One rule: the monthly report follows the transaction date, the payouts breakdown follows the payout date, and payouts lag transactions by two to three days
• A three-row table showing a transaction on 30 April, one mid-month, and one on 31 May, and which month each lands in under both views
• Verified against settlement data before it was written down

🎨 Portal Guides

Category: Documentation

• The merchant and partner portal guides now use the same rail as the developer guides — a list against a hairline, with independent scroll, scrollspy, and scroll-into-view on long rails