Headless integration

Last updated: November 11, 2022

The Checkout.com Shopware 6 extension allows you to create seamless payment experiences using the plugin’s API endpoints.

The following is a list of our public API endpoints that allow you to implement the Checkout.com Payments plugin with a headless setup.

To ensure successful authentication and authorization, include sw-access-key and sw-context-token as headers in all your requests.

Validates a merchant’s URL for Apple Pay.

post

/store-api/checkout-com/validate-merchant


1{
2  "validationURL": "https://example.com"
3}


1{
2  "success": "string",
3  "merchant": {}
4}

Returns the Checkout.com Payments plugin configuration.

get

/store-api/checkout-com/config


1{
2  "success": "string",
3  "configs": {
4    "frameUrl": "string",
5    "klarnaCdnUrl": "string",
6    "publicKey": "string",
7    "sandboxMode": true,
8    "googlePayMerchantId": "string"
9  }
10}

Creates a card payment token.

post

/store-api/checkout-com/card-payment/token


1{
2  "name": "string",
3  "number": "string",
4  "expiryMonth": 0,
5  "expiryYear": 0,
6  "cvv": "string"
7}


1{
2  "success": "string",
3  "token": "string"
4}

Adds a product to a direct cart. A direct cart is used when a customer pays for a product using a direct pay button, available for Google Pay and Apple Pay on the listing page and product details page.

post

/store-api/checkout-com/direct/add-product-to-cart


1{
2  "productId": "string",
3  "productQuantity": 0
4}


1{
2  "success": true,
3  "cartToken": "string"
4}

Removes the specified back-up cart.

post

/store-api/checkout-com/direct/remove-backup


1{
2  "cartToken": "string"
3}

If your request is successful, you'll receive a 200 HTTP response code.

Gets shipping methods for direct pay, and calculates the direct cart using the selected shipping method in the context.

post

/store-api/checkout-com/direct/get-shipping-methods


1{
2  "paymentMethodType": "applepay",
3  "cartToken": "string",
4  "countryCode": "string"
5}


1{
2  "success": "string",
3  "shippingPayload": {
4    "newShippingMethods": [
5      {
6        "identifier": "string",
7        "label": "string",
8        "amount": 0,
9        "detail": "string"
10      }
11    ],
12    "newTotal": {
13      "label": "string",
14      "amount": 0,
15      "type": "string"
16    },
17    "newLineItems": [
18      {
19        "label": "string",
20        "amount": 0,
21        "type": "string"
22      }
23    ]
24  }
25}

Calculates the direct cart for the specified shipping method.

post

/store-api/checkout-com/direct/update-shipping-payload


1{
2  "paymentMethodType": "applepay",
3  "cartToken": "string",
4  "shippingMethodId": "string"
5}


1{
2  "success": "string",
3  "shippingPayload": {
4    "newShippingMethods": [
5      {
6        "identifier": "string",
7        "label": "string",
8        "amount": 0,
9        "detail": "string"
10      }
11    ],
12    "newTotal": {
13      "label": "string",
14      "amount": 0,
15      "type": "string"
16    },
17    "newLineItems": [
18      {
19        "label": "string",
20        "amount": 0,
21        "type": "string"
22      }
23    ]
24  }
25}

Processes a payment made using a direct pay button.

post

/store-api/checkout-com/direct/process-payment


1{
2  "paymentMethodType": "applepay",
3  "cartToken": "string",
4  "shippingContact": {
5    "countryCode": "string",
6    "countryStateCode": "string",
7    "firstName": "string",
8    "lastName": "string",
9    "email": "string",
10    "phoneNumber": "string",
11    "street": "string",
12    "additionalAddressLine1": "string",
13    "zipCode": "string",
14    "city": "string"
15  }
16}


1{
2  "success": true,
3  "redirectUrl": "string"
4}

Creates a Klarna session when a customer reaches the checkout page.

post

/store-api/checkout-com/klarna/credit-sessions


1{
2  "orderId": "string"
3}


