A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Checkout.com API is how an app or AI agent works with a Checkout.com account: requesting a payment, capturing or refunding it, tokenizing a card, raising a payout, or handling a dispute. Access is granted through a secret API key or an OAuth 2.0 token, and that token carries granular scopes, like one to request payments and a separate one to refund them, that set which areas a call can reach. A state change emits an event that Checkout.com can deliver to an endpoint registered as a workflow.
How an app or AI agent connects to Checkout.com determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the key or token behind it and the scopes that token carries.
The REST API takes JSON request bodies and returns JSON, addressed by path on the account's API host. A call authenticates with a secret API key sent as a Bearer token, or with an OAuth 2.0 access token obtained from the token endpoint. The key or token carries the scopes that decide which areas the call can reach.
Checkout.com POSTs events to an HTTPS endpoint registered as a workflow, configured through the Dashboard or the Workflows API. The receiver verifies the signature on each delivery against the workflow's signing key to confirm the event came from Checkout.com. Events cover the payment lifecycle and disputes.
A secret key is used for server-side calls and sent as a Bearer token in the Authorization header. The scopes it can use are set on the key in the Dashboard, so a key reaches only the areas it was granted. A secret key must never be exposed in client code.
An access key ID and secret are exchanged at the token endpoint using the client_credentials grant, with Basic auth, for a JWT access token. The request names one or more scopes the token should carry, and the token expires after four hours. This suits integrations that prefer short-lived credentials over a long-lived key.
A public key is safe to embed in client code, such as a browser or mobile app. It is limited to tokenizing payment details and cannot read payments, move money, or reach any other area.
The Checkout.com API is split into areas an agent can act on, like taking and managing payments, tokenizing cards, storing instruments and customers, handling disputes, moving funds, and reading balances. Each area has its own methods and its own scope, and writes in some areas move real money.
Methods for requesting and managing payments and their actions.
Methods for hosted payment sessions and shareable payment links.
Methods for tokenizing cards and storing reusable payment instruments.
Methods for storing and managing customer records.
Methods for reviewing disputes and responding with evidence.
Methods for moving funds between entities and reading balances.
Methods for configuring where and how events are delivered.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
PaymentsMethods for requesting and managing payments and their actions.8 | ||||||
| POST | /payments | Request a payment or a payout, charging a source or sending funds to a destination. | write | gateway:payment | Current | |
The core payment write; also covers card verification. Capture and refund need their own scopes. Acts onpayment Permission (capability) gateway:paymentVersionAvailable since the API’s base version Webhook event payment_approvedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /payments | Search and list payments matching a query. | read | gateway:payment-details | Current | |
Read-only. Acts onpayment Permission (capability) gateway:payment-detailsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /payments/{id} | Get the details of a payment, including its status and source. | read | gateway:payment-details | Current | |
Read-only. Acts onpayment Permission (capability) gateway:payment-detailsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /payments/{id}/actions | Get the list of actions taken on a payment, like authorize, capture, refund, and void. | read | gateway:payment-details | Current | |
Read-only; the action history is how a payment's lifecycle is inspected. Acts onpayment_action Permission (capability) gateway:payment-detailsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /payments/{id}/captures | Capture the funds of a previously authorized payment, fully or partially. | write | gateway:payment-captures | Current | |
Only for manual-capture payments; collects authorized funds. Acts onpayment Permission (capability) gateway:payment-capturesVersionAvailable since the API’s base version Webhook event payment_capturedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /payments/{id}/refunds | Refund a captured payment, fully or partially, returning funds to the cardholder. | write | gateway:payment-refunds | Current | |
A separate scope from requesting the payment, so refunds can be granted on their own. Acts onpayment Permission (capability) gateway:payment-refundsVersionAvailable since the API’s base version Webhook event payment_refundedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /payments/{id}/voids | Void an authorized payment before it is captured, releasing the held funds. | write | gateway:payment-voids | Current | |
Only works before capture. Acts onpayment Permission (capability) gateway:payment-voidsVersionAvailable since the API’s base version Webhook event payment_voidedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /payments/{id}/authorizations | Increment the authorized amount on an existing payment. | write | gateway:payment-authorizations | Current | |
Raises the held amount before capture, for supported card schemes. Acts onpayment Permission (capability) gateway:payment-authorizationsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Payment Sessions & LinksMethods for hosted payment sessions and shareable payment links.3 | ||||||
| POST | /payment-sessions | Create a Payment Session, the server-side context behind Checkout.com's hosted and embedded payment flow. | write | gateway:payment | Current | |
Used by the Flow front-end component to present payment methods. Acts onpayment_session Permission (capability) gateway:paymentVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /payment-links | Create a Payment Link, a hosted page a customer can be sent to in order to pay. | write | gateway:payment | Current | |
Returns a URL the customer is directed to. Acts onpayment_link Permission (capability) gateway:paymentVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /payment-links/{id} | Get the details and status of a Payment Link. | read | gateway:payment-details | Current | |
Read-only. Acts onpayment_link Permission (capability) gateway:payment-detailsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Tokens & InstrumentsMethods for tokenizing cards and storing reusable payment instruments.4 | ||||||
| POST | /tokens | Tokenize raw payment details into a single-use token, usually from client code. | write | vault:instruments | Current | |
Typically called with a public key client-side to keep card data off the integration's servers. Acts ontoken Permission (capability) vault:instrumentsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /instruments | Store a reusable payment instrument from a token for future payments. | write | vault:instruments | Current | |
Persists a card for reuse, unlike a single-use token. Acts oninstrument Permission (capability) vault:instrumentsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /instruments/{id} | Get the details of a stored payment instrument. | read | vault:instruments | Current | |
Read-only. Acts oninstrument Permission (capability) vault:instrumentsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /instruments/{id} | Delete a stored payment instrument so it can no longer be charged. | write | vault:instruments | Current | |
Irreversible for that stored instrument. Acts oninstrument Permission (capability) vault:instrumentsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CustomersMethods for storing and managing customer records.4 | ||||||
| POST | /customers | Create a customer record to group payment instruments and details. | write | vault:instruments | Current | |
A core write under the vault scope. Acts oncustomer Permission (capability) vault:instrumentsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /customers/{id} | Get the details of a stored customer. | read | vault:instruments | Current | |
Read-only. Acts oncustomer Permission (capability) vault:instrumentsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /customers/{id} | Update a stored customer's details. | write | vault:instruments | Current | |
A core write under the vault scope. Acts oncustomer Permission (capability) vault:instrumentsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /customers/{id} | Delete a stored customer record. | write | vault:instruments | Current | |
Irreversible. Acts oncustomer Permission (capability) vault:instrumentsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DisputesMethods for reviewing disputes and responding with evidence.5 | ||||||
| GET | /disputes | List and search disputes raised against the account's payments. | read | disputes:view | Current | |
Read-only. Acts ondispute Permission (capability) disputes:viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /disputes/{id} | Get the details of a dispute, including its reason and deadline. | read | disputes:view | Current | |
Read-only. Acts ondispute Permission (capability) disputes:viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /disputes/{id}/accept | Accept a dispute, conceding the case and returning the funds to the cardholder. | write | disputes:accept | Current | |
Final; the dispute cannot then be contested. Acts ondispute Permission (capability) disputes:acceptVersionAvailable since the API’s base version Webhook event dispute_lostRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /disputes/{id}/evidence | Provide or update the evidence attached to a dispute before submitting it. | write | disputes:provide-evidence | Current | |
Stages evidence; a separate submit call commits it. Acts ondispute_evidence Permission (capability) disputes:provide-evidenceVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /disputes/{id}/evidence | Submit the staged evidence to contest a dispute before its deadline. | write | disputes:provide-evidence | Current | |
Commits the evidence; submit before the dispute deadline or the case is lost by default. Acts ondispute_evidence Permission (capability) disputes:provide-evidenceVersionAvailable since the API’s base version Webhook event dispute_wonRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Payouts & BalancesMethods for moving funds between entities and reading balances.3 | ||||||
| POST | /transfers | Initiate a transfer of funds between entities on the account. | write | fx | Current | |
Moves real money between entities; used in platform and payout setups. Acts ontransfer Permission (capability) fxVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /transfers/{id} | Get the details and status of a transfer. | read | fx | Current | |
Read-only. Acts ontransfer Permission (capability) fxVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /balances/{id} | Retrieve the balances held by an entity on the account. | read | fx | Current | |
Read-only. Acts onbalance Permission (capability) fxVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Workflows (Webhooks)Methods for configuring where and how events are delivered.5 | ||||||
| GET | /workflows | List the workflows configured for the account, including webhook destinations. | read | — | Current | |
Read-only; workflows decide where events are delivered. The exact OAuth scope is not stated on the public reference. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workflows | Add a workflow, including the webhook endpoint events are delivered to. | write | — | Current | |
Sets where account events are sent. The exact OAuth scope is not stated on the public reference. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workflows/{id} | Get the details of a single workflow. | read | — | Current | |
Read-only. The exact OAuth scope is not stated on the public reference. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /workflows/{id} | Update a workflow's conditions or actions. | write | — | Current | |
Changes how or where events are delivered. The exact OAuth scope is not stated on the public reference. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /workflows/{id} | Remove a workflow so its events are no longer delivered. | write | — | Current | |
Stops event delivery to that destination. The exact OAuth scope is not stated on the public reference. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Checkout.com can notify an app when something happens to a payment or a dispute, like a payment being approved, a capture succeeding, or a dispute needing evidence. It sends an event to an HTTPS endpoint configured as a workflow, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
payment_approved | A payment authorization, or a payout, was approved. An integration treats this as the signal that the payment was accepted. | /payments |
payment_declined | A payment authorization was declined, for example by the issuer. | /payments |
payment_captured | A capture was successful and the authorized funds were collected. | /payments/{id}/captures |
payment_refunded | A refund was successful and funds were returned to the cardholder. | /payments/{id}/refunds |
payment_voided | A void was successful and the authorization was released before capture. | /payments/{id}/voids |
card_verified | A card verification was successful, confirming the card without taking a payment. | /payments |
dispute_received | A new dispute was raised against a payment, opening a window to respond. | In-app only |
dispute_evidence_required | A dispute needs evidence to be submitted before its deadline, or it will be lost by default. | In-app only |
dispute_won | A dispute was resolved in the merchant's favour and the funds were retained. | /disputes/{id}/accept/disputes/{id}/evidence |
dispute_lost | A dispute was resolved against the merchant and the funds were returned to the cardholder. | /disputes/{id}/accept |
Checkout.com limits how fast an app can call, by a request rate measured per second and applied separately to reads and to writes.
Checkout.com meters requests by rate, not by a per-method cost. The default ceiling is 100 requests per second for GET calls and a separate 100 requests per second for POST, PUT, and DELETE calls, applied across the account. The sandbox environment uses lower limits. Limits can be raised by arrangement with an account manager, and going over returns HTTP 429, which an integration should handle by retrying with exponential backoff and jitter.
List endpoints, like getting disputes, page through results with a limit for the page size and a skip offset for the starting position. The response reports the total count alongside the returned page, so an integration can walk forward until it has read every item.
An OAuth access token is valid for four hours before it must be reissued. Request and response bodies are JSON. Specific maximum body sizes are not stated on the public reference, so an integration should not assume an unbounded payload.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | No valid credential was provided: a missing, malformed, or wrong API key or an expired or invalid OAuth token. | Send a valid secret key as a Bearer token, or reissue the OAuth access token, and confirm it is for the correct environment. |
| 403 | Forbidden | The credential is valid but lacks the scope this call needs, for example a refund attempted without gateway:payment-refunds. | Grant the matching scope on the key, or request the OAuth token with that scope, then retry. |
| 404 | Not Found | The referenced object, like a payment or dispute id, does not exist or is not visible to this credential. | Verify the id and confirm it belongs to the same account and environment. |
| 422 | request_invalid | The request was understood but failed validation. The body returns a request_id, an error_type, and an error_codes array, like [processing_channel_id_required], naming each invalid field. | Read the error_codes array, fix the named fields, and resend. The request is not retryable as-is. |
| 429 | too_many_requests | The request rate exceeded the account limit, by default 100 requests per second for reads and a separate 100 for writes. | Back off and retry with exponential backoff and jitter, and smooth the request rate. |
| 500 | Server Error | An error on Checkout.com's side. It is rare. | Retry with backoff using the same idempotency key where supplied, and contact support if it persists. |
Checkout.com runs a single unified API addressed by path rather than a dated version string, and ships changes through dated release notes.
Checkout.com runs one unified API addressed by path, with no dated version string. New fields and methods are added over time, and changes ship through dated release notes rather than as a new version number. The same API covers payments, tokenization, the vault, customers, disputes, payouts and transfers, balances, and workflows.
Checkout.com migrated merchants from its earlier account type to its current Unified Payments accounts, which use the scoped key and OAuth model documented here. The previous account type used a different key format and is being retired.
There is no version to pin; new fields and methods are added to the unified API over time.
Checkout.com release notes ↗Bollard AI sits between a team's AI agents and Checkout.com. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.