Card API — Contract v1

Status: PUBLISHED — finalized 2026-08-26. Every section was reconciled against the running implementation and executed live on the sandbox (api.sbx.oxen.finance), end to end: onboarding, cardholders, cards, funding, transactions, secrets/PIN, webhooks, events, disputes. Changes from here are additive or announced before they ship; shapes and codes in ✅ sections do not change silently. 🔜 marks contract published for design but not yet callable; the completeness ledger tracks what is still open. The OpenAPI document is published as the API Reference and imports directly into Postman, Insomnia or Bruno.

Conventions (auth, envelope, idempotency, errors, pagination) are defined in the Partner Integration Guide and apply to every endpoint here. Endpoints marked 🔑 require Idempotency-Key.

Resource model

client            cl_…    one end client = one provider company = one collateral pool
├─ cardholder     chd_…   a person under a client (owner is the first; add more via API)
│  └─ card        card_…  virtual | physical
├─ funding        (read-only sub-resource: deposit address + spending power)
└─ documents      (KYB document relay)
transaction       (uuid)  flat query surface — see the exception below
event             evt_…   webhook envelope id (guide §8)

Service ids: opaque, ≤40 chars, prefix + 26-char body. Never parsed. This table is the single authority on public prefixes — it supersedes illustrative prefixes used elsewhere. Partners never see operation ids in v1.

The transaction id is the one identifier here that is NOT an service id (§4): it is the issuer's UUID, carries no prefix, and is the only place a provider identifier reaches you — The service stores no transactions, so it has none of its own to give. A transaction's clientId, cardholderId and cardId are still Service ids. The draft published txn_…; nothing ever minted one.

---

Where each section lives

Section numbers are append-only — §1 is §1 wherever it is printed. This page is the map; each section below is its own page. If you have a #anchor into an older single-page version of this contract written down, find its section here and the anchor still works on that page.

§	Section	Page
1	Onboarding — the client application, KYB documents, UBOs	Onboarding
1	Collateral — funding, contract coordinates, withdrawal	Collateral & withdrawal
2	Cardholders	Cardholders & cards
3	Cards	Cardholders & cards
4	Transactions	Transactions
5	Card secrets & PIN	Secrets & PIN
6	Events	Events
7	Error codes added by this contract	Error codes
8	Disputes	Disputes

§1 is the only section printed on two pages. It carried both the client application and the money path — a review that runs for days, and a signature that moves collateral — and those are read by different people at different times, so each got a page it can be held open on alone. The section number did not change; only the page it is printed on did.

Conventions that apply to every section — authentication, the response envelope, idempotency, retry safety, pagination, rate limits — are in the Partner Integration Guide, not here.

---

Contract completeness ledger

Deferred details, each with its publication gate. An endpoint flips 🔜→✅ in the guide only when its rows here are cleared.

Pending item	Publishes with
Client field-level required/optional matrices — COMPANY ✅ republished 2026-08-24 with issuer-shaped flattened person fields; INDIVIDUAL still pending	INDIVIDUAL build
Document type enum	✅ 2026-08-24 — company uploads retain 12 issuer values (compliance currently clears two); UBO uploads publish the issuer's separate 19-value person enum
Full application-status fidelity end to end	✅ 2026-08-22 — all eleven issuer states map 1:1 provider→contract. The 2026-08-19 check saw only the eight values in the issuer's published schema; the live guide adds notStarted, tosNotAccepted, and exempt, and live sandbox census found two notStarted companies.
Physical-card shipping fields	✅ 2026-08-21 — required-when-PHYSICAL, verified against a live issuance
Physical-card activation	Open — sandbox issues physical cards straight to ACTIVE, so no activation step has been observed. If a production programme returns notActivated, an activation endpoint publishes with it.
Transactions field finalization	✅ 2026-08-22 — all eight kinds published in §4, mapped from the issuer's live reference. Funding remains open.
Funding read (GET /clients/:id/funding)	✅ 2026-08-26 — published as Beta: shapes, network vocabulary (sandbox chains), signed spendingPower, FUNDING_* error rows, rate limits, polling-required guidance. Still open: production network labels (per-chain dated evidence) and production end-to-end enforcement verification (the decline battery), which clears the Beta marker.
Secrets cipher parameters (AES mode, encodings, PIN-block format) & session TTL	✅ 2026-08-22 — published in §5, sourced from the issuer's own reference
Per-event data payload schemas	webhooks feature
Automated resolution of parked operations — a 502 on replace blocks that card until an operator clears it by hand (§3)	reconciliation sweep