1{
2  "success": true,
3  "creditSession": {
4    "session_id": "string",
5    "client_token": "string",
6    "payment_method_categories": [
7      {
8        "name": "string",
9        "identifier": "string",
10        "asset_urls": {
11          "descriptive": "string",
12          "standard": "string"
13        }
14      }
15    ]
16  }
17}

Deletes the source ID of the payment method from the customer.

delete

/checkout-com/source


1{
2  "sourceId": "string"
3}

If your request is successful, you'll receive a 204 HTTP response code.

Create a log in session with the customer credentials. After logging in, Shopware will return a context, which contains information needed for later steps.

post

/store-api/account/login


1{
2  "username": "customer@test.com",
3  "password": "customer"
4}


1{
2  "apiAlias": "array_struct",
3  "contextToken": "gyCDpNMo7E2Q3CzxMlKQdHDiLJIx8Grj",
4  "redirectUrl": null
5}

Get a list of available payment methods.

get

/store-api/payment-method


1{
2  "entity": "payment_method",
3  "total": 3,
4  "aggregations": [],
5  "page": 1,
6  "limit": 100,
7  "elements": [
8    {
9      "name": "Card Payments",
10      "distinguishableName": "Card Payments | Checkout.com Payments",
11      "description": null,
12      "position": 1,
13      "active": true,
14      "afterOrderEnabled": true,
15      "translations": null,
16      "mediaId": null,
17      "media": null,
18      "shortName": "card_payment_handler",
19      "synchronous": false,
20      "asynchronous": true,
21      "prepared": false,
22      "refundable": false,
23      "_uniqueIdentifier": "c70fe6a9d10d452796aede8ecf100b0f",
24      "versionId": null,
25      "translated": {
26        "name": "Card Payments",
27        "distinguishableName": "Card Payments | Checkout.com Payments",
28        "description": null,
29        "customFields": {}
30      },
31      "createdAt": "2022-10-14T07:17:17.089+00:00",
32      "updatedAt": "2022-10-17T10:49:23.765+00:00",
33      "extensions": {
34        "foreignKeys": {
35          "apiAlias": "array_struct"
36        }
37      },
38      "id": "c70fe6a9d10d452796aede8ecf100b0f",
39      "customFields": {
40        "checkoutConfig": {
41          "methodType": "card",
42          "extensions": []
43        }
44      },
45      "apiAlias": "payment_method"
46    }
47  ],
48  "states": [],
49  "apiAlias": "dal_entity_search_result"
50}

Find the ID of the payment method you want to use and pass it to the context.

patch

/store-api/context


1{
2  "paymentMethodId": "<payment-method-id>"
3}


1{
2  "apiAlias": "array_struct",
3  "contextToken": "eakh7cAQgpq5ED5VCkeGPGNeEcBsR5dF",
4  "redirectUrl": null
5}

Get the current cart or create a new one.

get

store-api/checkout/cart


1{
2  "name": "sales-channel",
3  "token": "eakh7cAQgpq5ED5VCkeGPGNeEcBsR5dF",
4  "price": {
5    "netPrice": 0,
6    "totalPrice": 0,
7    "calculatedTaxes": [],
8    "taxRules": [],
9    "positionPrice": 0,
10    "taxStatus": "gross",
11    "rawTotal": 0,
12    "apiAlias": "cart_price"
13  },
14  "lineItems": [],
15  "errors": [],
16  "deliveries": [],
17  "transactions": [
18    {
19      "amount": {
20        "unitPrice": 0,
21        "quantity": 1,
22        "totalPrice": 0,
23        "calculatedTaxes": [],
24        "taxRules": [],
25        "referencePrice": null,
26        "listPrice": null,
27        "regulationPrice": null,
28        "apiAlias": "calculated_price"
29      },
30      "paymentMethodId": "5356067bef4f4719b5a4f9044df1f40e",
31      "apiAlias": "cart_transaction"
32    }
33  ],
34  "modified": false,
35  "customerComment": null,
36  "affiliateCode": null,
37  "campaignCode": null,
38  "extensions": {
39    "cart-promotions": {
40      "addedCodes": [],
41      "blockedPromotionIds": [],
42      "apiAlias": "shopware_core_checkout_promotion_cart_extension_cart_extension"
43    }
44  },
45  "apiAlias": "cart"
46}

