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": true14}15}
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 |
---|---|
|
|
Classic API | Unified Payments API |
---|---|
|
|
1{2"email": "[email protected]",3"value": "2000",4"currency": "USD",5"trackId": "TRK12345",6"cardToken": "card_tok_9EDE49...A52CC25"7}
- 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 |
Classic API | Unified Payments API |
---|---|
|
|
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}
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 |
Classic API | Unified Payments API |
---|---|
|
|
1{2"autoCapture": "Y",3"value": "2000",4"currency": "USD",5"trackId": "TRK12345",6"customerId": "cust_9F8E74...CEE5270BF38A"7}
Classic API | Unified Payments API |
---|---|
|
|
Classic API | Unified Payments API |
---|---|
|
|
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}
Classic API | Unified 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. |
- 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 |
---|---|
|
|
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}
Your existing integration with the digital wallet provider, allowing you to receive their tokens, does not change.
Classic API | Unified Payments API |
---|---|
|
|
Classic API | Unified Payments API |
---|---|
|
|
1{2"autoCapture": "Y",3"email": "[email protected]",4"value": "2000",5"currency": "USD",6"trackId": "TRK12345",7"cardToken": "tok_5xgrat2fiuzeraaym3qn2ozdoq"8}
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 |
|
| ||
Attempt non-3D Default = False |
|
| ||
Risk checks Default = enabled |
|
| ||
Auto capture Default = enabled |
|
| ||
Auto capture delay Default = False |
|
| ||
Recurring payments Default = Regular |
|
| ||
Payment amount |
|
| ||
Billing descriptor |
|
| ||
Track ID |
|
| ||
Customer ID |
|
| ||
Customer name |
|
| ||
Customer email |
|
| ||
Customer IP address |
|
| ||
Shipping address |
|
| ||
Shipping address phone |
|
| ||
User defined fields |
|
|
Attribute type | Classic API | Unified Payments API |
---|---|---|
Flagged transaction | Response code: |
|
3D Secure parameters |
|
|
Acquirer auth code |
|
|
Response code |
|
|
Response summary |
|
|
Customer ID |
|
|
Customer name |
|
|
Customer email |
|
|
AVS check result |
|
|
CVV check result |
|
|
Customer IP address |
|
|
Requested time |
|
|
Approved payment | Response code: |
|
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 |
---|---|---|
|
| Occurs when a payment is approved by an acquirer/ provider. |
|
| Occurs on asynchronous payments or when further action is required. |
|
| Occurs when a payment is declined by an acquirer/provider or due to a timeout. |
|
| Occurs when an alternative Payment Link is generated by the merchant but not accessed by the customer. |
|
| Occurs when an authorized payment is voided by an acquirer. |
- |
| Occurs an end user cancels the payment through a provider’s interface. |
|
| Occurs when a void attempt is declined by an acquirer/provider or due to a timeout. |
|
| Occurs when an authorized card payment is captured by an acquirer or when an alternative payment capture is completed by the provider. |
|
| Occurs when a capture is declined by the acquirer or due to a timeout. |
|
| Occurs when a payment is being captured by an acquirer. |
|
| Occurs when a captured payment is refunded by an acquirer. |
|
| Occurs when a payment refund is declined by an acquirer or due to a timeout. |
- |
| Occurs when a payment is being refunded by an acquirer. |
| 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. |
| 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. |
- |
| Occurs when a card verification is approved by an acquirer/provider. |
- |
| Occurs when a card verification is declined by an acquirer/provider or due to a timeout. |