Migration guide

Last updated: April 29, 2022

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.

Tip

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

Information

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

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.

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 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.

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

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.

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.


1{
2  "source": {
3    "type": "card",
4    "number": "4242424242424242",
5    "expiry_year": 2019,
6    "expiry_month": 3,
7    "cvv": "100"
8  },
9  "amount": "2000",
10  "currency": "USD",
11  "reference": "TRK12345",
12  "3ds": {
13    "enabled": true
14  }
15}


1{
2  "id": "pay_g3avvtweex5e7prna4vkupdkle",
3  "status": "Pending",
4  "reference": "TRK12345",
5  "customer": {
6    "id": "cus_mp6evgbj4bzevmnpxgsq7bdcgy"
7  },
8  "3ds": {
9    "downgraded": false,
10    "enrolled": "Y"
11  },
12  "_links": {
13    "self": {
14      "href": "https://api.sandbox.checkout.com/payments/pay_g3avvtweex5e7prna4vkupdkle"
15    },
16    "redirect": {
17      "href": "https://sandbox.checkout.com/api2/v2/3ds/acs/sid_vwipcigm6k2ubcvl2rzbovpysy"
18    }
19  }
20}

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.

Your existing front-end solution (e.g., Frames, 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.

Classic API	Unified 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.

Classic API Unified Payments API

Classic API	Unified Payments API
`1https://api2.checkout.com/v2/charges/token`	`1https://api.checkout.com/payments`


1https://api2.checkout.com/v2/charges/token


1https://sandbox.checkout.com/api2/v2/charges/token


1https://api.checkout.com/payments


1https://api.sandbox.checkout.com/payments


1{
2  "email": "[email protected]",
3  "value": "2000",
4  "currency": "USD",
5  "trackId": "TRK12345",
6  "cardToken": "card_tok_9EDE49...A52CC25"
7}


1{
2  "source": {
3    "type": "token",
4    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
5  },
6  "amount": 2000,
7  "currency": "USD",
8  "reference": "TRK12345"
9}

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.

Classic API	Unified 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.

Classic API Unified Payments API

Classic API	Unified Payments API
`1https://api2.checkout.com/v2/charges/token`	`1https://api.checkout.com/payments`


1https://api2.checkout.com/v2/charges/token


1https://sandbox.checkout.com/api2/v2/charges/token


1https://api.checkout.com/payments


1https://api.sandbox.checkout.com/payments


1{
2  "autoCapture": "Y",
3  "email": "[email protected]",
4  "value": "2000",
5  "currency": "USD",
6  "trackId": "TRK12345",
7  "cardId": "card_930C63F9.....0B5D2CFB5AF",
8  "cvv": "100"
9}


1{
2  "source": {
3    "type": "id",
4    "id": "src_i3ywxkcgu5cevigmdxoy6km5je",
5    "cvv": "100"
6  },
7  "amount": 2000,
8  "currency": "USD",
9  "reference": "TRK12345"
10}

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.

Classic API	Unified 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.

Classic API Unified Payments API

Classic API	Unified Payments API
`1https://api2.checkout.com/v2/charges/customer`	`1https://api.checkout.com/payments`


1https://api2.checkout.com/v2/charges/customer


1https://sandbox.checkout.com/api2/v2/charges/customer


1https://api.checkout.com/payments


1https://api.sandbox.checkout.com/payments


1{
2  "autoCapture": "Y",
3  "value": "2000",
4  "currency": "USD",
5  "trackId": "TRK12345",
6  "customerId": "cust_9F8E74...CEE5270BF38A"
7}


1{
2  "source": {
3    "type": "customer",
4    "id": "cus_dxbrk2ruktbutlnbtilhv2qyzm"
5  },
6  "amount": 2000,
7  "currency": "USD",
8  "reference": "TRK12345"
9}

Classic API	Unified 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.

Classic API Unified Payments API

Classic API	Unified Payments API
`1https://api2.checkout.com/v2/charges/card`	`1https://api.checkout.com/payments`


1https://api2.checkout.com/v2/charges/card


1https://sandbox.checkout.com/api2/v2/charges/card


1https://api.checkout.com/payments


1https://api.sandbox.checkout.com/payments


1{
2  "email": "[email protected]",
3  "value": "2000",
4  "currency": "USD",
5  "trackId": "TRK12345",
6  "card": {
7    "name": "Sarah Mitchell",
8    "number": "4242424242424242",
9    "expiryMonth": "9",
10    "expiryYear": "2019",
11    "cvv": "100"
12  }
13}


1{
2  "source": {
3    "type": "card",
4    "number": "4242424242424242",
5    "expiry_month": 9,
6    "expiry_year": 2019,
7    "cvv": "100"
8  },
9  "amount": 2000,
10  "currency": "USD",
11  "reference": "TRK12345"
12}

Classic API	Unified Payments API
The payment token endpoint is used to create a payment token. The local payment endpoint is used to request a payment using the payment token.	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.

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.

Classic API Unified Payments API

Classic API	Unified Payments API
`1https://api2.checkout.com/v2/charges/localpayment`	`1https://api.checkout.com/payments`


1https://api2.checkout.com/v2/charges/localpayment


1https://sandbox.checkout.com/api2/v2/charges/localpayment


1https://api.checkout.com/payments


1https://api.sandbox.checkout.com/payments


1{
2  "value": "2000",
3  "currency": "EUR",
4  "chargemode": "3"
5}


1{
2  "email": "[email protected]",
3  "paymentToken": "pay_tok_6E5D1D...339A4B4B83E5",
4  "trackId": "TRK12345",
5  "localPayment": {
6    "lppId": "lpp_14"
7  }
8}


1{
2  "source": {
3    "type": "sofort"
4  },
5  "amount": "2000",
6  "currency": "EUR",
7  "reference": "TRK12345"
8}

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

Classic API	Unified 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.

Classic API Unified Payments API

Classic API	Unified Payments API
`1https://api2.checkout.com/v2/charges/token`	`1https://api.checkout.com/payments`


1https://api2.checkout.com/v2/charges/token


1https://sandbox.checkout.com/api2/v2/charges/token


1https://api.checkout.com/payments


1https://api.sandbox.checkout.com/payments


1{
2  "autoCapture": "Y",
3  "email": "[email protected]",
4  "value": "2000",
5  "currency": "USD",
6  "trackId": "TRK12345",
7  "cardToken": "tok_5xgrat2fiuzeraaym3qn2ozdoq"
8}


1{
2  "source": {
3    "type": "token",
4    "token": "tok_5xgrat2fiuzeraaym3qn2ozdoq"
5  },
6  "amount": 2000,
7  "currency": "USD",
8  "reference": "TRK12345"
9}

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

Attribute type	Classic API	Classic API	Unified Payment API	Unified Payment API
	Field	Required?	Field	Required?
3D Secure Default = non-3D	`chargeMode` 1 = non-3D 2 = 3D		`3ds.enabled` True False
Attempt non-3D Default = False	`attemptN3D` True False		`3ds.attempt_n3d` True False
Risk checks Default = enabled	`riskCheck` True False		`risk.enabled` True False
Auto capture Default = enabled	`autoCapture` Y = true N = false		`capture` True False
Auto capture delay Default = False	`autoCapTime` Delay in hours		`capture_on` Timestamp of capture
Recurring payments Default = Regular	`transactionIndicator` 1 = Regular 2 = Recurring 3 = MOTO		`payment_type` "Regular" Recurring MOTO
Payment amount	`value`		`amount`
Billing descriptor	`descriptor`		`billing_descriptor`
Track ID	`trackId`		`reference`
Customer ID	`customerId`		`customer.id`
Customer name	`customerName`		`customer.name`
Customer email	`email`		`customer.email`
Customer IP address	`customerIp`		`payment_ip`
Shipping address	`shippingDetails`		`shipping.address`
Shipping address phone	`shippingDetails.phone`		`shipping.phone`
User defined fields	`udf1...5`		`metadata.udf1...5`

Attribute type	Classic API	Unified Payments API
Flagged transaction	Response code: `10100`	`risk.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 code	`authCode`	`auth_code`
Response code	`responseCode`	`response_code`
Response summary	`responseSummary`	`response_summary`
Customer ID	`card.customerId`	`customer.id`
Customer name	`customerName`	`customer.name`
Customer email	`email`	`customer.email`
AVS check result	`card.avsCheck`	`source.avs_check`
CVV check result	`card.cvvCheck`	`source.cvv_check`
Customer IP address	`customerIp`	`payment_ip`
Requested time	`created`	`requested_on`
Approved payment	Response code: `10000`	`approved`

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 API	Unified Payments API	Description
`charge.succeeded`	`payment_approved`	Occurs when a payment is approved by an acquirer/ provider.
`charge.pending`	`payment_pending`	Occurs on asynchronous payments or when further action is required.
`charge.failed`	`payment_declined`	Occurs when a payment is declined by an acquirer/provider or due to a timeout.
`invoice.cancelled`	`payment_expired`	Occurs when an alternative Payment Link is generated by the merchant but not accessed by the customer.
`charge.voided`	`payment_voided`	Occurs when an authorized payment is voided by an acquirer.
-	`payment_canceled`	Occurs an end user cancels the payment through a provider’s interface.
`charge.voided.failed`	`payment_void_declined`	Occurs when a void attempt is declined by an acquirer/provider or due to a timeout.
`charge.captured`	`payment_captured`	Occurs when an authorized card payment is captured by an acquirer or when an alternative payment capture is completed by the provider.
`charge.captured.failed`	`payment_capture_declined`	Occurs when a capture is declined by the acquirer or due to a timeout.
`charge.captured.deferred`	`payment_capture_pending`	Occurs when a payment is being captured by an acquirer.
`charge.refunded`	`payment_refunded`	Occurs when a captured payment is refunded by an acquirer.
`charge.refunded.failed`	`payment_refund_failed`	Occurs when a payment refund is declined by an acquirer or due to a timeout.
-	`payment_refund_pending`	Occurs when a payment is being refunded by an acquirer.
`charge.chargeback`	As 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.retrieval`	As 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_verified`	Occurs when a card verification is approved by an acquirer/provider.
-	`card_verification_declined`	Occurs when a card verification is declined by an acquirer/provider or due to a timeout.

Unified Payments is SCA-ready

Tip

Information

Single payments endpoint

Payment sources

Payments and actions

Updated SDKs

Handling response codes

3D Secure payments

Card token flow

What doesn't change

What changes

The request

Endpoints

Request examples

Card ID flow

What doesn’t change

What changes

The request

Endpoints

Request examples

Default card/customer flow

What doesn’t change

What changes

The request

Endpoints

Request examples

Full card details

What changes

The request

Endpoints

Request examples

Alternative payment methods

What changes

What doesn't change

The request

Endpoints

Request examples

Payment token request

Payment request

Digital wallets

What doesn’t change

What changes

The request

Endpoints

Request examples

Attribute comparisons

Payment request

Payment response

Webhook events