Every endpoint, error and event

Version 2026-08-19. Read the quickstart first if you have not made a payment yet; the rest is reference and can be read in any order.

Start hereQuickstartA sandbox key, a tokenised test card, a payment, a registered endpoint and a webhook you verify yourself — in six requests.

Authentication and keysBearer keys, the two key shapes, how the environment is decided, what a key never returns twice, and how to roll one without a failed request.
ConventionsAmounts, currencies, ids, timestamps, versioning with Cleared-Version, cursor pagination, and what is not supported yet.
ErrorsThe error envelope, every error type with its status, the codes you will actually see, and which decline codes are safe to retry.
IdempotencyHow to make a POST safe to retry: the key, the 24-hour replay window, what counts as the same request, and what to do after a timeout.
PaymentsThe payment object field by field, create and confirm, retrieve and list, captures including partial, cancel, and refunds.
Checkout sessionsCreate a hosted payment page, send the payer to it, and read the result: parameters, the session object, lifecycle and the return URLs.
WebhooksRegister endpoints, subscribe to events, roll a secret with no downtime, and verify the signature. Plus the retry schedule and the dead letter.
Sandbox endpointsThe four test-mode endpoints: tokenise a magic card, advance an async payment, simulate a webhook, and read the card table from the API.

Card numbers, outcome overrides and the simulated challenge page are on sandbox and test cards, rendered from the simulator's own module so the table cannot drift.