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

Request example

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

Response example

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

Get plugin configuration

Returns the Checkout.com Payments plugin configuration.

get

/store-api/checkout-com/config

Response example

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

Create a card payment token

Creates a card payment token.

post

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

Request example

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

Response example

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

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

Request example

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

Response example

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

Remove back-up cart

Removes the specified back-up cart.

post

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

Request example

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

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

Request example

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

Response example

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
}

Update shipping payload

Calculates the direct cart for the specified shipping method.

post

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

Request example

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

Response example

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
}

Process payment

Processes a payment made using a direct pay button.

post

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

Request example

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

Response example

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

Create Klarna session

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

post

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

Request example

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

Response example

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
}

Delete source

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

delete

/checkout-com/source

Request example

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

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

Request example

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

Response example

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

/store-api/payment-method

Response example

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
}
  1. Find the ID of the payment method you want to use and pass it to the context.
patch

/store-api/context

Request example

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

Response example

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

store-api/checkout/cart

Response example

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

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

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

Request example

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
}

Response example

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
}
  1. After adding the required products, create an order from the cart.
post

/store-api/checkout/order

  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

Request example

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

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

Request example

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

Response example

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

/store-api/handle-payment

Request example

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
}

iDeal

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

post

/store-api/handle-payment

Request example

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

Klarna payments also require a payment token. See our Klarna documentation to learn how to generate the token.

post

/store-api/handle-payment

Request example

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
}

SEPA

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

post

/store-api/handle-payment

Request example

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

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

Request example

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

Request example

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
}

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
"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
}

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

Request example

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

Response example

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

Request example

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

Response example

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.

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

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

Request example

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

Response example

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

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

Request example

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
"first_name": "",
18
"last_name": "",
19
"phoneNumber": "",
20
"street": "",
21
"zipCode": ""
22
}
23
}

Response example

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

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

Request example

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

Implement direct pay with Apple Pay

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

Implement direct pay with Google Pay

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