Headless integration

Integrate an Adobe Commerce headless storefront with the Adyen platform.

Implementation examples
Try it out on GitHub!

On this page we provide Adyen-specific information for building a Progressive Web Application (PWA) storefront. The PWA storefront works with a headless Adobe Commerce back-end that has the Adyen plugin installed and configured.

Two web APIs can be used to utilize the Adyen functionality with Adobe Commerce in a headless implementation:

REST - This is the most widely used web API. All of the functionalities provided by the Adyen plugin can be accessed using this method.
GraphQL - This is an alternative way to interact with web APIs. The Adyen plugin utilizes the /graphql endpoint exposed by the Adobe Commerce back-end and adds the functionality that is related to the plugin. All functionalities provided by the Adyen plugin can be accessed using this method. For more information, checkout the Adobe Commerce GraphQL documentation.
GraphQL is only available with plugin v8.2.0 or later.

Ecommerce checkout flow

With a headless Adobe Commerce back end, you build your own payment form for the Adobe Commerce PWA storefront. In the checkout flow, data passes from the PWA storefront through the Adobe Commerce back end to the Adyen API. Then, data passes back from the Adyen API through the Adobe Commerce back end to the PWA storefront. In the checkout flow, you need to do the following steps:

Get the payment methods that are available on the Adyen platform, and for each of them determine the data that you need to collect.
Collect shopper details by presenting the payment methods on your payment form. Then, when the shopper selects a payment method, present the fields to fill out or the options to choose from, and collect these details.
Place the order.
Check the payment status to see if you need to perform any extra steps before redirecting the user to the success page or showing an error message.
Handle additional actions like redirecting the customer to the issue page for additional authentication, or presenting a QR code to complete the payment. If the payment fails, the following attempts will need to handle the additional actions as well

Requirements

Before you start integrating a Adobe Commerce PWA storefront with the Adyen platform:

Make sure that you have completed the steps to configure the Adobe Commerce back end:
- Set up the Adyen Customer Area.
- Set up the plugin in Adobe Commerce.
- Set up the payment methods in Adobe Commerce.
- Configured headless integration settings in Adobe Commerce.
- Get familiar with the front end components implementation. We suggest using the components to gather the payment related information in a secure way.
Setting up in-person payments is not required for a PWA storefront.
The plugin uses Adobe Commerce’s recommended authentication methods to authenticate requests coming from the front-end application. The endpoints use self resources for logged-in shoppers and anonymous resources for guest shoppers.
Therefore, an integration token is no longer required. Customer token needs to be used as Bearer Token for logged-in shoppers. For guest shoppers, no token is required because a masked card_id is used to authenticate requests.

For more information on resource access, refer to Adobe Commerce documentation.

Step 1: Get available payment methods

In this step, the Adobe Commerce back end retrieves the available payment methods from the /paymentMethods API endpoint and adds some extra information that you will need for rendering the components on the front end.

To get the available payment methods and extra information:

Make an API request to get the payment methods and data that you need to collect.
Parse the API response to get a JSON object that contains the Adyen /paymentMethods response and required extra information.

1. Make an API request

If you are using REST, the endpoint differs per use case. If you are using GraphQL, the endpoint is /graphql.

2. Parse the API response

The Adobe Commerce back end receives a response from Adyen containing all available payment methods for the current session filtered by currency, amount, country/region, etc. For each payment method, the /paymentMethods response includes:

name: Name of the payment method, which you can show to your shopper in your payments form.
type: Unique payment method code. Pass this back to indicate the shopper's selected payment method when you place an order.

The plugin also collects some extra information other than the /paymentMethods response. This data is included in the response as the following fields:

icon {url, width, height}: Payment method icon details.
configuration: Includes any extra payment method specific configuration that the checkout component should get on the front end which is not accessible from the /paymentMethods details response.
isOpenInvoice (boolean): Indicates if the payment method is an open invoice payment method. Note that this field is deprecated and will be removed later.

The following is an example API response for the REST flow, a GraphQL query retrieves data similarly to a REST GET request. To learn more about the similarities and differences between REST and GraphQL, refer to Adobe Commerce GraphQL documentation.

The response contains payment methods as a JSON encoded string. Parse this string to get a JSON object. For example, using JSON.parse();.