Get a list of products.

get

/store-api/product

If your request is successful, you'll receive a response that contains a list of objects representing available products.

Add an item to the cart using the product id returned in the previous step.

post

/store-api/checkout/cart/line-item


1{
2  "items": [
3    {
4      "id": "<product-id>",
5      "referencedId": "<product-id>",
6      "quantity": 1,
7      "type": "product",
8      "good": true,
9      "removable": true,
10      "stackable": true,
11      "modified": true
12    }
13  ]
14}


1{
2  "name": "f183ee5650cf4bdb8a774337575067a6",
3  "token": "eakh7cAQgpq5ED5VCkeGPGNeEcBsR5dF",
4  "price": {
5    "netPrice": 0,
6    "totalPrice": 0,
7    "calculatedTaxes": [],
8    "taxRules": [],
9    "positionPrice": 0,
10    "taxStatus": "gross",
11    "rawTotal": 0,
12    "apiAlias": "cart_price"
13  },
14  "lineItems": [],
15  "errors": [],
16  "deliveries": [],
17  "transactions": [
18    {
19      "amount": {
20        "unitPrice": 0,
21        "quantity": 1,
22        "totalPrice": 0,
23        "calculatedTaxes": [],
24        "taxRules": [],
25        "referencePrice": null,
26        "listPrice": null,
27        "regulationPrice": null,
28        "apiAlias": "calculated_price"
29      },
30      "paymentMethodId": "5356067bef4f4719b5a4f9044df1f40e",
31      "apiAlias": "cart_transaction"
32    }
33  ],
34  "modified": false,
35  "customerComment": null,
36  "affiliateCode": null,
37  "campaignCode": null,
38  "extensions": {
39    "cart-promotions": {
40      "addedCodes": [],
41      "blockedPromotionIds": [],
42      "apiAlias": "shopware_core_checkout_promotion_cart_extension_cart_extension"
43    }
44  },
45  "apiAlias": "cart"
46}

After adding the required products, create an order from the cart.

post

/store-api/checkout/order

After an order has been created, initiate a payment for the order using the newly created orderId. Note that the checkoutComDetails object will differ depending on the chosen payment method.

post

/store-api/handle-payment


1{
2  "orderId": "<id-of-the-order>",
3  "finishUrl": "<successful-payment-url>",
4  "errorUrl": "<failed-payment-url>",
5  "checkoutComDetails": {}
6}

Learn how to initiate a payment for different Checkout.com payment methods.

To accept card payments, you'll need a card payment token. You can generate a payment token using Frames or the following API endpoint:

post

/store-api/checkout-com/card-payment/token


1{
2  "name": "<card-holder-name>",
3  "number": "<card-number>",
4  "expiryMonth": 99,
5  "expiryYear": 99,
6  "cvv": "<card-cvv>"
7}


1{
2  "apiAlias": "card_payment_token_response",
3  "success": true,
4  "token": "<your-card-response-token>"
5}

After generating the card payment token, add it to the payment request.

post

/store-api/handle-payment


1{
2  "orderId": "<id-of-the-order>",
3  "finishUrl": "<successful-payment-url>",
4  "errorUrl": "<failed-payment-url>",
5  "checkoutComDetails": {
6    "token": "<card-payment-token>"
7  }
8}

For iDeal payments, you need to include the BIC value in the payment request.

post

/store-api/handle-payment


1{
2  "orderId": "<id-of-the-order>",
3  "finishUrl": "<successful-payment-url>",
4  "errorUrl": "<failed-payment-url>",
5  "checkoutComDetails": {
6    "source": {
7      "bic": "<your-bic-ideal>"
8    }
9  }
10}

Klarna payments also require a payment token.

