Guides
API Reference

Our reference library for integrating with our API

FAQ

Find answers to our most frequently asked questions

Classic Docs

Documentation for our Classic API

Migration guide

The Unified Payments solution provides you with a streamlined integration experience, with consolidated payment flows, simplified API responses, and a single /payments endpoint for all supported payment methods.

Unified Payments is SCA-ready

Our Unified Payments solution fully supports the new authentication standard – 3D Secure 2 (3DS2) – and automatically handles the Strong Customer Authentication (SCA) requirements introduced by the revised Payment Services Directive, providing your customers with a smoother, more secure checkout flow.

This migration guide will outline key concepts introduced in the Unified Payments solution and then provide you with a step-by-step guide on how to update your integration to use it.

We've answered some of the most frequently asked questions in our Migration FAQ.

If you need any additional support during the migration process, do not hesitate to reach out to our Support team.

Single payments endpoint

The Unified Payments solution provides a single payments endpoint supporting both new and existing payment methods. Whether you accept cards, alternative payment methods or digital wallets, all your payment requests will be sent to the same endpoint.

Payment sources

We now support securely storing multiple sources of payments, including cards and bank accounts. Each payment source will have a unique ID that can be used to make a payment request. Your existing card IDs can still be used when requesting a payment and you will be provided with the updated source ID in the payment response.

Payments and actions

Payments replace what we previously referred to as a charge. A payment can have one or more actions that represent an interaction with a payment provider, for example Visa. This provides you with granular visibility into the lifecycle of a payment and a single ID that can be used to obtain the current status.

Because any subsequent actions performed on a payment only requires you to reference the payment ID in your API call, it is the only identifier that you need to store for future use.

Updated SDKs

As a part of the Unified Payments solution, we have introduced new SDKs for .NETPython, and PHP that may make your migration process even easier. 

Handling response codes

Captures, refunds and voids are performed asynchronously in the Unified Payments solution, meaning that you will get an HTTP status code of 202 - Accepted in your API response rather than a 201 - Created. To get final confirmation that these actions were performed successfully, we recommend that you use webhook notifications. API validation response codes (i.e., 7xxx response codes) have also been replaced with more descriptive and user-friendly error codes. More details on this can be found response codes.

We have also introduced an approved field to the request payment and retrieve payment responses to indicate whether the requested action was performed successfully. This provides you with a single field that you can rely on in your integration to confirm the outcome of the requested action.

3D Secure payments

When requesting a 3D Secure payment, the cardholder may need to be redirected to a separate page to authenticate themselves. If this is the case, you will receive an HTTP status code of 202 - Accepted and a redirect link in the response’s hypermedia.

{
  "source" : {
    "type" : "card",
    "number" : "4242424242424242",
    "expiry_year" : 2019,
    "expiry_month" : 03,
    "cvv" : "100"
  },
  "amount" : "2000",
  "currency" : "USD",
  "reference": "TRK12345",
  "3ds" : {
    "enabled": true,
  }
}
{
  "id": "pay_g3avvtweex5e7prna4vkupdkle",
  "status": "Pending",
  "reference": "TRK12345",
  "customer": {
    "id": "cus_mp6evgbj4bzevmnpxgsq7bdcgy"
  },
  "3ds": {
    "downgraded": false,
    "enrolled": "Y"
  },
  "_links": {
    "self": {
      "href":
"https://api.sandbox.checkout.com/payments/pay_g3avvtweex5e7prna4vkupdkle"
    },
    "redirect": {
      "href":
"https://sandbox.checkout.com/api2/v2/3ds/acs/sid_vwipcigm6k2ubcvl2rzbovpysy"
    }
  } 
}

Once the cardholder has been authenticated and is redirected back to your success or failure URL, we will provide a session ID in the URL that can be used to retrieve details of the payment.

If you instead receive an HTTP status of 201 - Created, it means that it was processed successfully and does not require any further action to complete the processing.

Card token flow

What doesn't change

  • Your existing front-end solution (e.g., Frames, Checkout.js, SDKs) can still be used to collect your customer's card information.
  • Checkout.com still returns a card token once your customer has confirmed the purchase.

What changes