After parsing the response, you get two root objects:

paymentMethodsResponse: Includes the full and unmodified response object from the Adyen /paymentMethods API endpoint.
paymentMethodsExtraDetails: Holds the extra information that the plugin gathered for each payment method that is available in the paymentMethodsResponse.

{
    "paymentMethodsExtraDetails": {
        "applepay": {
            "icon": {
                "url": "full url for icon",
                "width": 1,
                "height": 1
            },
            "configuration": {
                "amount": {
                    "value": 1,
                    "currency": "currency ISO code like EUR"
                }
            }
        },
        "klarna": {...},
        "ideal": {...},
        "klarna_paynow": {...}
    },
    "paymentMethodsResponse": {
        "paymentMethods": [
            {
                "name": "iDEAL",
                "type": "ideal"
            },
            {
                "brands": [
                    "mc",
                    "visa",
                    "maestro"
                ],
                "name": "Cards",
                "type": "scheme"
            },
            {
                "configuration": {
                    "intent": "capture",
                    "merchantId": "Merchant id"
                },
                "name": "PayPal",
                "type": "paypal"
            },
            {
                "name": "Pay later with Klarna.",
                "type": "klarna"
            },
            {
                "name": "SEPA Direct Debit",
                "type": "sepadirectdebit"
            },
            {
                "configuration": {
                    "merchantId": "Merchant id",
                    "merchantName": "Merchant name"
                },
                "name": "Apple Pay",
                "type": "applepay"
            }
        ]
    }
}

Step 2: Collect shopper details

Next, present the available payment methods on your front end, and collect the shopper details that are required for the payment method selected by the shopper.

Use the name values from the /paymentMethods response to show all available payment methods to your shopper.

If you need payment methods and issuer logos for your payment form, use the paymentMethodsExtraDetails.icon from the /payment-information response as described in the previous step.
After the shopper selects a payment method, render the input fields to get the required payment details. You can do this by rendering the input fields with Adyen Components.

Render the input fields with Adyen Components

You can use our Web Components to render individual payment methods anywhere on your website with our customizable UI components.

We recommend to pass the full paymentMethodsResponse object to the Web Component configuration when implementing multiple payment methods in your PWA storefront. After creating the new AdyenCheckout object, you can loop through the methods and generate the components instead of creating components manually for each payment method. This also ensures that your integration can handle new payment methods when enabled in your Customer Area.

Step 3: Place the order

After the customer has filled in their data, you can place the order. In this step, the storefront makes a request to the Adobe Commerce back end which then makes a payment request to the /payments endpoint.

To start the payment process, place the order from your front end in the way the default Adobe Commerce checkout flow requires:

Create a data object to send in the Adobe Commerce API request.
Place the order with the created object.

1. Create a data object

2. Place an order

For more information, refer to the Adobe Commerce API documentation.

The response contains the orderId field with an integer value that you need for the next step.

Step 4: Check payment status

To see if there are any additional steps required after placing the order, call the payment status endpoint:

Parse the JSON response and evaluate it. There are two paths that you can follow based on the isFinal response field.
- The isFinal field is true:
  - If the resultCode field is Authorised or Received, the payment was successful and you can redirect the customer to the success page.
  - If the resultCode field is PresentToShopper, present the voucher or QR code to the shopper so they can complete the payment.
  - If the resultCode field is Refused, Error or unhandled, you receive a response containing an HTTP 400 result code and a default Adobe Commerce localized error response.
  - If the action field is present and is not empty, then handle the additional action using the Web Component.
- The isFinal field is false:
  - The action field is present and is not empty, then handle the additional action using the Web Component.

Step 5: Handle additional actions

This step is only needed if the action field is present and not empty in the response of the previous step.

Some payment methods require additional action from the shopper. For example, to scan a QR code, to authenticate a payment with 3D Secure, or to log in to their bank's website to complete the payment. To handle these additional front-end actions, follow the Web Components documentation or find specific documentation for each payment method in this list.

All payment methods use the createFromAction method, except for PayPal. The PayPal Component uses the handleAction method to process additional action from the PayPal pop-up window.

Gift card payments

After you have followed the steps to get the available payment methods and present them in your front end, you can offer your shoppers to pay with gift cards.

For GraphQL integrations, the additional setup steps below are required to process gift card payments.

