v1.0.0
OpenAPI 3.0.1

Checkout.com API Reference

Checkout.com Support
Terms of Service

Get started

Checkout.com provides a collection of APIs that enable you to integrate with our various products and services. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using any HTTP or REST library. Sign up for a test account to gain access to the sandbox environment, where you can test API calls without affecting live data. For more information, see:

Base URLs

The base URLs you must use for your API calls to the sandbox and production environments are unique to you.

  • https://{prefix}.api.sandbox.checkout.com/{path}
  • https://{prefix}.api.checkout.com/{path}
  • https://{prefix}.access.sandbox.checkout.com/{path}
  • https://{prefix}.access.checkout.com/{path}

The unique API endpoint host names resolve to Checkout.com's IP addresses. Do not allowlist these IP addresses. The {prefix} value in each base URL is a string containing the first eight characters of each of your environments' unique client_id, excluding the cli_ prefix. To find your unique base URL:

  1. Sign in to the Dashboard environment you want to retrieve the base URL for:

  2. Go to Developers > Overview.
    Your unique base URL is displayed on the Developer overview page. For example, https://vkuhvk4v.api.checkout.com.

  3. Alternatively, go to Settings > Account details.
    Your unique base URL is displayed under Connection settings.

If you are unsure of your client ID or base URL for either environment, contact your account manager or request support. For more information, see API endpoints.

Authentication

When you sign up for an account, you can authenticate with either Access keys (OAuth 2.0), or Secret API keys. Unless explicitly stated, all endpoints require authentication using either your Access or Secret API Keys. Public keys should only be used in JavaScript or native applications.

  • Client-side authentication. Use your public key for client-side authentication. It only has access to a limited set of our APIs – mostly those called as part of your payment environment.

  • Server-to-server authentication. Use your secret key or OAuth for server-to-server communication. Support for API keys depends on the endpoint.

Never share your OAuth credentials, API keys, or access tokens. Keep them guarded and secure.

ApiPublicKey

Public keys are for client-side authentication and supported only in JavaScript or native applications.

Format

  • Sandbox – pk_sbox_xxxxxxxxxxxxxxxxxxxxxxxxxx

  • Production – pk_xxxxxxxxxxxxxxxxxxxxxxxxxx

When specifying your public key, use the format Bearer {{PublicApiKey}}.

Security Scheme Type: API Key

Header parameter name: Authorization

ApiSecretKey

You can pass your secret API key in the Authorization header of your requests for supported endpoints.

Format

  • Sandbox – sk_sbox_xxxxxxxxxxxxxxxxxxxxxxxxxx

  • Production – sk_xxxxxxxxxxxxxxxxxxxxxxxxxx

When specifying your secret key, use the format Bearer {{SecretApiKey}}.

curl --location --request POST 'https://{prefix}.api.checkout.com/{{path}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{SecretApiKey}}' \
--data-raw '{
"amount": 10000,
"currency": "USD",
"reference": "Visa-USD-Test",
...
}'

Security Scheme Type: API Key

Header parameter name: Authorization

OAuth

Your OAuth credentials include an access key ID and an access key secret. They correspond to an OAuth 2.0 client ID and a client secret respectively.

To exchange these credentials for an access token, call the Request an access token endpoint. Authenticate using basic authentication, with your access key ID as the username and your access key secret as the password.

Environment Authorization server
Sandbox https://{prefix}.access.sandbox.checkout.com/connect/token
Production https://{prefix}.access.checkout.com/connect/token 
curl --location 'https://{prefix}.access.checkout.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=ack_...' \
--data-urlencode 'client_secret=...'

The token server returns a Bearer access_token in JSON Web Token (JWT) format. Use this token in the Authorization header of your API requests.

curl --location --request POST 'https://{prefix}.api.checkout.com/{{path}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{AccessToken}}' \
--data-raw '{
  "amount": 10000,
  "currency": "USD",
  "reference": "Visa-USD-Test",
  ...
}'

The expires_in field in the response indicates the validity period of your access token in seconds. When your token expires, you must request a new one.

