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.

[
    {
        "name": "SEPA direct debit",
        "description": "Direct debit payments",
        "active": true,
        ...
        "extensions": {
            ...
            "adyenData": {
                "type": "sepadirectdebit",
                "paymentMethodConfig": {
                    "details": [
                        {
                            "key": "sepa.ownerName",
                            "type": "text"
                        },
                        {
                            "key": "sepa.ibanNumber",
                            "type": "text"
                        }
                    ],
                    "name": "SEPA Direct Debit",
                    "type": "sepadirectdebit"
                },
                "apiAlias": "adyen_shopware_struct_adyen_payment_method_data_struct"
            }
        },
        "apiAlias": "payment_method"
    },
    {
        "name": "PayPal",
        "description": "eWallet",
        "active": true,
        ...
        "extensions": {
            ...
            "adyenData": {
                "type": "paypal",
                "paymentMethodConfig": {
                    "configuration": {
                        "merchantId": "MERCHANT_ACCOUNT",
                        "intent": "capture"
                    },
                    "name": "PayPal",
                    "type": "paypal"
                },
                "apiAlias": "adyen_shopware_struct_adyen_payment_method_data_struct"
            }
        },
        "apiAlias": "payment_method"
    }
]

https://docs.adyen.com/plugins/shopware-6/headless-integration#example-response-for-post-store-api-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: (Recommended) Render the input fields using our Drop-in or Components.
Option 2: Render your own UI.

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

Use one of our Pre-built UI options.

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.

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.

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, use Adyen's custom card integration to collect encrypted 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': 'https://example.com/checkout/finish?orderId=XXX',
            'errorUrl': 'https://example.com/checkout/finish?orderId=XXX&paymentFailed=1',
        };
// 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"
   }
}
this.client.post(
    'https://example.com/store-api/handle-payment',
    JSON.stringify(params)
);

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:

this.client.post(
    'https://example.com/store-api/adyen/payment-status',
    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:

Access the additional input from the shopper by implementing the onAdditionalDetails event listener of your Drop-in or Web Component.
Submit the additional details by making a POST /store-api/adyen/payment-details request with the orderId and stateData parameters.

handleOnAdditionalDetails (state) {
    this.client.post(
        'https://example.com/store-api/adyen/payment-details',
        JSON.stringify({orderId: 'XXX', stateData: state.data})
    );
}

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.

Are you looking for test card numbers?

Would you like to contact support?

Headless integration

Before you begin

Step 1: Get available payment methods

Step 2: Show available payment methods

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

Saving the shopper's payment details

Option 2: Render your own UI

Saving the shopper's payment details

Step 3: Create order

Step 4: Make payment

Step 5: Handle additional actions

Step 6: Present payment results