post

/store-api/handle-payment


1{
2  "orderId": "<id-of-the-order>",
3  "finishUrl": "<successful-payment-url>",
4  "errorUrl": "<failed-payment-url>",
5  "checkoutComDetails": {
6    "token": "<klarna-token>"
7  }
8}

For SEPA payments, you need to include the firstName, lastName, and iban fields in the payment request.

post

/store-api/handle-payment


1{
2  "orderId": "<id-of-the-order>",
3  "finishUrl": "<successful-payment-url>",
4  "errorUrl": "<failed-payment-url>",
5  "checkoutComDetails": {
6    "source": {
7      "firstName": "<your-sepa-first-name>",
8      "lastName": "<your-sepa-last-name>",
9      "iban": "<your-sepa-iban>"
10    }
11  }
12}

To initiate an Apple Pay payment, you must first create an ApplePaySession. See the Apple documentation for more information.

When initiating an ApplePaySession, you'll need to provide ApplePaySession.onvalidatemerchant a way to validate the merchant and return the MerchantSession object. To do this, use the following endpoint:

post

/store-api/checkout-com/validate-merchant


1{
2  "validationURL": "<apple-pay-response-validation-url>"
3}

On ApplePaySession.onpaymentauthorized, you will get the data, header, signature, and version parameters from the token provided by Apple Pay. Use that token to initiate the payment.

post

/store-api/handle-payment


1{
2  "orderId": "<id-of-the-order>",
3  "finishUrl": "<successful-payment-url>",
4  "errorUrl": "<failed-payment-url>",
5  "checkoutComDetails": {
6    "token": {
7      "data": "<apple-pay-data-response>",
8      "header": "<apple-pay-header-response>",
9      "signature": "<apple-pay-signature-response>",
10      "version": "<apple-pay-version-response>"
11    }
12  }
13}

To initiate a Google Pay payment, you'll need to call the loadPaymentData method. See the Google documentation for more information.

After calling loadPaymentData, you'll receive a Google Pay payment token. Use that token to initiate the payment.


1{
2  "orderId": "<order-id",
3  "finishUrl": "<successful-payment-url>",
4  "errorUrl": "<failed-payment-url>",
5  "checkoutComDetails": {
6    "token": {
7      "protocolVersion": "<google-pay-data-response>",
8      "signedMessage": "<google-pay-header-response>",
9      "signature": "<google-pay-signature-response>"
10    }
11  }
12}

We support the direct pay feature for payments made with Apple Pay and Google Pay. Follow these steps to implement direct pay:

Add a product and its quantity to a direct cart. The direct cart is separate from the current cart. This allows you to initiate a payment without affecting the current cart, which may already contain some items.

post

/store-api/checkout-com/direct/add-product-to-cart


1{
2  "productId": "<product-id>",
3  "productQuantity": 99
4}


1{
2  "cartToken": "<your-cart-token>",
3  "success": true
4}

Use the cart token received in the response to get all available shipping methods. Depending on the payment method used, set paymentMethodType to googlepay or applepay.

post

/store-api/checkout-com/direct/get-shipping-methods


1{
2  "cartToken": "<your-cart-token>",
3  "countryCode": "US",
4  "paymentMethodType": "googlepay"
5}


1{
2  "shippingPayload": {
3    "displayItems": [
4      {
5        "label": "Subtotal",
6        "price": "1.00",
7        "type": "SUBTOTAL"
8      }
9    ],
10    "shippingOptions": [
11      {
12        "description": "<your-shipping-method-description>",
13        "id": "<your-shipping-method-id>",
14        "label": "<your-shipping-method-label>"
15      }
16    ]
17  },
18  "success": true
19}

You can render the shippingOptions from the response as options to let your customers choose their preferred shipping method.

Calculate the direct cart for the specified shipping method.

post

/store-api/checkout-com/direct/update-shipping-payload


1{
2  "cartToken": "<your-cart-token>",
3  "paymentMethodType": "googlepay",
4  "shippingMethodId": "<your-new-shipping-method-id>"
5}


