Plugin icon

Headless integration

Use the Adyen plugin with a Shopware 6 Headless integration.

This page describes how to build a front end for your headless Shopware 6 integration using either Adyen's pre-built UI solutions or your own UI. Your front end connects to your existing back end that uses Shopware's Store API endpoints.

Before you begin

Before you start building a Shopware 6 Headless integration, set up the Shopware 6 plugin.

Step 1: Get available payment methods

Get the available payment methods, so you can show them in the checkout form.

Make a POST store-api/payment-method request to get the available payment methods. Specify:

Parameter name Description
page Search result page.
limit Number of items per result page.
filter List of filters to restrict the search result.
sort Sorting in the search result.
post_filter Filters that applied without affecting aggregations.
associations Used to fetch associations that are not fetched by default.
aggregations Used to perform aggregations on the search result.
grouping Perform groupings over certain fields.
onlyAvailable List only available.

The response contains an adyenData object for each available payment method.

In the next step, use information from the adyenData objects to show payment methods on your checkout page.

Step 2: Show available payment methods

Show the available payment methods on your front end and collect the shopper's payment details using either:

Option 1: Render the input fields using our Drop-in or Components

Use one of our Pre-built UI options.

  1. From your server, make a GET /store-api/adyen/payment-methods request. The response you get is the same as an Adyen Checkout API /paymentMethods response.
  1. When you configure Drop-in use the full response as the paymentMethodsResponse in the configuration object:

    const configuration = {
      // ... Other configuration parameters
      paymentMethodsResponse: paymentMethodsResponse, // The full response from the server.
  2. Configure and create Drop-in:

    // Configure Drop-in.
    const checkout = await AdyenCheckout(configuration);
    // Create Drop-in.
    const dropin = checkout.create('dropin').mount('#dropin-container')

Saving the shopper's payment details

The shopper's payment details are collected by the Drop-in and Component in a STATE_DATA object that you send in Step 4 when you make a payment.

Option 2: Render your own UI

From the store-api/payment-methods response in Step 1, the details array from the extensions.adyenData.paymentMethodConfig shows the payment details that you need to collect from the shopper:

  • key: The field you need from the shopper.
  • type: The data type of the field:

    type value Description
    emailAddress Email address.
    radio Radio buttons showing the options specified in the items array.
    select A list showing the options specified in the items array. The options are usually issuer or bank names. Show each name to the shopper.
    tel Telephone number.
    text Generic string.

If a payment method doesn't have a details array in extension.adyenData.paymentMethodConfig, you don't need to collect shopper's payment details in your form. This usually means that the shopper is redirected to another site to complete the payment.

For card payment methods (extensions.adyenData.type: scheme):
- If you are fully PCI compliant, you can collect and submit raw card data.
- If you aren't PCI compliant, you need to use our solution to encrypt card data.

Saving the shopper's payment details

Save the shopper's payment details from the input fields in a stateData object that you send in Step 4 when you make a payment.

Step 3: Create order

When the shopper submits the order, create the order by making a store-api/checkout/order endpoint.

Parameter name Description
customerComment Adds a comment from the customer to the order.
affiliateCode The affiliate code can be used to track which referrer the customer came through.
campaignCode The campaign code is used to track which action the customer came from.

Step 4: Make payment

Make a POST store-api/handle-payment request, including the shopper's payment details in the stateData parameter. For example:

this.client = new StoreApiClient();
let params = {
            'orderId': 'XXX',
            'finishUrl': '',
            'errorUrl': '',
// Add payment state data
params['stateData'] = {
    paymentMethod: {
     type: "scheme",
     encryptedCardNumber: "adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..",
     encryptedExpiryMonth: "adyenjs_0_1_18$p2OZxW2XmwAA8C1Avxm3G9UB6e4..",
     encryptedExpiryYear: "adyenjs_0_1_18$CkCOLYZsdqpxGjrALWHj3QoGHqe+..",
     encryptedSecurityCode: "adyenjs_0_1_18$XUyMJyHebrra/TpSda9fha978+.."
     holderName: "S. Hopper"

Step 5: Handle additional actions

You can get the status of the payment by making a POST /store-api/adyen/payment-status request with the orderId parameter as shown below:
    JSON.stringify({orderId: 'XXX'})

The response will contain the following parameters:

Parameter Description
isFinal This is a boolean value that indicates whether or not the payment requires additional action for the shopper.
resultCode Returns one of the Adyen payment result codes.
action This optional response parameter is only returned for payments that require additional action from the user.

Some payment methods require additional action from the shopper, you can determine if this is the case from the response for isFinal:

  • When isFinal is true, the payment has been completed and no further action is required.
  • When isFinal is false, the action parameter will contain the payload needed to mount the UI elements for additional actions.

Note: Consult the Web Component or Drop-in documentation for how to handle additional front end actions.

After your shopper completes the additional action:

  1. Access the additional input from the shopper by implementing the onAdditionalDetails event listener of your Drop-in or Web Component.
  2. Submit the additional details by making a POST /store-api/adyen/payment-details request with the orderId and stateData parameters.
handleOnAdditionalDetails (state) {
        JSON.stringify({orderId: 'XXX', stateData:})

Step 6: Present payment results

After the shopper completes the payment and no further actions are required on the front end or client app, use the resultCode to inform the shopper of the payment status.

resultCode Description Action to take
Authorised The payment was successful. Inform the shopper that the payment was successful.
Error Inform the shopper that there was an error processing their payment. You'll receive a refusalReason in the same response, indicating the cause of the error.
Pending The shopper has completed the payment but the final result is not yet known. Inform the shopper that you've received their order, and are waiting for the payment to be completed.
You will receive the final result of the payment in an AUTHORISATION webhook.
PresentToShopper Present the voucher or the QR code to the shopper. For a voucher payment method, inform the shopper that you are waiting for their payment. You will receive the final result of the payment in an AUTHORISATION webhook.

For a qrCode payment method, wait for the AUTHORISATION webhook before presenting the payment result to the shopper.
Refused The payment was refused. Inform the shopper that the payment was refused. Ask the shopper to try the payment again using a different payment method or card.
Received For some payment methods, it can take some time before the final status of the payment is known. Inform the shopper that you've received their order, and are waiting for the payment to clear.
You will receive the final result of the payment in an AUTHORISATION webhook.

For other possible resultCode values and recommended messages that you can present to your shopper, see Result codes.