Classic APIUnified Payments API
  • The token charges endpoint is used to request a payment using the card token from step 2.
  • A card ID is provided in the charge response, which can be used for subsequent payments with the same card information.
  • The unified payments endpoint is used to request a payment with the card token from step 2. A source type of token should be used.
  • A source ID is provided in the payment response, which can be used for subsequent payments with the same card information.

The request

Endpoints

Classic APIUnified Payments API
https://api2.checkout.com/v2/charges/token
https://sandbox.checkout.com/api2/v2/charges/token
https://api.checkout.com/payments
https://api.sandbox.checkout.com/payments

Request examples

{
  "email": "s.mitchell@checkout.com",
  "value": "2000",
  "currency": "USD",
  "trackId": "TRK12345",
  "cardToken": "card_tok_9EDE49...A52CC25"
}
{
  "source": {
    "type":"token",
    "token":"card_tok_9EDE49...A52CC25",
  },
  "amount":2000,
  "currency":"USD",
  "reference": "TRK12345",
}

Card ID flow

What doesn’t change

  • When a payment using a card token or full card details is made, the Unified Payments API provides an identifier for the tokenized card information in its response. This identifier, previous called a card ID, is now called a source ID.
  • This source ID can be used to make payments using its underlying card information.

What changes

Classic APIUnified Payments API
The card charges endpoint is used to request a payment.The unified payments endpoint is used to request a payment using a card ID or source ID. A source type of id should be used.

The request

Endpoints

Classic APIUnified Payments API
https://api2.checkout.com/v2/charges/token
https://sandbox.checkout.com/api2/v2/charges/token
https://api.checkout.com/payments
https://api.sandbox.checkout.com/payments

Request examples

{
  "autoCapture": "Y",
  "email": "sarah.mitchell@checkout.com",
  "value": "2000",
  "currency": "USD",
  "trackId": "TRK12345",
  "cardId": "card_930C63F9.....0B5D2CFB5AF",
  "cvv": "100",
}
{ 
  "source": {
    "type": "id",
    "id": "src_i3ywxkcgu5cevigmdxoy6km5je",
    "cvv": "100",
  },
  "amount": 2000,
  "currency": "USD",
  "reference": "TRK12345",
}

Default card/customer flow

What doesn’t change

When a payment is made, the Unified Payments API continues to provide an identifier for the customer in its response. This identifier can be used to make further payments using the default card associated with that customer.

What changes

Classic APIUnified Payments API
The card charges endpoint is used to request a payment using a customer ID.The unified payments endpoint is used to request a payment using a customer ID. A source type of customer should be used.

The request

Endpoints

Classic APIUnified Payments API
https://api2.checkout.com/v2/charges/customer
https://sandbox.checkout.com/api2/v2/charges/customer
https://api.checkout.com/payments
https://api.sandbox.checkout.com/payments

Request examples

{
  "autoCapture": "Y",
  "value": "2000",
  "currency": "USD",
  "trackId": "TRK12345",
  "customerId": "cust_9F8E74...CEE5270BF38A"
}
{ 
	"source": {
    "type": "customer",
    "id": "cus_dxbrk2ruktbutlnbtilhv2qyzm",
  },
  "amount": 2000,
  "currency": "USD",
  "reference": "TRK12345"
}

Full card details

What changes

Classic APIUnified Payments API
  • The card charges endpoint is used to request a payment. Full card details should be specified in the card object of the payment request.
  • A card ID is provided in the charge response, which can be used for subsequent payments with the same card information.
  • The unified payments endpoint is used to request a payment. A source type of card should be used.
  • A source ID is provided in the payment response, which can be used for subsequent payments with the same card information.

The request

Endpoints

Classic APIUnified Payments API
https://api2.checkout.com/v2/charges/card
https://sandbox.checkout.com/api2/v2/charges/card
https://api.checkout.com/payments
https://api.sandbox.checkout.com/payments

Request examples

{
  "email": "sarah.mitchell@checkout.com",
  "value": "2000",
  "currency": "USD",
  "trackId": "TRK12345",
  "card": {
    "name": "Sarah Mitchell",
    "number": "4242424242424242",
    "expiryMonth": "9",
    "expiryYear": "2019",
    "cvv": "100",
  },
}
{ 
  "source": {
    "type": "card",
    "number": "4242424242424242",
    "expiry_month": 9,
    "expiry_year": 2019,
    "cvv": "100",
  },
  "amount": 2000,
  "currency": "USD",
  "reference": "TRK12345",
}

