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