Headless integration

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.

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

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

Returns the Checkout.com Payments plugin configuration.

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

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

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

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

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

Removes the specified back-up cart.

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

2. Get a list of available payment methods.

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

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

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

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

4. Get the current cart or create a new one.

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

5. Get a list of products.

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

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

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

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

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

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

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

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:

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

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

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

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

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

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

json
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:

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

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

json
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:

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.

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

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

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

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

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

3. Calculate the direct cart for the specified shipping method.

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

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

4. Process the payment for the specified payment method.

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

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

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

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

js
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

js
1new google.payments.api.PaymentsClient({
2    environment,
3    paymentDataCallbacks: {
4        onPaymentAuthorized: onPaymentAuthorized,
5        onPaymentDataChanged: onPaymentDataChanged,
6    },
7});
8
9const 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
29const 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}