/api/v1. Choose the environment first, keep server credentials on your server, and treat every write as a state transition that may be retried or reconciled.
Authentication
Sendx-api-key from trusted server code. Never put it in browser JavaScript, mobile bundles, URLs, logs, or metadata. Browser checkout calls use a short-lived bearer client token scoped to one session.
Money and currency
Use integer minor units for new requests.4990 with EUR means EUR 49.90. Store the currency beside every amount, use decimal-safe arithmetic, and compare the authoritative API amount with your order total before fulfillment.
Idempotency
Send a stableIdempotency-Key on payment, checkout-session, subscription, payment-link, refund, and other create requests. Reuse the same key when the response is lost. Do not generate a new key until you have reconciled the original request.
Pagination
List endpoints acceptlimit and offset and return data, hasMore, and nextOffset where applicable. Persist the last successful cursor and stop when hasMore is false. Do not use an object’s display name as a cursor.
Errors
Errors return anerror code, a message, optional field details, and a requestId. Fix 400 and 401 requests before retrying. Back off on 429 and 5xx; retrieve by ID after an ambiguous response. A 409 means you must reconcile current state before applying another write.