API basics
The rules every endpoint shares. Read this once; the guides and the API reference assume it.
On this page
Base URL and requests
Every endpoint lives under /api/v1 on your gateway host. The samples use https://payments.example.com/api/v1; replace it with your own. In these docs a path such as /v1/payments means https://payments.example.com/api/v1/payments.
- Requests with a body send JSON with
Content-Type: application/json. Another content type answers415, and a body larger than 32 KB answers413. - Request bodies are strict: a field that is not documented is an error (
400 invalid_request, with the field inparam). - Every response carries an
X-Request-Idheader. Quote it when you contact support.
Authentication
Authenticate every request with an API key as a bearer token. You create keys in the API keys page of your dashboard; the secret is shown once, right after you create it.
curl -sS https://payments.example.com/api/v1/payments \
-H "Authorization: Bearer cp_test_..."A missing, malformed, unknown or revoked key, or a key of a suspended account, answers 401 unauthorized with WWW-Authenticate: Bearer. The reason is deliberately not given.
Test and live keys
A cp_test_ key works on test payments only, where no real money moves, and a cp_live_ key on live ones. The two never see each other: a payment of the other mode answers 404. Every object has livemode. See Test mode.
Amounts and currencies
Amounts are decimal strings in major units, never numbers: "49.00" is 49 euros. A price has at most 9 whole digits and 2 decimals. Prices are in EUR or USD.
What the buyer is charged can differ from the price: a USD price is converted to EUR, and VAT can be added at checkout. See Amounts, currencies and VAT.
Idempotency
Creating a payment or a subscription takes an optional Idempotency-Key header, so a retry after a timeout creates nothing twice.
- A key is 1 to 200 characters of letters, digits and
_ . : -. A malformed key answers400 invalid_idempotency_key. - Keys are scoped to your account and mode and kept for 24 hours.
- The same key with the same body returns the stored first response, marked
Idempotent-Replayed: true, and creates nothing new. - The same key with a different body is refused with
422 idempotency_key_reuse.
Use one key per order attempt, and send the same key again when you retry that attempt.
Selecting a method with the direct payment API is idempotent by method and needs no key.
Pagination
List endpoints return the newest objects first, in pages. limit is 1 to 100 (default 20). When has_more is true, ask for the next page with the id of the last object as starting_after.
curl -sS "https://payments.example.com/api/v1/payments?limit=20&starting_after=pay_0123456789abcdefghjkmnpq" \
-H "Authorization: Bearer cp_test_..."{
"object": "list",
"data": [
"…"
],
"has_more": false
}A malformed starting_after answers 400 invalid_cursor.
Errors
Every error has the same shape. Read code, which is stable. message is fixed text for a developer, not for the buyer. param names the request field a 400 is about.
{
"error": {
"code": "invalid_request",
"message": "This field has an invalid format",
"param": "return_url"
}
}| HTTP | Codes | Meaning |
|---|---|---|
| 400 | invalid_json, invalid_request, invalid_input, invalid_amount, invalid_idempotency_key, invalid_cursor | The request is not valid. Fix it; do not retry it as it is. |
| 401 | unauthorized | The API key is missing, malformed, unknown or revoked, or its account is suspended. |
| 403 | customer_unavailable | The account cannot take payments. |
| 404 | not_found | No such object in the mode of your key. Another account’s object and a malformed id look the same. |
| 409 | not_cancellable | The object is in a status that does not allow the call. Nothing changed. |
| 413, 415 | payload_too_large, unsupported_media_type | The body is over 32 KB, or not application/json. |
| 422 | no_methods, no_fee_rule, amount_too_small, idempotency_key_reuse | The request is well formed but cannot be done. |
| 429 | rate_limited | Too many requests. Wait for Retry-After. |
| 500 | internal_error | Something went wrong on the gateway. A request with an Idempotency-Key is safe to retry. |
| 502, 503 | provider_error, fx_unavailable | A provider or the exchange rate is not available. Nothing changed; retry after Retry-After. |
Each endpoint lists its own codes in the API reference.
Rate limits
The API takes 120 requests per minute per API key, with a per-address limit in front of it. Over a limit the answer is 429 rate_limited with a Retry-After header: wait that many seconds, then try again.