Checkout.js migration guide

Last updated: April 29, 2022

If you’re using Checkout.js with our Classic API, you should upgrade to one of our new integration options to benefit from our latest features.

This guide compares the payment flows of each option, helping you to decide which integration option is best for you.

You can choose between a Hosted Payments Page or Frames. Like Checkout.js, both solutions present a form to your customer where they can enter their payment information. We then convert the payment details into a temporary token, which you can use to make a payment request, without having to handle any sensitive information yourself.

Checkout.js is our legacy solution, built on our Classic API.

Note

As of May 2021, the Classic API is only receiving security updates.

The following is a reminder of the payment flow with Checkout.js.

From the server side, send a POST request to our /api2/v2/tokens/payment endpoint, providing information about the payment you want to process. For example:


1{
2  "value": 1000,
3  "currency": "EUR"
4}

And the response from our Classic API would look like:


1{
2  "id": "pay_tok_7B1D75B9-6214-4A6E-B209-90610D13C002",
3  "liveMode": false
4}

Once you’ve generated a payment token, pass it in the configuration of Checkout.js and render a lightbox for your customer so they can choose how to pay (with a card or a local payment method, like Sofort).

Here's an example of a configuration:


1<script src="https://cdn.checkout.com/sandbox/js/checkout.js"></script>
2<form class="payment-form" method="POST" action="server/autocapture.php">
3  <input name="cko-card-token" id="input-id" value="" hidden />
4</form>
5
6<button onclick="Checkout.open()">PAY EUR 100.00</button>
7
8<script>
9  Checkout.configure({
10    publicKey: “pk_test_ac89202e-4531-43b3-a830-9e4f0151cd49”,
11    paymentToken: “pay_tok_7B1D75B9-6214-4A6E-B209-90610D13C002”,
12    customerEmail: "[email protected]",
13    value: 10000,
14    currency: "EUR",
15    paymentMode: "mixed"   // allows both cards and local payments
16  });
17</script>

Our Hosted Payments Page integration option is a fast and easy way to collect your customer’s payment information and process the payment request.

Preview a Hosted Payments Page with the demo below. Try it with the following test card or Sofort details.

Card number: 4242 4242 4242 4242
Expiry date: Any future date
CVV: 100

The Hosted Payment Page payment flow offers a similar experience to Checkout.js.

Call our /hosted-payments endpoint, providing information about the transaction and billing location.

We’ll use this information to render a payment page tailored to your customer’s region where they can enter their payment details. Here’s an example request:


1{
2  "amount": 1000,
3  "currency": "EUR",
4  "billing": {
5    "address": {
6      "country": "DE"
7    }
8  },
9  "success_url": "https://checkout.com/success",
10  "cancel_url": "https://checkout.com/cancel",
11  "failure_url": "https://checkout.com/fail"
12}

In the response you'll get a redirect link for the Hosted Payments Page. Here's an example:


1{
2  "_links": {
3    "redirect": {
4      "href": "https://pay.sandbox.checkout.com/page/uUuwh39apxXS"
5    }
6  }
7}

Once you’ve got the link to the Hosted Payment Page, redirect your customer to it. They will enter their payment details on the page and then get sent to either your success or failure page.

You don’t have to worry about managing the session. When we redirect the customer back to your page, we provide a session ID (cko-session-id) or payment ID (cko-payment-id) as a query parameter in the URL, which you can pass into our get payment details endpoint to get a full overview of the payment.

Note

Out of the box, you can also accept iDEAL, KNET, Mada, PayPal, and Sofort with a Hosted Payments Page. You can integrate more payment methods if you want.

Information

You can sign up to webhook notifications to let you know how the payment is progressing. If you have an order management system, webhooks are useful where, for example, you want to dispatch the goods or provide services only after you know the payment has been captured (meaning the money has actually been taken from the customer’s account).

Frames is a customizable payment form that collects and tokenizes your customers' payment details. It offers more customization options than a Hosted Payment Page, giving you more control over the checkout experience.

Preview Frames with the demo below. Enter 4242424242424242 as the card number, any future expiry date, and 100 for the CVV.

Frames allows you to securely collect the card details of your customers, exchanging the sensitive card information for a secure token (single use, expiring after 15 minutes) you can use to make a payment request.

Once you've received the token from Frames, call our /payments endpoint from your server to process a payment. Here’s an example of a payment request:


1{
2  "source": {
3    "type": "token",
4    "token": "{{the_token_generated_by_frames}}"
5  },
6  "amount": 1000,
7  "currency": "EUR"
8}

After you send a payment request you’ll receive the authorization response – whether the payment was accepted or not. You can use this response to show your customer a success or failure outcome page or message.

Information

Frames is designed to collect card details and exchange them for a secure payment token, but you can also use it to accept local payment methods, integrating them using our Unified Payments API.

For example, let’s say you want to accept payments with Sofort. First, you need to create a ‘pay with Sofort’ button, or checkbox, the customer can interact with. Then, when they choose this option, you call our payments API with the necessary information required for a Sofort payment to receive a redirect link. Once you’ve got the link, use it to redirect your customer to the payment page and then handle the outcome.

Checkout.js migration guide

Checkout.js

Note

Payment flow

1. Create a payment token

2. Initialize Checkout.js with the payment token

Hosted Payments Page

Try it out

Payment flow

1. Create a Hosted Payments Page

2. Present the Hosted Payments Page and handle the outcome

Note

Information

Frames

Try it out

Payment flow

1. Collect card details

2. Send a payment request

3. Handle the outcome

Information

Accepting local payment methods

Next steps

Hosted Payments Page

Frames