API conventions
The merchant API is versioned under /v1 and uses JSON request and response bodies. Stable resource identifiers are separate from public checkout tokens and human-readable references.
Validate status codes and typed response bodies rather than assuming every 2xx has the same shape. Keep the SDK at your server boundary so privileged merchant credentials are not exposed in browser code.
Invoices and checkout
Create and issue invoices, generate public checkout links, inspect payment attempts, cancel unpaid invoices, and poll checkout status without exposing internal identifiers.
Create the customer and settlement configuration first, then create an invoice with exact base-unit expectations. Issuing freezes the payment request and produces the public checkout surface used by the payer.
POST /v1/invoices
POST /v1/invoices/{invoiceId}/issue
GET /pay/{checkoutToken}/statusCustomers and settlement wallets
Customer records group merchant references and invoices. Settlement-wallet records define the public Solana destination that an invoice may expect; they do not contain signing material.
Deactivate or replace configuration through explicit state transitions. Historical invoice evidence continues to reference the settlement facts that were active when the invoice was issued.
Exceptions and evidence
List reviewable payment exceptions, assign and resolve them through explicit state transitions, and download evidence packs or accounting exports.
Resolution is an operator decision with an audit trail, not an edit to raw transfer facts. Evidence exports let finance trace invoice expectation, finalized transfer, rule version, decision, event, and delivery history.
GET /v1/exceptions
POST /v1/exceptions/{id}/resolve
GET /v1/evidence-packs/{invoiceId}Operations
Readiness, production controls, incident state, and promotion checks are exposed separately from merchant workflows.
Use these endpoints for deployment gates and operator dashboards, not customer checkout. A production promotion should prove database migrations, supported network and mint configuration, webhook health, and required operational ownership.
Errors, retries, and idempotency
Bounded validation errors should be corrected by the caller and not retried blindly. Temporary service failures may be retried with backoff when the operation is idempotent or carries a stable request identity.
For webhook-driven state changes, deduplicate by event ID. For invoice creation and operational actions, preserve your own stable correlation identifier so a client timeout does not cause duplicate business records.