Depending on the Environment against which you're making your requests against you'll need to request the token from a different Authorization Server.

Environment Authorization Server
Sandbox https://{prefix}.access.sandbox.checkout.com/connect/token
Production https://{prefix}.access.checkout.com/connect/token

Your base URL {prefix} is unique. To learn how to retrieve your unique base URLs for the sandbox and production environments, see API endpoints.

Security Scheme Type: OAuth2

Flow type: clientCredentials

Token URL: string

Scopes:

  • vault - Access to all Vault resources
  • vault:apme-enrollment - Manage Apple Pay Domain Enrollment
  • vault:customers - Manage customers
  • vault:card-metadata - Read card metadata
  • vault:instruments - Create instruments
  • vault:network-tokens - Manage network tokens
  • vault:tokenization - Tokenize payment instruments
  • vault:real-time-account-updater - Access to real-time account updater
  • gateway - Access to all Gateway resources
  • gateway:payment - Request payments
  • gateway:payment-details - Get payment details
  • gateway:payment-authorizations - Increment authorizations
  • gateway:payment-voids - Void payments
  • gateway:payment-captures - Capture payments
  • gateway:payment-contexts - Manage payment contexts
  • gateway:payment-cancellations - Manage payment cancellations
  • gateway:payment-refunds - Refund payments
  • fx - Foreign exchange services
  • payouts:bank-details - Get bank details
  • sessions:app - App-based authentication
  • sessions:browser - Browser-based authentication
  • disputes - Access to all Disputes resources
  • disputes:view - View disputes
  • disputes:provide-evidence - Provide dispute evidence
  • disputes:accept - Accept disputes
  • disputes:scheme-files - Read dispute scheme files
  • accounts - Manage sub-entities
  • flow - Access to all Flow resources
  • flow:workflows - Manage workflows
  • flow:events - Retrieve events
  • flow:reflow - Manage workflows
  • files - Access to all Files resources
  • files:retrieve - Retrieve files
  • files:upload - Upload files
  • files:download - Download files
  • forward - Access to Forward api
  • forward:secrets - Manage secrets in Forward api
  • balances - Access to all Balances resources
  • balances:view - View balances
  • balances:top-up-instructions - Get top-up instructions
  • transfers - Access to all Transfers resources
  • transfers:view - View transfers
  • transfers:create - Create transfers
  • middleware - Access to all Middleware resources
  • middleware:merchants-secret - Allows merchant identity and Middleware token exchange from a secure execution environment
  • middleware:merchants-public - Allows merchant identity and Middleware token exchange from an insecure execution environment
  • payment-sessions - Access to all Payment Sessions resources
  • payments:search - Search payments
  • reports - Access to all Reports resources
  • reports:view - View reports
  • financial-actions - Access to all Financial actions resources
  • financial-actions:view - View financial actions
  • card-management - Access to all Card management resources
  • issuing:card-management-read - Gives access to card management endpoints with GET operations
  • issuing:card-management-write - Gives access to card management endpoints with POST/ PUT / DELETE operations
  • issuing:controls-read - Gives access to card control endpoints with GET operations
  • issuing:controls-write - Gives access to card control endpoints with POST/ PUT / DELETE operations
  • transactions - Access to all transactions resources
  • issuing:transactions-read - Gives access to get and search transactions
  • issuing:transactions-write - Gives access to simulate transactions for testing purposes
  • issuing-disputes - Access to Issuing disputes resources
  • issuing:disputes-read - Gives access to get disputes
  • issuing:disputes-write - Gives access to create and submit Issuing disputes
  • identity-verification - Access to all Identities endpoints
  • Payment Context - Read payment context
  • agentic:inventory - Manage agentic commerce inventory and reservations

SessionSecret

A base64 encoded value prefixed with sek_ that gives access to client-side operations for a single authentication within the Sessions API. This value is returned as the session_secret when requesting a session.

Security Scheme Type: API Key

Header parameter name: Authorization

Sandbox environment

Client Libraries
Shell Curl