Skip to content

Migration guide

Last updated: 13th January 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.

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.

Boleto ticket render example

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
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    {
    "source" : {
    "type" : "card",
    "number" : "4242424242424242",
    "expiry_year" : 2019,
    "expiry_month" : 03,
    "cvv" : "100"
    },
    "amount" : "2000",
    "currency" : "USD",
    "reference": "TRK12345",
    "3ds" : {
    "enabled": true,
    }
    }

    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 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
      1
      https://api2.checkout.com/v2/charges/token
        1
        https://api.checkout.com/payments

        Request examples

          1
          2
          3
          4
          5
          6
          7
          {
          "email": "s.mitchell@checkout.com",
          "value": "2000",
          "currency": "USD",
          "trackId": "TRK12345",
          "cardToken": "card_tok_9EDE49...A52CC25"
          }

          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
            1
            https://api2.checkout.com/v2/charges/token
              1
              https://api.checkout.com/payments

              Request examples

                1
                2
                3
                4
                5
                6
                7
                8
                9
                {
                "autoCapture": "Y",
                "email": "sarah.mitchell@checkout.com",
                "value": "2000",
                "currency": "USD",
                "trackId": "TRK12345",
                "cardId": "card_930C63F9.....0B5D2CFB5AF",
                "cvv": "100",
                }

                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
                  1
                  https://api2.checkout.com/v2/charges/customer
                    1
                    https://api.checkout.com/payments

                    Request examples

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

                      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
                        1
                        https://api2.checkout.com/v2/charges/card
                          1
                          https://api.checkout.com/payments

                          Request examples

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

                            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
                              1
                              https://api2.checkout.com/v2/charges/localpayment
                                1
                                https://api.checkout.com/payments

                                Request examples

                                  1
                                  2
                                  3
                                  4
                                  5
                                  6
                                  7
                                  8
                                  9
                                  10
                                  11
                                  12
                                  13
                                  14
                                  15
                                  16
                                  17
                                  18
                                  // 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",
                                  }
                                  }

                                  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 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
                                    1
                                    https://api2.checkout.com/v2/charges/token
                                      1
                                      https://api.checkout.com/payments

                                      Request examples

                                        1
                                        2
                                        3
                                        4
                                        5
                                        6
                                        7
                                        8
                                        {
                                        "autoCapture": "Y",
                                        "email": "s.mitchell@checkout.com",
                                        "value": "2000",
                                        "currency": "USD",
                                        "trackId": "TRK12345",
                                        "cardToken": "tok_5xgrat2fiuzeraaym3qn2ozdoq"
                                        }

                                        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 APIClassic APIUnified Payment APIUnified 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

                                        Payment response

                                        Attribute typeClassic APIUnified 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

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