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.

Requirements

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 by rendering the input fields using our Drop-in or Components.

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.

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.

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