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.
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..
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 .NET, Python, 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.
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.
Card token flow
What doesn't change
- 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.
What changes
Classic API | Unified Payments API |
---|---|
|
|
The request
Endpoints
Classic API | Unified Payments API |
---|---|
|
|
Request examples
1{2 "email": "s.mitchell@checkout.com",3 "value": "2000",4 "currency": "USD",5 "trackId": "TRK12345",6 "cardToken": "card_tok_9EDE49...A52CC25"7 }
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 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 |
The request
Endpoints
Classic API | Unified Payments API |
---|---|
|
|
Request examples
1{2 "autoCapture": "Y",3 "email": "sarah.mitchell@checkout.com",4 "value": "2000",5 "currency": "USD",6 "trackId": "TRK12345",7 "cardId": "card_930C63F9.....0B5D2CFB5AF",8 "cvv": "100"9}
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 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 |
The request
Endpoints
Classic API | Unified Payments API |
---|---|
|
|
Request examples
1{2 "autoCapture": "Y",3 "value": "2000",4 "currency": "USD",5 "trackId": "TRK12345",6 "customerId": "cust_9F8E74...CEE5270BF38A"7 }
Full card details
What changes
Classic API | Unified Payments API |
---|---|
|
|
The request
Endpoints
Classic API | Unified Payments API |
---|---|
|
|
Request examples
1{2 "email": "sarah.mitchell@checkout.com",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 }
Alternative payment methods
What changes
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. |
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 API | Unified Payments API |
---|---|
|
|
Request examples
Payment token request
1{2 "value": "2000",3 "currency": "EUR",4 "chargemode": "3"5}
Payment request
1{2 "email": "s.mitchell@checkout.com",3 "paymentToken": "pay_tok_6E5D1D...339A4B4B83E5",4 "trackId": "TRK12345",5 "localPayment": {6 "lppId": "lpp_14"7 }8}
Digital wallets
What doesn’t change
Your existing integration with the digital wallet provider, allowing you to receive their tokens, does not change.
What changes
Classic API | Unified Payments API |
---|---|
|
|
The request
Endpoints
Classic API | Unified Payments API |
---|---|
|
|
Request examples
1{2 "autoCapture": "Y",3 "email": "s.mitchell@checkout.com",4 "value": "2000",5 "currency": "USD",6 "trackId": "TRK12345",7 "cardToken": "tok_5xgrat2fiuzeraaym3qn2ozdoq"8 }
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 type | Classic API | Classic API | Unified Payment API | Unified Payment API | ||
---|---|---|---|---|---|---|
Field | Required? | Field | Required? | |||
3D Secure
|
|
| ||||
Attempt non-3D
|
|
| ||||
Risk checks
|
|
| ||||
Auto capture
|
|
| ||||
Auto capture delay
|
|
| ||||
Recurring payments
|
|
| ||||
Payment amount |
|
| ||||
Billing descriptor |
|
| ||||
Track ID |
|
| ||||
Customer ID |
|
| ||||
Customer name |
|
| ||||
Customer email |
|
| ||||
Customer IP address |
|
| ||||
Shipping address |
|
| ||||
Shipping address phone |
|
| ||||
User defined fields |
|
|
Payment response
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: |
|
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 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. |