Skip to content
Integrate / E-commerce platforms / Shopware 6 / Headless integration

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
}

On this page

Endpoints
Create an order on a headless storefront
Implement direct pay