1{
2  "shippingPayload": {
3    "displayItems": [
4      {
5        "label": "Subtotal",
6        "price": "1.00",
7        "type": "SUBTOTAL"
8      }
9    ]
10  },
11  "success": true
12}

Process the payment for the specified payment method.

post

/store-api/checkout-com/direct/process-payment


1{
2  "cartToken": "<your-cart-token>",
3  "checkoutComDetails": {
4    "token": {
5      "protocolVersion": "<google-pay-data-response>",
6      "signedMessage": "<google-pay-header-response>",
7      "signature": "<google-pay-signature-response>"
8    }
9  },
10  "paymentMethodType": "googlepay",
11  "shippingContact": {
12    "additionalAddressLine1": "",
13    "city": "",
14    "countryCode": "",
15    "countryStateCode": "",
16    "email": "",
17    "firstName": "",
18    "lastName": "",
19    "phoneNumber": "",
20    "street": "",
21    "zipCode": ""
22  }
23}


1{
2  "success": true,
3  "redirectUrl": "<your-redirect-url>"
4}

If a payment is canceled, you can remove a direct cart using the following endpoint:

post

/store-api/checkout-com/direct/remove-backup


1{
2  "cartToken": "<your-cart-token>"
3}


1const session = new ApplePaySession(APPLE_PAY.APPLE_PAY_VERSION, {
2  /// Options
3});
4session.onshippingcontactselected; // This is where you call /store-api/checkout-com/direct/get-shipping-methods
5session.onshippingmethodselected; // This is where you call /store-api/checkout-com/direct/update-shipping-payload
6session.onvalidatemerchant; // This is where you call /store-api/checkout-com/validate-merchant
7session.onpaymentauthorized; // This is where you call /store-api/checkout-com/direct/process-payment
8session.oncancel; // This is where you call /store-api/checkout-com/direct/remove-backup


1new google.payments.api.PaymentsClient({
2  environment,
3  paymentDataCallbacks: {
4    onPaymentAuthorized: onPaymentAuthorized,
5    onPaymentDataChanged: onPaymentDataChanged,
6  },
7});
8
9const onPaymentDataChanged = (intermediatePaymentData) => {
10  const { shippingAddress, shippingOptionData, callbackTrigger } = intermediatePaymentData;
11
12  switch (callbackTrigger) {
13    case 'INITIALIZE':
14    // This is where you add a product to a direct cart
15    // After that you should continue by calling this API: /store-api/checkout-com/direct/get-shipping-methods
16    case 'SHIPPING_ADDRESS':
17    // This is where you call /store-api/checkout-com/direct/get-shipping-methods
18    case 'PAYMENT_AUTHORIZATION':
19    // This is where you call /store-api/checkout-com/direct/update-shipping-payload
20    default:
21      return Promise.resolve({});
22  }
23};
24
25const onPaymentAuthorized = (paymentData) => {
26  const { email, paymentMethodData, shippingAddress } = paymentData;
27  // This is where you call /store-api/checkout-com/direct/process-payment
28};

Endpoints

Validate a merchant for Apple Pay

Request example

Response example

Get plugin configuration

Response example

Create a card payment token

Request example

Response example

Add product to cart

Request example

Response example

Remove back-up cart

Request example

Get shipping methods

Request example

Response example

Update shipping payload

Request example

Response example

Process payment

Request example

Response example

Create Klarna session

Request example

Response example

Delete source

Request example

Create an order on a headless storefront

Request example

Response example

Response example

Request example

Response example

Response example

Request example

Response example

Request example

Initiate a payment for Checkout.com payment methods

Card payments

Request example

Response example

Request example

iDeal

Request example

Klarna

Request example

SEPA

Request example

Apple Pay

Request example

Request example

Google Pay

Request example

Implement direct pay

Request example

Response example

Request example

Response example

Request example

Response example

Request example

Response example

Request example

Implement direct pay with Apple Pay

Implement direct pay with Google Pay