No momento, esta página não está disponível em português
Plugin icon

Headless integration

Integrate an Adobe Commerce headless storefront with the Adyen platform.

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:

  • 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 of the essential 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 version 8.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:

  1. Get the payment methods that are available on the Adyen platform, and for each of them determine the data that you need to collect.
  2. 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.
  3. Place the order.
  4. 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.
  5. 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

Before you begin

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

  1. Make sure you have completed the steps to configure the Adobe Commerce back end:

    Setting up point of sale is not required for a PWA storefront.

  2. From version 9.0.1 onwards, 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 cart ID is used to authenticating their 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:

  1. Make an API request to get the payment methods and data that you need to collect.
  2. 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.

Available payment methods and required extra information are added to the extension_attributes of payment-information and shipping-information endpoints of Adobe Commerce as adyen_payment_methods_response. The required extra information is relevant when collecting shopper details in Step 2.

The payment_methods object in the response of payment-information or shipping-information endpoints is filtered and sorted according to the response of /paymentMethods endpoint.

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, 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.
  • details: Array that contains the required fields for the payment method.

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 REST endpoint's 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:

  1. paymentMethodsResponse: Includes the full and unmodified response object from the Adyen /paymentMethods API endpoint.
  2. 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"
                }
            }
        },
        "ideal": {
       ...
        },
        "klarna": {
       ...
        },
        "klarna_paynow": {
       ...
        },
    ...
    },
    "paymentMethodsResponse": {
        "paymentMethods": [
            {
                "details": [
                    {
                        "items": [
                            {
                                "id": "1121",
                                "name": "Test Issuer"
                            },
                            {
                                "id": "1154",
                                "name": "Test Issuer 5"
                            },
                            {
                                "id": "1153",
                                "name": "Test Issuer 4"
                            },
                            "..."
                        ],
                        "key": "issuer",
                        "type": "select"
                    }
                ],
                "name": "iDEAL",
                "type": "ideal"
            },
            {
                "brands": [
                    "mc",
                    "visa",
                    "maestro"
                ],
                "details": [
                    {
                        "key": "number",
                        "type": "text"
                    },
                    {
                        "key": "expiryMonth",
                        "type": "text"
                    },
                    {
                        "key": "expiryYear",
                        "type": "text"
                    },
                    {
                        "key": "cvc",
                        "type": "text"
                    },
                    {
                        "key": "holderName",
                        "optional": true,
                        "type": "text"
                    }
                ],
                "name": "Credit Card",
                "type": "scheme"
            },
            {
                "configuration": {
                    "intent": "capture",
                    "merchantId": "Merchant id"
                },
                "name": "PayPal",
                "type": "paypal"
            },
            {
                "name": "Pay later with Klarna.",
                "type": "klarna"
            },
            {
                "details": [
                    {
                        "key": "sepa.ownerName",
                        "type": "text"
                    },
                    {
                        "key": "sepa.ibanNumber",
                        "type": "text"
                    }
                ],
                "name": "SEPA Direct Debit",
                "type": "sepadirectdebit"
            },
            {
                "configuration": {
                    "merchantId": "Merchant id",
                    "merchantName": "Merchant name"
                },
                "details": [
                    {
                        "key": "applepay.token",
                        "type": "applePayToken"
                    }
                ],
                "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. To do so:

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

  2. After the shopper selects a payment method, render the input fields to get the required payment details. This can be done in two ways:

Rendering the input fields using our Drop-in or Components

We provide front end solutions that render and validate the necessary input fields:

  • Web Components : Render individual payment methods anywhere on your website with our customizable UI components.

    When you are implementing multiple payment methods on your PWA storefront we suggest that you pass the full paymentMethodsResponse object to the Web Component configuration. After creating the new AdyenCheckout object you can loop through the methods and generate the components instead of doing it manually for each payment method. With this approach, you make sure that your integration can handle new payment methods that you enable in your Customer Area.

  • Web Drop-in : Render a list of available payment methods anywhere on your website with our pre-built UI.

Rendering the input fields manually

Use the details array from the paymentMethodsResponse for the selected payment method to determine what you need to collect from the shopper.

  • key: Shopper detail you need to collect using your payments form.
  • type: Input type for collecting the payment detail from the shopper:
Type Description
emailAddress Email address.
radio Radio buttons showing the options specified within the items array.
select A list showing the options specified within the items array. Usually the options represent issuer (bank) names. Present each name in this array to the shopper.
tel Telephone number.
text Generic string. For "type": "scheme", if you are fully PCI compliant you can alternatively collect and submit raw card data. See Collecting raw card data for more information. Otherwise, you need to generate encrypted card data using our custom card integration.

If a payment method does not have a details array, you do not need to collect any shopper details in your form. This usually means that the shopper must be redirected to another site to complete the payment.

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:

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

1. Create a data object

First, create a data object that you can later send in the Adobe Commerce /payment-information Adobe Commerce 2 REST API request.

To get the necessary details for this object, you can do either of the two:

  • Use state.data from the Web component.

  • Replicate the request object yourself based on the documentation for the /payments endpoint. To replicate the object, follow this structure:

    Parameter Required Description
    method -white_check_mark- Payment method name in Adobe Commerce. For example, adyen_cc, adyen_ideal, or adyen_googlepay.
    cc_type If method is adyen_cc Card type.
    Get the card type available in Adobe Commerce based on the state.data.paymentMethod.brand or state.brand. See example.
    If you implement the onBrand callback for the Web Component, then you can find it as state.brand. See example.
    brand_code If method is an alternative payment method The value of state.data.paymentMethod.type field.
    recurringProcessingModel -x- The recurring processing model for the request, overwrites the default value in the plugin configuration. Set to Subscription, CardOnFile, UnscheduledCardOnFile depending on the recurring payment type you are making the request for.
    stateData -white_check_mark- JSON.stringify() the state.data object that you get from the Web Component or Drop-in. See example.
    The state.data object can be set in a separate request to accommodate special checkout flows.

2. Place an order

Place the order with the /payment-information endpoint from the Adobe Commerce REST API. Use the object created in the previous step.

If you can't use the payment-information endpoint to set state.data, see setting the payment state.data in a separate request.

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

The response contains orderId in integer format that you need for the next step.

Plugin version 7.2.0 and newer support setting the payment's state.data by using the /V1/adyen/carts/mine/state-data or /V1/adyen/guest-carts/:cartId/state-data endpoint. This is useful for checkout flows where this information can't be sent using the /payment-information Adobe Commerce REST API endpoint.

The /stateData endpoint receives the following parameters:

Parameter Description
state_data state.data from the Web Component.
quote_id The ID of the Adobe Commerce quote related to state.data.

state.data saved with this endpoint is used in the payment request if no state.data was supplied in the /payment-information request.

Using this endpoint will persist payment data which can be useful for complex checkout flows, but could have implications for your integration's PCI scope. Reach out to our Support team for questions.

Step 4: Check payment status

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

  1. Make a POST request:

    • For logged-in shoppers, use the /V1/adyen/orders/carts/mine/payment-status endpoint.
    • For guest shoppers, use the /V1/adyen/orders/guest-carts/{cartId}/payment-status endpoint.

    In the request body, include orderId that you received in the response from the /payment-information endpoint in the previous step. See an example from our plugin's credit card method renderer.

  1. 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:

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.

Handle action from the /payment-status or /payment-details response

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.

Optional: Validate the state.data from the action component

In case the shopper is already redirected to the success page, you don't need to validate anything because the Component presents a QR code or additional information to the customer, and no additional steps are required from you. Adyen is going to send a notification to your system as soon as the customer finishes the payment.

The plugin handles webhooks on its own.

In case the shopper is still in the checkout process, you need to perform additional checks of the state.data that you get back from the Component. To do this, implement the onAdditionalDetails callback when creating the new AdyenCheckout component.

To validate the state.data:

  • Use the /V1/adyen/carts/mine/payments-details endpoint for logged-in shoppers.
  • Use the /V1/adyen/guest-carts/:cartId/payments-details endpoint for guest shoppers.

Create your request

Create your request with the following field:

  • payload: JSON.stringify() the object that you get from the action component in the state.data field.
  • orderId: The orderId you received in the response when you placed the order.

Example request:

{
"payload": "{\"details\":{\"threeDSResult\":\"eyJ0cmFuc1N..."}}",
"orderId": "175",
"cartId": "r8Mktr..."
}

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 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:

  1. Go to the Adyen Adobe Commerce (formerly Magento 2) plugin on GitHub.
  2. In the Branch dropdown, on the Tags tab, select the version of your Adobe Commerce plugin.
  3. 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".
  4. Go to the Adyen PHP library.
  5. In the Branch dropdown, on the Tags tab, select the library version you've just found.
  6. 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".

See also