Step 1: Mount the component

After a shopper selects the option to pay with a gift card, mount the Adyen Web Component for gift cards and check the balance:

Follow the steps to configure the Component.
When creating an instance of the Component, in the onBalanceCheck event, call the adyenPaymentMethodsBalance GraphQL mutation that returns the available balance of a gift card.
Use the JSON.stringify() function on the data object you get from the event. This is the payload for the adyenPaymentMethodsBalance mutation.

This mutation returns the balance of a gift card, and additional details like the currency and value. For example:

Step 2: Save gift card state data

To redeem gift cards when making a payment, save the state data associated with the Adyen payment method.

Use the adyenSaveStateData GraphQL mutation to save the state data after you have checked the balance of a gift card. For multiple gift cards payments, save the state data for each gift card after checking their balances.

stateData: The JSON string that contains state data to save.
cart_id: Use the cart ID of your shopper's cart.

This mutation makes a request to save the state data:

You get a stateDataId object that you can use to remove the saved state data later.

You may no longer need the saved state data if your shopper deletes the gift card number in the checkout form, for example if they decide to pay with another gift card.

To remove the saved state data, use the adyenRemoveStateData GraphQL mutation:

stateDataId: The ID that you received in the response when you saved state data.
cart_id: Use the cart ID of your shopper's cart.

You get a response containing the stateDataId for removed state data.

Step 3: Redeem gift cards

Use the adyenRedeemedGiftCards GraphQL mutation that returns an array of the gift cards, including identifiers and remaining balances to fetch redeemed gift cards. This allows you to present the gift cards and the deducted amounts in your front end.
Compare the amount of the shopper's cart to the balance available on the gift card. The way you place the order depends on the outcome of the comparison:
- If the balance of the gift card is equal or higher than the order amount, place the order with adyen_giftcard for the code field.
- If the balance of the gift card is lower than the order amount, place the order with the payment method that is used to cover the remaining amount. The plugin handles the gift card redemption automatically using the state data you have saved.

After you have followed the above steps, check the payment status as you would for other payment methods.

Tokenization

With your headless integration, you can securely store the payment details of shoppers and offer returning customers a faster checkout experience.

Tokenization in a headless integration works similarly to tokenization in the standard plugin setup, using the Adobe Commerce Vault.

Tokenize shopper payment details

Follow the steps to set up the vault in Adobe Commerce.

After you have enabled tokenization in your Adobe Commerce admin panel, a Save for my next payment checkbox will appear when making a payment. If the checkbox is selected, the shopper payment details will be stored in the vault_payment_token database table.

Remove a shopper token

For each token, the vault_payment_token database table includes:

shopperReference: Stored in Adobe Commerce as the customer_id.
storedPaymentMethodId: Stored in Adobe Commerce as the gateway_token.

To remove an existing shopper token, make a POST /token/deactivate request from your server. In your request, include the customerId parameter. This must match the customer_id value for the token in the database table.

Troubleshooting

When you get unexpected results, you can:

Check the endpoints on Adyen's GitHub as a starting point to see if there are any changes. In addition, check your /swagger where all the endpoints are listed.
Use our API Explorer to try out calls to the Adyen API endpoints and for example see what kind of errors you might get. Make sure that you select the API version that the Adobe Commerce plugin uses. Check the library and API versions you are using.

Checking library and API versions

The Adobe Commerce plugin uses a specific version of the Adyen PHP library, which uses specific versions of the Adyen APIs. You can try out calls to the Adyen APIs in our API Explorer. The API Explorer is versioned, and you need to select the API version that your Adobe Commerce plugin version is using before trying calls.

To look up which PHP library and Adyen API versions you are using, refer to the release notes.

Alternatively:

Go to the Adyen Adobe Commerce (formerly Magento 2) plugin on GitHub.
In the Branch dropdown, on the Tags tab, select the version of your Adobe Commerce plugin.
At adyen/php-api-library, find the version of the Adyen PHP library that the plugin uses. For example, "adyen/php-api-library": "~2.1".
Go to the Adyen PHP library.
In the Branch dropdown, on the Tags tab, select the library version you have just found.
Refer to the API constants to find the versions of the Adyen APIs that the PHP library uses, for example const API_CHECKOUT_VERSION = "v41".