API reference
API overview
The Checkout API is a REST API. It takes JSON request bodies, returns JSON, uses standard HTTP status codes, and authenticates with a secret key.
Base URLs
| Environment | Base URL | Keys |
|---|---|---|
| Live | https://api.saphra.one/v1 | sk_live_… |
| Sandbox | https://sandbox.api.saphra.one/v1 | sk_test_… |
Endpoints
| Method | Path | Does |
|---|---|---|
| POST | /v1/checkout/sessions | Create a checkout session |
| GET | /v1/checkout/sessions/{id} | Retrieve a session |
| GET | /v1/checkout/sessions | List sessions |
| POST | /v1/checkout/sessions/{id}/expire | Expire an unpaid session |
Requests
- Send bodies as JSON with
Content-Type: application/json. A body that isn’t a JSON object is refused withbody_invalid. - Money is always a decimal string, such as
"25.00", with up to six decimal places. Numbers are refused so no amount is ever rounded by a float. - Unknown fields are ignored, so adding fields later never breaks you.
- Ids are case-insensitive and look like
cs_live_+ 24 characters.
Responses
- Every object has an
objectfield naming its type (checkout.session,list). - Timestamps are ISO 8601 strings in UTC. Fields with no value are
null, never missing. - Amounts come back normalised without trailing zeros:
"25.00"is returned as"25". - Responses carry
Cache-Control: no-store. Errors use one error format.
Rate limits
| Limit | Value |
|---|---|
| Requests per secret key | 100 per minute |
| Sessions created per business | 1,000 per hour |
Over the limit you get 429 with the code rate_limited. Retry with exponential backoff (for example 1s, 2s, 4s, with jitter). Need more? Contact SaphraONE support.
Object limits
| Field | Limit |
|---|---|
amount | 0.50 to 10,000 per session |
currency | USDC (default) or EURC |
expires_in_minutes | 30 to 1,440; default 60 |
line_items | Up to 20; quantity 1 to 10,000; name up to 120 characters |
metadata | Up to 20 keys; keys up to 40 characters, values up to 500 |
description | Up to 140 characters |
client_reference_id | Up to 200 characters |
success_url, cancel_url | Up to 2,048 characters |
| Active API keys | 5 per business |
Versioning
The version is in the path: /v1. Within v1 we only make additive changes: new endpoints, new optional parameters, new fields in responses and new error codes. Anything that would break an integration ships as a new version, announced in the changelog well ahead.
OpenAPI
A machine-readable description of the API is at /openapi/checkout-v1.json. Import it into Postman or Insomnia, or generate a typed client.