Skip to content
Creative Payments

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 answers 415, and a body larger than 32 KB answers 413.
  • Request bodies are strict: a field that is not documented is an error (400 invalid_request, with the field in param).
  • Every response carries an X-Request-Id header. 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.

Authenticated requestcurl
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 answers 400 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.

Next pagecurl
curl -sS "https://payments.example.com/api/v1/payments?limit=20&starting_after=pay_0123456789abcdefghjkmnpq" \
  -H "Authorization: Bearer cp_test_..."
List shapeJSON
{
  "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 bodyJSON
{
  "error": {
    "code": "invalid_request",
    "message": "This field has an invalid format",
    "param": "return_url"
  }
}
Status codes shared by the endpoints
HTTPCodesMeaning
400invalid_json, invalid_request, invalid_input, invalid_amount, invalid_idempotency_key, invalid_cursorThe request is not valid. Fix it; do not retry it as it is.
401unauthorizedThe API key is missing, malformed, unknown or revoked, or its account is suspended.
403customer_unavailableThe account cannot take payments.
404not_foundNo such object in the mode of your key. Another account’s object and a malformed id look the same.
409not_cancellableThe object is in a status that does not allow the call. Nothing changed.
413, 415payload_too_large, unsupported_media_typeThe body is over 32 KB, or not application/json.
422no_methods, no_fee_rule, amount_too_small, idempotency_key_reuseThe request is well formed but cannot be done.
429rate_limitedToo many requests. Wait for Retry-After.
500internal_errorSomething went wrong on the gateway. A request with an Idempotency-Key is safe to retry.
502, 503provider_error, fx_unavailableA 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.