Skip to main content

​
Checkout Integration

Process card payments and Apple Pay transactions through Checkout.com.

​
Authentication

Authentication Required - All Checkout endpoints require authentication. Include your access token in the Authorization header.
Authorization: Bearer YOUR_ACCESS_TOKEN
See Authentication Setup for instructions on obtaining tokens.

​
Endpoints

MethodEndpointDescription
POST/v1/checkout/payment-sessionsRequest payment session
POST/v1/checkout/instrumentsTokenize payment card
POST/v1/checkout/depositsCreate card deposit
POST/v1/checkout/withdrawalsCreate card withdrawal

​
Integration Flow

​
Step 1: Request Payment Session

Create a payment session to initialize the Checkout.com integration.

​
Request

POST /v1/checkout/payment-sessions

{
  "fundingAccountId": "fa_123",
  "currency": "USD",
  "countryCode": "US",
  "email": "john.doe@example.com",
  "phoneNumber": "+15551234567"
}

​
Response

{
  "id": "ps_abc123",
  "paymentSessionToken": "pst_xyz",
  "paymentSessionSecret": "pss_secret",
  "links": {
    "self": {
      "href": "https://api.checkout.com/sessions/ps_abc123",
      "title": "Session"
    }
  }
}
Use paymentSessionToken and paymentSessionSecret to initialize the Checkout.com client-side SDK.

​
Step 2: Tokenize Card

After collecting card details using the Checkout.com SDK, create a token instrument.

​
Request

POST /v1/checkout/instruments

{
  "fundingAccountId": "fa_123",
  "token": "tok_card_abc123",
  "accountHolder": {
    "type": "CHECKOUT_ACCOUNT_HOLDER_TYPE_INDIVIDUAL",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phoneNumber": "+15551234567",
    "dob": "1990-01-15",
    "billingAddress": {
      "addressLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    }
  }
}

​
Account Holder Types

TypeDescription
CHECKOUT_ACCOUNT_HOLDER_TYPE_INDIVIDUALPersonal account
CHECKOUT_ACCOUNT_HOLDER_TYPE_CORPORATEBusiness account
CHECKOUT_ACCOUNT_HOLDER_TYPE_GOVERNMENTGovernment entity

​
Response

{
  "id": "src_card_abc123"
}
Store the id as the payment instrument for future transactions.

​
Step 3: Create Deposit

Process a card deposit.

​
Request

POST /v1/checkout/deposits

{
  "fundingAccountId": "fa_123",
  "amount": "10000",
  "currency": "USD",
  "description": "Account funding",
  "accountHolder": {
    "type": "CHECKOUT_ACCOUNT_HOLDER_TYPE_INDIVIDUAL",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "billingAddress": {
      "addressLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    }
  },
  "instrumentPaymentSource": {
    "instrumentId": "src_card_abc123"
  }
}
Note: Amount is in minor units (cents for USD). 10000 = $100.00

​
Response

{
  "fundingTransactionId": "ft_deposit_789",
  "checkoutTransactionId": "pay_abc123"
}

​
Error Response

{
  "fundingTransactionId": null,
  "checkoutTransactionId": null,
  "error": {
    "statusCode": 400,
    "status": "Bad Request",
    "requestId": "req_xyz",
    "errorType": "processing_error",
    "errorCodes": ["card_declined"],
    "userMessage": "Your card was declined. Please try a different payment method."
  }
}

​
Error Response Fields

FieldTypeDescription
statusCodeintHTTP status code
statusstringHTTP status text
requestIdstringUnique request ID for debugging
errorTypestringError category
errorCodesarrayMachine-readable error codes for programmatic handling
userMessagestringHuman-readable message safe to display to end users
Display userMessage to UsersThe userMessage field contains a user-friendly explanation of the error. Display this to your users instead of the raw errorCodes. The errorCodes array is for programmatic error handling and logging.

​
Step 4: Create Withdrawal

Process a card withdrawal (payout).

​
Request

POST /v1/checkout/withdrawals

{
  "fundingAccountId": "fa_123",
  "amount": "5000",
  "currency": "USD",
  "description": "Withdrawal to card",
  "accountHolder": {
    "type": "CHECKOUT_ACCOUNT_HOLDER_TYPE_INDIVIDUAL",
    "firstName": "John",
    "lastName": "Doe",
    ...
  },
  "instrumentPaymentDestination": {
    "instrumentId": "src_card_abc123"
  }
}

​
Response

{
  "fundingTransactionId": "ft_withdraw_321",
  "checkoutTransactionId": "pay_def456"
}

​
Apple Pay Integration

For Apple Pay transactions, use the Apple Pay payment details instead of a saved instrument. Apple Pay provides encrypted payment data directly from the user’s device.

​
Apple Pay Headers

FieldDescription
versionAlways "EC_v1" for current Apple Pay
dataBase64-encoded encrypted payment data
signatureBase64-encoded signature
ephemeralPublicKeyPublic key for decryption
publicKeyHashHash of the merchant’s public key
transactionIdApple-generated transaction ID
displayNameCard display name (e.g., “Visa 1234”)

​
Deposit with Apple Pay

POST /v1/checkout/deposits

{
  "fundingAccountId": "fa_123",
  "amount": 10000,
  "currency": "USD",
  "description": "Account funding via Apple Pay",
  "accountHolder": {
    "type": "CHECKOUT_ACCOUNT_HOLDER_TYPE_INDIVIDUAL",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "billingAddress": {
      "addressLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    }
  },
  "applePayPaymentSource": {
    "version": "EC_v1",
    "data": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ...",
    "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglgh...",
    "headers": {
      "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...",
      "publicKeyHash": "abc123def456...",
      "transactionId": "apple_txn_abc123"
    },
    "displayName": "Visa 1234"
  }
}

​
Response

{
  "fundingTransactionId": "ft_deposit_789",
  "checkoutTransactionId": "pay_abc123"
}

​
Withdrawal with Apple Pay

Apple Pay can also be used for withdrawals (payouts) to the user’s linked card. 
POST /v1/checkout/withdrawals

{
  "fundingAccountId": "fa_123",
  "amount": 5000,
  "currency": "USD",
  "description": "Withdrawal via Apple Pay",
  "accountHolder": {
    "type": "CHECKOUT_ACCOUNT_HOLDER_TYPE_INDIVIDUAL",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "billingAddress": {
      "addressLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    }
  },
  "applePayPaymentDestination": {
    "version": "EC_v1",
    "data": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ...",
    "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglgh...",
    "headers": {
      "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...",
      "publicKeyHash": "abc123def456...",
      "transactionId": "apple_txn_def456"
    },
    "displayName": "Visa 1234"
  }
}

​
Response

{
  "fundingTransactionId": "ft_withdraw_321",
  "checkoutTransactionId": "pay_def456"
}

​
Error Codes

Error CodeDescriptionResolution
card_declinedCard was declinedTry different card
insufficient_fundsNot enough funds on cardTry smaller amount
expired_cardCard has expiredUse valid card
invalid_cardCard number invalidCheck card details
processing_errorGeneral processing errorRetry transaction
velocity_limitToo many transactionsWait and retry

​
Best Practices

  1. Use client-side tokenization - Never send raw card data to your servers
  2. Store instrument IDs - Allow users to save cards for faster checkout
  3. Validate amount limits - Check deposit/withdrawal limits before processing
  4. Handle 3DS - Be prepared for 3D Secure authentication flows
  5. Display clear errors - Show user-friendly error messages