Alternative payment methods

What changes

Classic APIUnified Payments API
The unified payments endpoint is used to request a payment using an alternative payment method. The source type dictates which alternative payment method is used.

What doesn't change

  • The payment response contains a redirect URL that your customer should be redirected to.
  • After your customer completes the payment, they are redirected back to your predefined success or failure URL.
  • You will be provided with a session ID in the URL, which can be used to retrieve the payment details.

The request

Endpoints

Classic APIUnified Payments API
http://api2.checkout.com/v2/charges/localpayment
https://sandbox.checkout.com/api2/v2/charges/localpayment
https://api.checkout.com/payments
https://api.sandbox.checkout.com/payments

Request examples

// Payment token request

{
  "value": "2000",
  "currency": "EUR",
  "chargemode": "3",
}
  
// Payment request
  
{
  "email": "s.mitchell@checkout.com",
  "paymentToken": "pay_tok_6E5D1D...339A4B4B83E5",
  "trackId": "TRK12345",
  "localPayment": {
    "lppId": "lpp_14",
  }
}
{
  "source" : {
    "type": "sofort",
  },
  "amount": "2000",
  "currency": "EUR",
  "reference": "TRK12345",
}

Alternative payment methods - Checkout.JS

What changes

The Checkout.js solution no longer supports alternative payment methods. Instead, a direct integration with the Unified Payments API should be used to request payments using alternative payment methods.

Classic APIUnified Payments API
  • The payment token endpoint is used to create a payment token.
  • The payment token is used in the initialization of Checkout.js.
  • Your customer selects the desired payment method in the lightbox, which then redirects the customer to the payment provider to complete the payment.
  • The unified payments endpoint is used to request a payment. The source type should be the desired payment method.
  • The payment response contains a redirect URL that your customer should be redirected to.
  • The iDEAL payment flow involves an additional step. Please refer to this page for more details.

What doesn't change

  • After your customer completes the payment, they are redirected back to your predefined success or failure URL.
  • You will be provided with a session ID in the URL, which can be used to retrieve the payment details.

The request

Endpoints

Classic APIUnified Payments API
http://api2.checkout.com/v2/tokens/payment
https://sandbox.checkout.com/api2/v2/tokens/payment
https://api.checkout.com/payments
https://api.sandbox.checkout.com/payments

Request examples

{
  "value": "2000",
  "currency": "EUR",
}
{
  "source" : {
    "type": "sofort",
  },
  "amount": "2000",
  "currency": "EUR",
  "reference": "TRK12345",
}

Digital wallets

What doesn’t change

Your existing integration with the digital wallet provider, allowing you to receive their tokens, does not change.

Classic APIUnified Payments API
  • The digital wallet provider’s token is exchanged for a Checkout.com token using the tokens endpoint.
  • The card charges endpoint is used to request a payment using a token.
  • A card ID is provided in the charge response, which can be used for subsequent payments with the same card information.
  • The digital wallet provider’s token is exchanged for a Checkout.com token using the token endpoint.
  • The unified payments endpoint is used to request a payment. A source type of token should be used.
  • A source ID is provided in the payment response, which can be used for subsequent payments with the same card information.

The request

Endpoints

Classic APIUnified Payments API
https://api2.checkout.com/v2/charges/token
https://sandbox.checkout.com/api2/v2/charges/token
https://api.checkout.com/payments
https://api.sandbox.checkout.com/payments

Request examples

{
  "autoCapture": "Y",
  "email": "s.mitchell@checkout.com",
  "value": "2000",
  "currency": "USD",
  "trackId": "TRK12345",
  "cardToken": "tok_5xgrat2fiuzeraaym3qn2ozdoq"
}
{ 
  "source": {
    "type": "token",
    "token": "tok_5xgrat2fiuzeraaym3qn2ozdoq",
  },
  "amount": 2000,
  "currency": "USD",
  "reference": "TRK12345",
}

Attribute comparisons

Below is a list of the key attributes that have changed in the Unified Payments API when requesting a payment.

Payment request

Attribute typeClassic APIUnified Payment API


Field

Required?FieldRequired?

3D Secure

Default = non-3D

chargeMode

  • 1 = non-3D
  • 2 = 3D
