Commercetools
Last updated: April 29, 2022
Learn how to get started with our integration for commercetools.
Information
This guide assumes that you have already created a commercetools project. If you would like to test this integration, please contact partnerships.
Commercetools is an ecommerce platform that offers true cloud-native, headless commerce integration capabilities. The plugin makes it easier for those already using commercetools to integrate with Checkout.com.
Our integration has two parts:
- Configure our API Client in the commercetools Merchant Center.
- Set up the frontend, which involves integrating Frames for card payments and our Klarna SDK for Klarna payments.
If you haven't already, create a test Checkout.com account.
To set up our commercetools API Client, you'll need your public and secret API keys, which are generated automatically upon account creation.
- Log in to your test account on the Hub sandbox.
- In the left menu, go to Settings > Channels, and make a note of your secret and public API keys.

Information
Webhooks are notifications that we send when an event occurs on your account. For example, when a payment is captured. These are used by commercetools to update the status of an order. Read more about webhooks.
- Scroll down to the Webhooks section of the page and select New webhook.
- Enter the following URLs:
Webhook URL | Events |
---|---|
|
|
|
|
- Select API - v2.
- Select Create webhook.
Note
Correctly configuring your webhooks is important; if they're incorrectly formatted, our API Client will not work.
When a webhook is triggered on our side, our integration is creating or updating a transaction in commercetools to reflect the change.
These transactions are attached to a payment, and there may be multiple transactions attached to a single payment. This is all done automatically, and you don't have to do anything other than setting up the webhooks and configuring the API client.
You can see these interactions in your commercetools Merchant Center by going to Order list > Order and selecting the Payment tab.
Information
We do not automatically update the order or payment status. This allows you to build your own order flow.
Follow the steps below to create and configure the Checkout.com API Client on your commercetools site.
- Log in to the commercetools Merchant Center, go to Settings > Developer Settings and select Create API Client.
- Enter a name for this new API Client (e.g., cko-payment-integration).
- Select the following scopes:
- Manage: Orders
- Manage: Payments
- Select Create API Client.
- Copy the following details from the window displayed, and reach out to our Support team at [email protected] to assist you with onboarding:
- project_key
- client_id
- secret
- API URL
- Auth URL
Information
You must save this information, as it is only displayed once.
- Using commercetools' IMPEX, set
Types
asendpoint
, andcreate
ascommand
. Then copy and paste in the following JSON files to install them (make sure you're in the right project when doing this):
Next, set up the frontend part of our commercetools integration.
- Integrate Frames to accept card payments.
- Add our Klarna SDK (follow steps 2 and 3 on that page; we'll take care of the rest) to support Klarna payments.
If you are planning to accept SEPA payments, before any payment can occur, your customer must authorize the payment by accepting the terms of the mandate. By accepting, they are authorizing you to collect the specified amount from their bank account using SEPA Direct Debit. See Issue the mandate for more information
Now that you've set up the integration, you're ready to make a payment. You can make a payment in two steps:
- Create context
- Request payment
First, create a payment context. This returns the available payment options to the customer, and gives you a context_id
, with which you can then request a payment.
Expand the table below to see how our properties map to commercetools' properties.
Tip
We recommend that you create a context when your payment options page loads, and reload it if the customer makes a change to their basket or details.
post
https://commercetools.integration.checkout.com/api/contexts
Header | Value |
---|---|
required |
Use the valid public key of your Checkout.com account. You can find this in the Hub. |
required |
|
Field name | Description |
---|---|
string required | The commercetools cart or order ID. |
string optional | The customer's email. If not present, the billing email or the email from the order will be used. |
Creating the context above will give you a context_id
. Use this to request a payment with the following endpoint.
The commercetools integration currently supports the following payment methods:
- Card
- iDEAL
- Sofort
- Klarna
- PayPal
post
https://commercetools.integration.checkout.com/api/payments
Header | Value |
---|---|
required |
Use the valid public key of your Checkout.com account. You can find this in the Hub. |
required |
|
Field name | Description |
---|---|
string required | The type of payment method. Set this to |
string required | The ID of the payment context created above. |
string required | The Checkout.com token. |
string optional | The three-digit (or four digits for Amex) card verification value/code. |
boolean optional | Allows you to save the payment method for future use. |
object optional | Allows you to select whether the transaction should be 3D Secure authenticated. |
boolean required | Required if the |
string optional | Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge. Default: Possible values:
For more information about SCA, please refer to the SCA compliance guide. |
string optional | A reference you can use to later identify the payment. This populates the reference field in the Hub Leaving this blank will result in |
string optional | The URL to which the customer will be redirected if the payment is successful. |
string optional | The URL to which the customer will be redirected if the payment fails. |
The following endpoints allow you to retrieve a customer's saved payment instruments or delete them.
Use this endpoint to return a list of a customer's saved payment instruments.
get
https://commercetools.integration.checkout.com/api/merchants/{public_key}/customers/{customer_id}
Header | Value |
---|---|
required |
Use the valid secret key of your Checkout.com account. You can find this in the Hub. |
required |
|
Path | Description |
---|---|
required | Your Checkout.com public key. You can find this in the Hub. |
required | The customer's commercetools ID. |
Use the endpoint below to delete a customer's saved payment instrument.
delete
https://commercetools.integration.checkout.com/api/merchants/{public_key}/customers/{customer_id}/payment-instruments/{payment_instrument_id}
Header | Value |
---|---|
required |
Use the valid secret key of your Checkout.com account. You can find this in the Hub. |
required |
|
Path | Description |
---|---|
required | Your Checkout.com public key. You can find this in the Hub. |
required | The customer's commercetools ID. |
required | The unique identifier of the saved payment instrument. |
For more testing, commercetools have created a Postman collection.