# SB Checkout API

Version: 2026-08-26
Base path: /api/checkout/v1
OpenAPI 3.1: /api/checkout/v1/openapi
Human quickstart: /checkout/docs/api-v1

Use Authorization: Bearer sbck_test_* from a trusted backend. Never expose secret keys in browsers, mobile applications, logs or source control. Send SB-Checkout-Version: 2026-08-26 when pinning the contract.

Every resource-creating POST and every irreversible command requires Idempotency-Key. Reuse a key only for an exact retry. Responses include X-Request-Id; retain it for support and audit correlation.

Resources:
- stores: GET/POST /stores; GET/PATCH /stores/{id}
- products: GET/POST /products; GET/PATCH /products/{id}
- offers: GET/POST /offers; GET/PATCH /offers/{id}
- customers: GET/POST /customers; GET/PATCH /customers/{id}
- sessions: POST /sessions; GET /sessions/{id}
- orders: GET /orders; GET /orders/{orderTokenOrNumber}
- payment methods: GET /payment-methods
- payment intents: GET/POST /payment-intents; GET /payment-intents/{id}; POST /payment-intents/{id}/confirm; POST /payment-intents/{id}/cancel; POST /payment-intents/{id}/capture
- refunds: GET/POST /payment-intents/{id}/refunds; GET/POST /orders/{orderTokenOrNumber}/refunds
- disputes: POST /payment-intents/{id}/disputes; GET /disputes; POST /disputes/{id}/resolve
- settlements: GET /settlements
- payouts: POST /settlements/{id}/payouts
- payment links: GET/POST /payment-links; GET /payment-links/{id}; POST /payment-links/{id}/deactivate
- webhooks: GET/POST /webhook-endpoints; GET/PATCH /webhook-endpoints/{id}; POST /webhook-endpoints/{id}/rotate-secret; GET /webhook-deliveries

Webhook verification uses the exact raw request bytes, X-SB-Checkout-Timestamp and the v1 HMAC-SHA256 signature. Deduplicate by event.id and reject stale timestamps. Secret rotation can temporarily emit signatures for both the current and previous secret.

TEST and LIVE credentials and data paths are isolated. Never infer payment or settlement from a browser redirect. Use order retrieval and signed events. LIVE financial execution may remain fail-closed even when the API and TEST catalog are available.

Current SB Pay lifecycle boundary:
- TEST advertises manual capture, full/partial refunds, dispute simulation and payout simulation.
- LIVE advertises none of those capabilities until a provider-backed adapter implements and proves each command.
- Unsupported lifecycle commands return HTTP 422 with a stable capability code before financial state is mutated.
- Capture, refund, dispute and payout routes require a secret server key and must never be called by the browser SDK.

Checkout payment boundaries:
- PIX accepts BRL. SB Pay uses the linked SB Bank account. Card accepts EUR and USD; MB WAY and Revolut Pay accept EUR.
- Use only methods whose availability is true for the current session, mode and currency.
- TEST payment simulation is separate from LIVE balances and payment execution.
- PAN, CVC, PIN and magnetic-track data must never be sent to SB Checkout APIs, logs or webhooks. Use the hosted secure checkout for customer confirmation.
- A successful payment can remain PENDING until reconciliation and the active settlement policy permit release. Reserves and release times are policy-controlled.
- The seller tariff is snapshotted when the payment starts. Refund and dispute operations retain that financial snapshot.
- Full and partial refunds are available only when explicitly advertised. Do not assume manual capture or recurring payments are supported.
- Signed webhook notifications and payment retrieval are the source of payment status. Never mark an order paid from a browser callback alone.

Custom checkout:
1. From your trusted backend, POST /payment-intents with offerPublicToken, customer and exact allowedOrigins.
2. Return only paymentIntent.clientSecret to that allowed browser origin. Never return sbck_*.
3. Load /checkout/sdk/v1/sb-checkout.js and initialize SBCheckout with the client secret.
4. Retrieve methods, confirm with a unique Idempotency-Key and handle the returned state machine.
5. Use the hosted SB Checkout payment page for card and wallet confirmation. Never proxy credentials or card fields through your backend.
6. For a rail that advertises MANUAL capture, wait for REQUIRES_CAPTURE and call /payment-intents/{id}/capture from your trusted backend only. Card payments advertise automatic capture only.
7. Treat PROCESSING and ambiguous outcomes as non-retryable until retrieval or a signed webhook provides the final state.

Client OpenAPI 3.1: /api/checkout/client/v1/openapi
Browser SDK: /checkout/sdk/v1/sb-checkout.js