Conventions

Requests and responses

Send JSON with Content-Type: application/json and read JSON back. A single record comes back as the object itself, with an object field naming its type. Timestamps are ISO 8601 in UTC.

Amounts

Every amount is an integer in minor units: cents for USD, so 2500 is $25.00. This holds for requests and responses alike. Each gateway receives the amount in whatever format it expects.

currency is a three-letter code and defaults to USD.

Ids

Ids carry a prefix that tells you what they are, followed by a sortable ULID:

Metadata

Cards, transactions and customers take metadata: keys and values of your own, like an order id. It is returned on the record and in its webhooks, and shown in the dashboard.

• Up to 50 keys. A key starts with a letter and uses only letters, digits, _ and -, up to 40 characters.
• Values are text, up to 500 characters. Numbers, true/false and nested objects are refused; send them as text.
• Sending metadata replaces all of it. To change one key, send the whole set again; send {} to clear it.
• Metadata is stored as plain text, so never put card numbers or other secrets in it. A value containing anything that passes for a card number is refused.

{ "metadata": { "order_id": "1042", "channel": "web" } }

Idempotency

Send an Idempotency-Key header with every POST that moves money. If the request is retried with the same key and the same body within 24 hours, you get the first answer back, marked with an Idempotent-Replayed: true header, and nothing runs twice.

curl -X POST https://api.ordercard.io/v1/gateways/gw_01jaxr2d5f8g0h3j6k9m2n5p8q/purchase \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Idempotency-Key: order-1001-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method_token": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e", "amount": 2500 }'

• A key reused with a different body answers 409 with idempotency_key_reused.
• While the first request with a key is still running, a second one answers 409 with idempotency_in_progress.
• Declines (402) are remembered like successes. Server errors (5xx) are not, so a request that failed on our side can be retried with the same key.
• Refused requests (invalid input, a missing permission, a conflict) are not remembered either: fix the request and send it again with the same key.
• Keys are remembered per API key. A retry sent with a different API key runs as a new request, and a charge can still never run twice with the same Idempotency-Key.
• Keys are at most 255 characters. Use something tied to the business action, like an order number plus attempt.

Pagination

List endpoints return a page of records under data, newest first, with cursors to move between pages:

{
  "data": [ { "object": "transaction", "id": "txn_…" } ],
  "links": { "first": null, "last": null, "prev": null, "next": "https://api.ordercard.io/v1/transactions?cursor=eyJ…" },
  "meta": { "path": "https://api.ordercard.io/v1/transactions", "per_page": 25, "next_cursor": "eyJ…", "prev_cursor": null }
}

Pass limit (1 to 100, default 25) and cursor (a next_cursor or prev_cursor value). When next_cursor is null you have reached the end.

Rate limits

Each API key can make 300 requests per minute. Above that, requests answer 429 with the code rate_limited and a Retry-After header saying how many seconds to wait.