--- title: "Headless integration" description: "Integrate an Adobe Commerce headless storefront with the Adyen platform." url: "https://docs.adyen.com/plugins/adobe-commerce/headless-integration" source_url: "https://docs.adyen.com/plugins/adobe-commerce/headless-integration.md" canonical: "https://docs.adyen.com/plugins/adobe-commerce/headless-integration" last_modified: "2024-01-05T11:36:00+01:00" language: "en" --- # Headless integration Integrate an Adobe Commerce headless storefront with the Adyen platform. [View source](/plugins/adobe-commerce/headless-integration.md) ##### Implementation examples ![](/images/f/2/2/c/f/f22cf6a7525fc96518b9f2755d03270e606d9bf6-github-icon.png)  [See our example integration on GitHub!](https://github.com/adyen-examples/magento-headless-demo) 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. You can use one of the following web APIs to get Adyen functionalities in your Adobe Commerce headless implementation: * **REST**: The most widely used web API. This method allows you to access all the functionalities provided by the Adyen plugin. * **GraphQL**: Requires plugin v8.2.0 or later The Adyen plugin utilizes the `/graphql` endpoint exposed by the Adobe Commerce back-end, and adds functionality that is related to the plugin. You can access all functionalities provided by the Adyen plugin with this method. For more information, checkout the [Adobe Commerce GraphQL documentation](https://developer.adobe.com/commerce/webapi/graphql/). ## Ecommerce checkout flow ##### Postman ![](/user/pages/docs/05.plugins/04.adobe-commerce/08.headless-integration/postman-icon.svg?decoding=auto\&fetchpriority=auto)   See the API flows for a guest shopper on Postman * [REST API](https://www.postman.com/adyendev/adyen-flows/flow/669e40799441740032f40154) * [GraphQL](https://www.postman.com/adyendev/adyen-flows/flow/66b665d5cafbb0003264bef9) 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](#get-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](#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](#place-order). 4. [Check the payment status](#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](#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: 1. Make sure that you have completed the steps to configure the Adobe Commerce back end: * [Set up the Adyen Customer Area](/plugins/adobe-commerce/set-up-adyen-customer-area). * [Set up the plugin in Adobe Commerce](/plugins/adobe-commerce/set-up-the-plugin-in-adobe-commerce). * [Set up the payment methods in Adobe Commerce](/plugins/adobe-commerce/set-up-the-payment-methods-in-adobe-commerce). * [Configured headless integration settings in Adobe Commerce](/plugins/adobe-commerce/set-up-the-payment-methods-in-adobe-commerce#configure-headless-integration). * [Get familiar with the front end components implementation](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=Components). 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. 2. The plugin uses [Adobe Commerce’s recommended authentication methods](https://developer.adobe.com/commerce/webapi/get-started/authentication/) 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](https://developer.adobe.com/commerce/webapi/get-started/authentication/gs-authentication-token/#integration-tokens) is no longer required. Customer token needs to be used as [`Bearer Token` ](https://developer.adobe.com/commerce/webapi/get-started/authentication/#token-based-bearer-authentication)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](https://developer.adobe.com/commerce/webapi/get-started/authentication/gs-authentication-session/). ## Step 1: Get available payment methods In this step, the Adobe Commerce back end retrieves the available payment methods from the [/paymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/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](#make-api-request) to get the payment methods and data that you need to collect. 2. [Parse the API response](#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`. ### Tab: REST * Guest shoppers (not logged-in) * GET [`/V1/guest-carts/{cartId}/payment-information`](https://adobe-commerce.redoc.ly/2.4.6-admin/tag/guest-cartscartIdpayment-information#operation/GetV1GuestcartsCartIdPaymentinformation)\ Alternatively, * POST [`/V1/guest-carts/{cartId}/shipping-information`](https://adobe-commerce.redoc.ly/2.4.6-admin/tag/guest-cartscartIdshipping-information#operation/PostV1GuestcartsCartIdShippinginformation) * Logged-in shoppers * GET [`/V1/carts/mine/payment-information`](https://adobe-commerce.redoc.ly/2.4.6-admin/tag/cartsminepayment-information#operation/GetV1CartsMinePaymentinformation)\ Alternatively, * POST [`/V1/carts/mine/shipping-information`](https://adobe-commerce.redoc.ly/2.4.6-admin/tag/cartsmineshipping-information#operation/PostV1CartsMineShippinginformation) The `/payment-information` and `/shipping-information` responses include `extension_attributes`. This field contains available payment methods and required extra information as `adyen_payment_methods_response`. The required extra information is relevant when [collecting shopper details in Step 2](#collect-shopper-details). The `payment_methods` object in the response of `/payment-information` or `/shipping-information` endpoints is filtered and sorted according to the response of [/paymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) endpoint. ### Tab: GraphQL Pass the following parameters in the request to retrieve payment methods for logged-in and guest shoppers: | Parameter | Required | Description | | ---------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cart_id` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your reference to the shopper's cart. See [cart query in Adobe](https://developer.adobe.com/commerce/webapi/graphql/schema/cart/queries/cart/) for more information. | | `shopper_locale` | | The combination of a language code and a country code to specify the language to be used in the payment. For example, **en\_GB**. This parameter overrides the default locale set in the store settings. | The request calls the [`getPaymentMethods` ](https://github.com/Adyen/adyen-magento2/blob/51216d2b56049c8f0b8c7f2faaa51e3172067c29/Model/Api/AdyenPaymentMethodManagement.php#L27)method, which then makes a POST request to the [/paymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) endpoint. ```graphql query getAdyenPaymentMethods($cartId: String!, $shopperLocale: String) { adyenPaymentMethods(cart_id: $cartId, shopper_locale: $shopperLocale) { paymentMethodsExtraDetails { type icon { url width height } isOpenInvoice configuration { amount { value currency } currency } } paymentMethodsResponse { paymentMethods { name type brand brands configuration { merchantId merchantName } } } } } ``` ### 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/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](#place-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](https://developer.adobe.com/commerce/webapi/graphql/usage). **Example API response** ```json { "payment_methods": [ ... { "code": "adyen_cc", "title": "Credit Card" }, { "code": "adyen_ideal", "title": "iDeal" }, { "code": "adyen_googlepay", "title": "Google Pay" }, ... ], "totals": { ... }, "extension_attributes": { "adyen_payment_methods_response": "{\"paymentMethodsResponse\":{\"paymentMethods\":[{\"details\":[{\"items\":[{\"id\":\"1121\",\"name\":\"Test Issuer\"},{\"id\":\"1154\",\"name\":\"Test Issuer 5\"},{\"id\":\"1153\",\"name\":\"Test Issuer 4\"},{\"id\":\"1152\",\"name\":\"Test Issuer 3\"},{\"id\":\"1151\",\"name\":\"Test Issuer 2\"},{\"id\":\"1162\",\"name\":\"Test Issuer Cancelled\"},{\"id\":\"1161\",\"name\":\ …" } } ``` * 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: 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`. ** #### Example response after parsing ```json { "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. 1. Use the `name` values from the [/paymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/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. You can do this by [rendering the input fields with Adyen Components](#render-with-components). ### Render the input fields with Adyen Components You can use our [Web Components](/online-payments/build-your-integration/advanced-flow?platform=Web\&integration=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](/online-payments/build-your-integration/advanced-flow?platform=Web\&integration=Components#add), 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/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](#create-a-data-object) to send in the Adobe Commerce API request. 2. [Place the order](#place-an-order) with the created object. ### 1. Create a data object ### Tab: REST First, create a data object that you can send in the [Adobe Commerce 2 REST API](https://developer.adobe.com/commerce/webapi/rest/quick-reference/) `/payment-information` request. To get the necessary details for this object, you can do either of the two: * Use `state.data` from the [Web component](/online-payments/build-your-integration/advanced-flow?platform=Web\&integration=Components). * Replicate the request object based on the documentation for the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) endpoint, with the following parameters. | Parameter | Required | Description | | -------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `method` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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](https://github.com/Adyen/adyen-magento2/blob/master/view/frontend/web/js/view/payment/method-renderer/adyen-cc-method.js#L356-L362). If you implement the `onBrand` callback for the Web Component, then you can find it as `state.brand`. See [example](https://github.com/Adyen/adyen-magento2/blob/master/view/frontend/web/js/view/payment/method-renderer/adyen-cc-method.js#L133-L137). | | `brand_code` | **Only for v9** If `method` is an alternative payment method | The value of `state.data.paymentMethod.type` field. | | `recurringProcessingModel` | ![-x-](/user/data/smileys/emoji/x.png "-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](https://help.adyen.com/knowledge/ecommerce-integrations/tokenization/how-to-choose-recurring-processing-model) you are making the request for. | | `stateData` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Use the `JSON.stringify()` function on the `state.data` object that you get from the Web Component. See [example](https://github.com/Adyen/adyen-magento2/blob/master/view/frontend/web/js/view/payment/method-renderer/adyen-cc-method.js#L244-264). The `state.data` object can be [set in a separate request](/plugins/adobe-commerce/headless-integration#setting-the-payment-state-data-in-a-separate-request) to accommodate special checkout flows. | * When replicating the object for a card payment method, follow this structure: **Example data object for a card payment method** ```json { "method": "adyen_cc", "additional_data": { "cc_type": "MC", "recurringProcessingModel": "Subscription", "stateData": "{\"riskData\":{\"clientData\":\"eyJ2ZXJz...\"},\"paymentMethod\":{\"type\":\"scheme\",\"holderName\":\"Holder name\",\"encryptedCardNumber\":\"adyenjs_0_1_25...\",\"encryptedExpiryYear\":\"adyenjs_0_1_25...\",\"encryptedSecurityCode\":\"adyenjs_0_1_25...\",\"brand\":\"mc\"},\"browserInfo\":{\"acceptHeader\":\"*/*\",\"colorDepth\":30,\"language\":\"en-US\",\"javaEnabled\":false,\"screenHeight\":900,\"screenWidth\":1440,\"userAgent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X)\",\"timeZoneOffset\":-120},\"clientStateDataIndicator\":true}\" } } ``` * When replicating the object for an alternative payment method, follow this structure: **Example data object for an alternative payment method** ```json { "method": "adyen_ideal", "additional_data": { "recurringProcessingModel": "Subscription", "stateData": "{\"riskData\":{\"clientData\":\"eyJ2ZXJz...\"},\"paymentMethod\":{\"type\":\"ideal\",\"issuer\":\"1121\"},\"clientStateDataIndicator\":true}" } } ``` ### Tab: GraphQL To place an order using GraphQL, use the `placeAdyenOrder` mutation. This mutation is a combination of the [`setPaymentMethodOnCart` ](https://developer.adobe.com/commerce/webapi/graphql/schema/cart/mutations/set-payment-method/)and [`placeOrder` ](https://developer.adobe.com/commerce/webapi/graphql/schema/cart/mutations/place-order/)mutations. First, create a data object to send in the [`setPaymentMethodOnCart` ](https://developer.adobe.com/commerce/webapi/graphql/schema/cart/mutations/set-payment-method/)mutation. To get the necessary details for this object, you can do either of the two: * Use `state.data` from the [Web component](/online-payments/build-your-integration/advanced-flow?platform=Web\&integration=Components). * Replicate the request object based on the documentation for the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) endpoint, with the following parameters. | Parameter | Required | Description | | -------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `code` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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](https://github.com/Adyen/adyen-magento2/blob/master/view/frontend/web/js/view/payment/method-renderer/adyen-cc-method.js#L356-L362). If you implement the `onBrand` callback for the Web Component, then you can find it as `state.brand`. See [example](https://github.com/Adyen/adyen-magento2/blob/master/view/frontend/web/js/view/payment/method-renderer/adyen-cc-method.js#L133-L137). | | `brand_code` | **Only for v9** If `method` is an alternative payment method | The value of `state.data.paymentMethod.type` field. | | `recurringProcessingModel` | ![-x-](/user/data/smileys/emoji/x.png "-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](https://help.adyen.com/knowledge/ecommerce-integrations/tokenization/how-to-choose-recurring-processing-model) you are making the request for. | | `stateData` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | JSON.stringify() the `state.data` object that you get from the Web Component. See [example](https://github.com/Adyen/adyen-magento2/blob/master/view/frontend/web/js/view/payment/method-renderer/adyen-cc-method.js#L244-264). | * When replicating the object for a card payment method, follow this structure: **Example data object for a card payment method** ```graphql setPaymentMethodOnCart( input: { cart_id: $cartId payment_method: { code: "adyen_cc" adyen_additional_data_cc: { cc_type: "VI" recurringProcessingModel: "Subscription" stateData: $stateData } } } ) ``` * When replicating the object for an alternative payment method, follow this structure: **Example data object for an alternative payment method** ```graphql setPaymentMethodOnCart( input: { cart_id: $cartId payment_method: { code: "adyen_ideal" adyen_additional_data: { recurringProcessingModel: "Subscription" stateData: $stateData } } } ) ``` ### 2. Place an order ### Tab: REST Place the order with the `/payment-information` endpoint from the [Adobe Commerce REST API](https://developer.adobe.com/commerce/webapi/rest/quick-reference/). Use the object created in the previous step. If you cannot use the `/payment-information` endpoint to set `state.data`, see [setting the payment `state.data` in a separate request](/plugins/adobe-commerce/headless-integration#setting-the-payment-state-data-in-a-separate-request). **Place the order with REST** ```json { "email": "SHOPPER_EMAIL_ADDRESS", "billingAddress": { "city": "Gravenhage", "company": "", "countryId": "NL", "firstname": "John Doe", "lastname": "Approved", "postcode": "2521VA", "region": "Netherlands", "saveInAddressBook": null, "street": [ "Neherkade 1 XI" ], "telephone": "0612345678" }, "paymentMethod": { "method": "adyen_ideal", "additional_data": { "stateData": "{\"riskData\":{\"clientData\":\"eyJ2ZXJz...\"},\"paymentMethod\":{\"type\":\"ideal\",\"issuer\":\"1121\"},\"clientStateDataIndicator\":true}" } } } ``` ** #### Setting the payment \`state.data\` in a separate request Plugin v7.2.0 and later 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 cannot be sent using the `/payment-information` [Adobe Commerce REST API endpoint](https://developer.adobe.com/commerce/webapi/rest/quick-reference/). The `/state-data` 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. ### Tab: GraphQL Place the order using the `placeAdyenOrder` mutation. Use the `setPaymentMethodOnCart` object created in the previous step. **Place the order with GraphQL** ```graphql mutation placeAdyenOrder( $cartId: String! $stateData: String! ) { setPaymentMethodOnCart( input: { cart_id: $cartId payment_method: { code: "adyen_ideal" adyen_additional_data: { stateData: $stateData } } } ) { cart { selected_payment_method { code title } } } placeOrder( input: { cart_id: $cartId } ) { order { order_number cart_id adyen_payment_status { isFinal resultCode additionalData action } } } } ``` For more information, refer to the [Adobe Commerce API documentation](https://developer.adobe.com/commerce/webapi/rest/). 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: ### Tab: REST 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](https://github.com/Adyen/adyen-magento2/blob/5d6b157887eb3c4c810cad882d1c17b356309e23/view/frontend/web/js/view/payment/method-renderer/adyen-cc-method.js#L280). ### Tab: GraphQL 1. Call an `adyenPaymentStatus` query. In the URL, use the `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](https://github.com/Adyen/adyen-magento2/blob/5d6b157887eb3c4c810cad882d1c17b356309e23/view/frontend/web/js/view/payment/method-renderer/adyen-cc-method.js#L280). ```graphql query getAdyenPaymentStatus($orderNumber: String!, $cartId: String!) { adyenPaymentStatus(orderNumber: $orderNumber, cartId: $cartId) { // $orderNumber is the order increment Id. isFinal resultCode additionalData action } } ``` 2. 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](#handle-additional-actions). * The `isFinal` field is **false**: * The `action` field is present and is not empty, then [handle the additional action using the Web Component](#handle-additional-actions). ## 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](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=Components#additional-action) or find specific documentation for each payment method in [this list](/payment-methods). All payment methods use the `createFromAction` method, except for PayPal. The [PayPal Component](/payment-methods/paypal/web-component?tab=_code_payments_code__2) uses the `handleAction` method to process additional action from the PayPal pop-up window. ### Tab: REST Create your request to handle the additional action with the following fields: * `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](#place-an-order). **Handle additional actions** ```json { "payload": "{\"details\":{\"threeDSResult\":\"eyJ0cmFuc1N..."}}", "orderId": "175", "cartId": "r8Mktr..." } ``` ### Optional: Validate the `state.data` from the action component In case the shopper is already redirected to the success page, you do not 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](/plugins/adobe-commerce/set-up-the-plugin-in-adobe-commerce#step-2-run-cron) 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. ### Tab: GraphQL Use the `getAdyenPaymentDetails` query to handle the additional actions. Create your request to handle the additional action with the following fields: * `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](#place-an-order). **Handle additional actions** ```graphql mutation getAdyenPaymentDetails($payload: String!, $cartId: String!) { adyenPaymentDetails(payload: $payload, cart_id: $cartId) { isFinal resultCode additionalData action } } ``` ## Gift card payments After you have followed the steps to [get the available payment methods](#get-payment-methods) and [present them in your front end](#collect-shopper-details), 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: 1. Follow the steps to [configure the Component](/payment-methods/gift-cards/web-component/?tab=config-payments_3#component-configuration).\ When [creating an instance of the Component](/payment-methods/gift-cards/web-component/?tab=config-payments_3#step-2-create-an-instance-of-the-component), in the `onBalanceCheck` event, call the `adyenPaymentMethodsBalance` GraphQL mutation that returns the available balance of a gift card. 2. Use the `JSON.stringify()` function on the `data` object you get from the event. This is the `payload` for the `adyenPaymentMethodsBalance` mutation. **Example payload object to check balance** ```js {\"paymentMethod\":{\"type\":\"giftcard\",\"brand\":\"svs\",\"encryptedCardNumber\":\"abc…\",\"encryptedSecurityCode\":\"xyz…\"},\"amount\":{\"currency\":\"EUR\",\"value\":1000}} ``` **GraphQL mutation to check the balance of a gift card** ```js query adyenPaymentMethodsBalance ($payload: String!) { adyenPaymentMethodsBalance (payload: $payload) { balanceResponse } } ``` This mutation returns the balance of a gift card, and additional details like the currency and value. For example: **Gift card balance response** ```js { "data": { "adyenPaymentMethodsBalance": { "balanceResponse": "{\"pspReference\":\"GB573LDWSBFWFL65\",\"resultCode\":\"Success\",\"balance\":{\"currency\":\"EUR\",\"value\":5000}}" } } } ``` ### 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. **GraphQL mutation to save state data** ```js mutation adyenSaveStateData ($state_data: String!, $cart_id: String!) { adyenSaveStateData (stateData: $state_data, cartId: $cart_id) { stateDataId } } ``` * `stateData`: The JSON string that contains state data to save. * `cart_id`: Use the [cart ID](https://developer.adobe.com/commerce/webapi/graphql/schema/cart/queries/cart/) of your shopper's cart. This mutation makes a request to save the state data: **Example request to save state data** ```js { "state_data": "{\"paymentMethod\":{\"type\":\"giftcard\",\"brand\":\"svs\",\"encryptedCardNumber\":\"abc...\",\"encryptedSecurityCode\":\"xyz...\"},\"giftcard\":{\"balance\":{\"currency\":\"EUR\",\"value\":5000},\"title\":\"SVS\"}}", "cart_id": "zJAHYuFaTn..." } ``` You get a `stateDataId` object that you can use to remove the saved state data later. **Example response after saving state data** ```js { "data": { "adyenSaveStateData": { "stateDataId": "1" } } } ``` 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: **Implement the mutation to remove saved state data** ```js mutation adyenRemoveStateData ($state_data_id: Int!, $cart_id: String!) { adyenRemoveStateData (stateDataId: $state_data_id, cartId: $cart_id) { stateDataId } } ``` * `stateDataId`: The ID that you received in the response when you saved state data. * `cart_id`: Use the [cart ID](https://developer.adobe.com/commerce/webapi/graphql/schema/cart/queries/cart/) of your shopper's cart. You get a response containing the `stateDataId` for removed state data. ### Step 3: Redeem gift cards 1. 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. **GraphQL mutation to get redeemed gift cards** ```js query adyenRedeemedGiftcards ($cart_id: String!) { adyenRedeemedGiftcards (cartId: $cart_id) { redeemedGiftcards { stateDataId brand title balance { currency value } deductedAmount } remainingAmount totalDiscount } } ``` **Example response with redeemed gift cards** ```js { "data": { "adyenRedeemedGiftcards": { "redeemedGiftcards": [ { "stateDataId": "11", "brand": "svs", "title": "SVS", "balance": { "currency": "EUR", "value": "5000" }, "deductedAmount": "€0.00" } ], "remainingAmount": "€75.00", "totalDiscount": "€50.00" } } } ``` 2. Compare the amount of the shopper's cart to the balance available on the gift card. The way you [place the order](/plugins/adobe-commerce/headless-integration?tab=graphql1_2#place-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](#save-gift-card-state-data). After you have followed the above steps, [check the payment status](/plugins/adobe-commerce/headless-integration?tab=graphql4_2#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](/plugins/adobe-commerce/set-up-tokenization/#how-it-works), using the [Adobe Commerce Vault](https://developer.adobe.com/commerce/php/development/payments-integrations/vault/). ### Tokenize shopper payment details Follow the steps to [set up the vault in Adobe Commerce](/plugins/adobe-commerce/set-up-tokenization/#set-up-vault). * For alternative payment methods, the payment details of shoppers will be tokenized for payment methods that you [enable tokenization](/plugins/adobe-commerce/set-up-tokenization/#set-up-vault) for. * For cards, you must [enable storing payment details](/payment-methods/cards/web-component/?tab=store-card-details-payment-methods_2#store-card-details) in your [card component configuration](/payment-methods/cards/web-component/?tab=store-card-details-payment-methods_2#optional-configuration), by setting `enableStoreDetails` to **true**.\ This setting displays a **Save for my next payment** checkbox when a shopper is making a card payment. The shopper payment details are 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](https://github.com/Adyen/adyen-magento2/blob/master/etc/webapi.xml) 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](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/overview) 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-versions). ### 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](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/overview). 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](/plugins/release-notes/?title%5B0%5D=Adobe%2BCommerce). Alternatively: 1. Go to the [Adyen Adobe Commerce (formerly Magento 2) plugin on GitHub](https://github.com/Adyen/adyen-magento2/blob/main/composer.json). 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](https://github.com/Adyen/adyen-php-api-library/blob/develop/src/Adyen/Client.php#23). 5. In the **Branch** dropdown, on the **Tags** tab, select the library version you have 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 * [Adobe Commerce plugin](/plugins/adobe-commerce) * [Payment methods](/payment-methods)