API reference

The machine-readable spec is at /api/v1/openapi.json. Load it into any OpenAPI viewer (Swagger UI, Stoplight, Postman, Insomnia) to explore it.

In sandbox today

SorenPay is in private beta. Every workspace runs in sandbox, and no route moves real money yet.

Conventions

Base URL: https://sorenpay.com
Authenticated requests carry Authorization: Bearer apk_…
Idempotency: routes marked idempotent take an Idempotency-Key header (some require it). A replay within 24 hours returns the first response.
Live mode (not switched on yet): money-movement routes (payouts, international payments, USDC, multi-currency, cards, cardholders, physical cards and agents) require the workspace's business verification to be approved, else 403 kyb_required. Sandbox skips this check.
Inbound webhooks from our partners are checked (signature or shared secret) before we act on them.

Resource	Routes	Status
Workspaces	`POST /api/workspaces`, `GET /api/workspaces`	In sandbox
API keys	`POST/GET/DELETE /api/auth/keys`	In sandbox
Cards	`POST/GET /api/cards`, `GET/PATCH /api/cards/{id}`	In sandbox
Cardholders	`POST/GET /api/cardholders`	In sandbox
Physical cards	`POST/GET /api/physical-cards`	In sandbox
Ledger and payouts	`GET /api/treasury`, recipients, payouts, FX quotes	In sandbox
Multi-currency	currency balances, details, quotes, conversions	In sandbox (converting and paying from a balance: Coming soon)
USDC ramp	quotes, orders, withdrawals, wallets	In sandbox
Intl payments (USDC)	quote + originate + lookup	Coming soon (answers `422`)
Agents	register + submit intent + intent log	In sandbox
MCP	JSON-RPC 2.0 endpoint, read-only	In sandbox
Checkout	merchant sessions + customer flow	In sandbox
Webhooks	the webhook we send and how it's signed	In sandbox

Errors are JSON with a machine-readable error code, and often a human-readable message:

{
"error": "<short_machine_code>",
"message": "Optional human-readable message"
}

Status	When
`400`	Bad request body, or a required `Idempotency-Key` is missing
`401`	Missing or invalid `apk_` key
`403`	The key is missing the scope (`missing_scope:<scope>`), or business verification isn't approved on a live request (`kyb_required`)
`404`	Not found, or not in your workspace
`409`	State conflict (for example `cardholder_required`)
`422`	Same `Idempotency-Key` with a different body (`idempotency_key_mismatch`), or the feature isn't available (`capability_unavailable`)
`429`	Rate limit hit (`rate_limited`). Retry after `Retry-After` seconds
`500`	Server error. Retry with the same `Idempotency-Key`
`501`	Not implemented
`503`	`rate_limit_unavailable`: limits couldn't be checked and nothing changed. Retry after `Retry-After` seconds

The OpenAPI spec at /api/v1/openapi.json describes the current surface. While SorenPay is in private beta, routes can still change.