Skip to content

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.

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.

Validate a merchant for Apple Pay

Validates a merchant’s URL for Apple Pay.

post

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

Copied!

Request example

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

Response example

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

Get plugin configuration

Returns the Checkout.com Payments plugin configuration.

get

/store-api/checkout-com/config

Copied!

Response example

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

Create a card payment token

Creates a card payment token.

post

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

Copied!

Request example

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

Response example

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

Add product to cart

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

Copied!

Request example

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

Response example

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

Remove back-up cart

Removes the specified back-up cart.

post

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

Copied!

Request example

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

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

Get shipping methods

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

Copied!

Request example

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

Response example

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

Update shipping payload

Calculates the direct cart for the specified shipping method.

post

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

Copied!

Request example

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

Response example

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

Process payment

Processes a payment made using a direct pay button.

post

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

Copied!

Request example

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

Response example

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

Create Klarna session

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

post

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

Copied!

Request example

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

Response example

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

Delete source

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

delete

/checkout-com/source

Copied!

Request example

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

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


Create an order on a headless storefront

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

Copied!

Request example

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

Response example

1
2
3
4
5
{
"apiAlias": "array_struct",
"contextToken": "gyCDpNMo7E2Q3CzxMlKQdHDiLJIx8Grj",
"redirectUrl": null
}
  1. Get a list of available payment methods.
get

/store-api/payment-method

Copied!

Response example

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

/store-api/context

Copied!

Request example

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

Response example

1
2
3
4
5
{
"apiAlias": "array_struct",
"contextToken": "eakh7cAQgpq5ED5VCkeGPGNeEcBsR5dF",
"redirectUrl": null
}
  1. Get the current cart or create a new one.
get

store-api/checkout/cart

Copied!

Response example

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

/store-api/product

Copied!

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

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

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

Copied!

Request example

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

Response example

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

/store-api/checkout/order

Copied!
  1. 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

Copied!

Request example

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

Initiate a payment for Checkout.com payment methods

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

Card payments

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

Copied!

Request example

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

Response example

1
2
3
4
5
{
"apiAlias": "card_payment_token_response",
"success": true,
"token": "<your-card-response-token>"
}
  1. After generating the card payment token, add it to the payment request.
post

/store-api/handle-payment

Copied!

Request example

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

iDeal

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

post

/store-api/handle-payment

Copied!

Request example

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

Klarna

Klarna payments also require a payment token.

post

/store-api/handle-payment

Copied!

Request example

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

SEPA

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

post

/store-api/handle-payment

Copied!

Request example

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

Apple Pay

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

Copied!

Request example

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

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

Copied!

Request example

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

Google Pay

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.

Request example

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

Implement direct pay

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

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

Copied!

Request example

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

Response example

1
2
3
4
{
"cartToken": "<your-cart-token>",
"success": true
}
  1. Use the cart token received in the reponse 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

Copied!

Request example

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

Response example

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

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

  1. Calculate the direct cart for the specified shipping method.
post

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

Copied!

Request example

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

Response example

1
2
3
4
5
6
7
8
9
10
11
12
{
"shippingPayload": {
"displayItems": [
{
"label": "Subtotal",
"price": "1.00",
"type": "SUBTOTAL"
}
]
},
"success": true
}
  1. Process the payment for the specified payment method.
post

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

Copied!

Request example

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

Response example

1
2
3
4
{
"success": true,
"redirectUrl": "<your-redirect-url>"
}
  1. If a payment is cancelled, you can remove a direct cart using the following endpoint:
post

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

Copied!

Request example

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

Implement direct pay with Apple Pay

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

Implement direct pay with Google Pay

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