(error)

3ds.enabled

  • True
  • False
(error)

Attempt non-3D

Default = False

attemptN3D
  • True
  • False
(error)3ds.attempt_n3d
  • True
  • False
(error)

Risk checks

Default = enabled

riskCheck
  • True
  • False
(error)risk.enabled
  • True
  • False
(error)

Auto capture

Default = enabled

autoCapture
  • Y = true
  • N = false
(error)capture
  • True
  • False
(error)

Auto capture delay

Default = False

autoCapTime
  • Delay in hours
(error)capture_on
  • Timestamp of capture
(error)

Recurring payments

Default = Regular

transactionIndicator
  • 1 = Regular
  • 2 = Recurring
  • 3 = MOTO
(error)payment_type
  • "Regular"
  • Recurring
  • MOTO
(error)
Payment amountvalue(error)amount(error)
Billing descriptordescriptor(error)billing_descriptor(error)
Track IDtrackId(error)reference(error)
Customer IDcustomerId(tick)customer.id(error)
Customer namecustomerName(error)customer.name(error)
Customer emailemail(tick)customer.email(error)
Customer IP addresscustomerIp(error)payment_ip(error)
Shipping addressshippingDetails(error)shipping.address(error)
Shipping address phoneshippingDetails.phone(error)shipping.phone(error)
User defined fieldsudf1...5(error)metadata.udf1...5(error)

Payment response

Attribute typeClassic APIUnified Payments API
Flagged transactionResponse code: 10100risk.flagged: true
3D Secure parameters
  • eci
  • enrolled
  • cavv
  • xid
  • signatureValid
  • authenticationResponse
  • eci
  • 3ds.enrolled
  • 3ds.cryptogram
  • 3ds.xid
  • 3ds.signature_valid
  • 3ds.authentication_response
Acquirer auth codeauthCodeauth_code
Response coderesponseCoderesponse_code
Response summaryresponseSummaryresponse_summary
Customer IDcard.customerIdcustomer.id
Customer namecustomerNamecustomer.name
Customer emailemailcustomer.email
AVS check resultcard.avsChecksource.avs_check
CVV check resultcard.cvvChecksource.cvv_check
Customer IP addresscustomerIppayment_ip
Requested timecreatedrequested_on
Approved paymentResponse code: 10000approved

Webhook events

The Unified Payments solution supports all of our existing webhook event types and introduces a number of new ones, aiming to provide you with a more granular level of notification. If you request a payment using the Unified Payments API, you will receive only its associated webhook event types.

Classic APIUnified Payments APIDescription
charge.succeededpayment_approvedOccurs when a payment is approved by an acquirer/ provider.
charge.pendingpayment_pendingOccurs on asynchronous payments or when further action is required.
charge.failedpayment_declinedOccurs when a payment is declined by an acquirer/provider or due to a timeout.
invoice.cancelledpayment_expiredOccurs when an alternative payment link is generated by the merchant but not accessed by the customer.
charge.voidedpayment_voidedOccurs when an authorized payment is voided by an acquirer.
-payment_canceledOccurs an end user cancels the payment through a provider’s interface.
charge.voided.failedpayment_void_declinedOccurs when a void attempt is declined by an acquirer/provider or due to a timeout.
charge.capturedpayment_capturedOccurs when an authorized card payment is captured by an acquirer or when an alternative payment capture is completed by the provider.
charge.captured.failedpayment_capture_declinedOccurs when a capture is declined by the acquirer or due to a timeout.
charge.captured.deferredpayment_capture_pendingOccurs when a payment is being captured by an acquirer.
charge.refundedpayment_refundedOccurs when a captured payment is refunded by an acquirer.
charge.refunded.failedpayment_refund_failedOccurs when a payment refund is declined by an acquirer or due to a timeout.
-payment_refund_pendingOccurs when a payment is being refunded by an acquirer.
charge.chargebackAs a part of the Disputes API, we have launched a number of additional webhooks.More details can be found in our Disputes API documentation.
charge.retrievalAs a part of the Disputes API, we have launched a number of additional webhooks.More details can be found in our Disputes API documentation.
-card_verifiedOccurs when a card verification is approved by an acquirer/provider.
-card_verification_declinedOccurs when a card verification is declined by an acquirer/provider or due to a timeout.