---
title: "Express checkout"
description: "Integrate express payment methods for your headless Adobe Commerce integration."
url: "https://docs.adyen.com/plugins/adobe-commerce/headless-integration/express-checkout"
source_url: "https://docs.adyen.com/plugins/adobe-commerce/headless-integration/express-checkout.md"
canonical: "https://docs.adyen.com/plugins/adobe-commerce/headless-integration/express-checkout"
last_modified: "2024-01-05T11:36:00+01:00"
language: "en"
---

# Express checkout

Integrate express payment methods for your headless Adobe Commerce integration.

[View source](/plugins/adobe-commerce/headless-integration/express-checkout.md)

Our [express checkout module](https://github.com/Adyen/adyen-magento2-express-checkout) lets you implement [express checkout](/payment-methods/express-checkout) for your headless Adobe Commerce integration.

The module supports express payments with [Apple Pay](/payment-methods/apple-pay), [Google Pay](/payment-methods/google-pay), and [PayPal](/payment-methods/paypal). You can offer the option to use express checkout by placing express payment method buttons in the product detail, cart, and mini-cart pages on your website. This lets your shopper complete their payment without having to go to a separate checkout page.

## Requirements

| Requirement          | Description                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Integration type** | Make sure that you have:- A [headless Adobe Commerce plugin integration](/plugins/adobe-commerce/headless-integration).
- [Web Components](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=Components\&version=latest) integrations for the [express payment methods](/payment-methods/express-checkout/#supported-express-payment-methods) that you want to support. |
| **Setup steps**      | Before you begin:- [Install the Adobe Commerce express checkout module](/plugins/adobe-commerce/set-up-the-plugin-in-adobe-commerce#use-express-checkout).
- [Implement express checkout](/payment-methods/express-checkout/#get-started) for the express payment methods that you offer.                                                                                                              |

## Headless integration types

##### Learn more

![](/images/b/2/2/1/b/b221b265a9c6b77a7b46951d7e3db0fc381397ba-github-icon.png) Find the [GraphQL schema definition](https://github.com/Adyen/adyen-magento2-express-checkout/blob/main/etc/schema.graphqls) and the [REST API implementation](https://github.com/Adyen/adyen-magento2-express-checkout/blob/main/etc/webapi.xml) for express checkout on our GitHub.

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/).

The steps to follow to set up express payment methods are different for REST and GraphQL integrations. If you are using REST, the endpoint differs per use case. If you are using GraphQL, the endpoint is `/graphql`, and there are different [mutations](https://graphql.org/learn/queries/#mutations) that you need to use.

## How it works

With a headless Adobe Commerce integration, you can use the Adyen [Web Components](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=Components\&version=latest) to support express checkout. You use our Components to show the express payment methods to your shoppers, and make requests to the Adobe Commerce API to handle the payment flow.

The flow depends on where you show the option to use express checkout in your store:

### Tab: Cart or mini-cart page

1. Adobe Commerce [initializes a quote for the order](#initialize-a-quote).
2. When the shopper enters their shipping address, [present the available shipping methods](#shipping-address).
3. When the shopper selects a shipping method, [update the order with the shipping method](#shipping-methods).
4. The total payment amount may change depending on the shipping method the shopper selects, in such cases, [handle the changes to the payment amount](#handle-payment-amount-changes).
5. When the shopper selects the express payment button, the payment method components trigger an event.
6. Use the Adobe Commerce API to [complete the payment](#complete-the-payment) within the event.

### Tab: Product detail page

* To display the option to use express checkout on the product detail page, [initialize a quote for the order](#initialize-a-quote).

* When the shopper enters their shipping address, [present the available shipping methods](#shipping-address).

* When the shopper selects a shipping method, [update the order with the shipping method](#shipping-methods).

* The total payment amount may change depending on the shipping method the shopper selects, in such cases, you [handle the changes to the payment amount](#handle-payment-amount-changes).

* When the shopper selects the express payment button, the payment method components trigger an event.

* Use Adobe Commerce API to [activate the quote that you initialized, and complete the payment](#complete-the-payment) within the event.

## Initialize a quote

Adobe Commerce requires a quote to be generated to complete a transaction and create an order.

If you show express payment methods on:

* **Cart or mini-cart pages**: when a shopper adds an item to their shopping cart for the first time, Adobe commerce [creates a quote](https://developer.adobe.com/commerce/webapi/rest/tutorials/orders/order-create-quote/). Proceed to [get the shopper's address and available shipping methods](#shipping-address).
* **Product detail page**: [initialize a quote manually](#initialize-a-quote-manually).

### Initialize a quote manually

To initialize a quote on the product detail page, 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

#### Logged-in shoppers

* POST `/V1/adyen/express/init/mine`

  | Parameter            | Required                                                                                    | Description                                                                                                                                                                                                                                                                                                      |
  | -------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `productCartParams`  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An instance of the [`ProductCartParamsInterface` ](https://github.com/Adyen/adyen-magento2-express-checkout/blob/main/Api/Data/ProductCartParamsInterface.php), including the product ID, quantity, and options for configurable products. The object should be a JSON encoded string.                           |
  | `adyenCartId`        |                                                                                             | The logged-in shopper's real cart ID. If a cart already exists at the time of the initialization request, this request disables the existing real cart using the cart ID.                                                                                                                                        |
  | `adyenMaskedQuoteId` |                                                                                             | The quote initialized to mount the payment method component on the product detail page. You receive this value in the response to your first request to the endpoint and can use it in your subsequent requests. In subsequent requests, this field is used to update the quote in case of changes to the order. |

In the response, you receive the `adyenMaskedQuoteId` that you need to use to mount the component in the [next step](#shipping-address).

#### Guest shoppers

* POST `/V1/adyen/express/init/guest`

  | Parameter            | Required                                                                                    | Description                                                                                                                                                                                                                                                                                                      |
  | -------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `productCartParams`  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An instance of the [`ProductCartParamsInterface` ](https://github.com/Adyen/adyen-magento2-express-checkout/blob/main/Api/Data/ProductCartParamsInterface.php), including the product ID, quantity, and options for configurable products in a JSON encoded string format.                                       |
  | `guestMaskedId`      |                                                                                             | The guest shopper's real cart ID. If a cart already exists at the time of the initialization request, this request disables the existing real cart using the cart ID.                                                                                                                                            |
  | `adyenMaskedQuoteId` |                                                                                             | The quote initialized to mount the payment method component on the product detail page. You receive this value in the response to your first request to the endpoint and can use it in your subsequent requests. In subsequent requests, this field is used to update the quote in case of changes to the order. |

In the response, you receive the `adyenMaskedQuoteId` that you need to use to mount the component in the [next step](#shipping-address).

### Tab: GraphQL

Use the `expressInit` GraphQL mutation to initialize a quote on the product detail page. If there is already a quote initialized on the product detail page, this mutation updates the quote.

Create a data object to send in the mutation, that includes the following:

| Parameter            | Required                                                                                    | Description                                                                                                                                                                                                                                                                                                      |
| -------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `productCartParams`  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An instance of the [`ProductCartParamsInterface` ](https://github.com/Adyen/adyen-magento2-express-checkout/blob/main/Api/Data/ProductCartParamsInterface.php), including the product ID, quantity, and options for configurable products in a JSON encoded string format.                                       |
| `guestMaskedId`      |                                                                                             | The guest shopper's real cart ID. If a cart already exists at the time of the initialization request, this request disables the existing real cart using the cart ID.                                                                                                                                            |
| `adyenMaskedQuoteId` |                                                                                             | The quote initialized to mount the payment method component on the product detail page. You receive this value in the response to your first request to the endpoint and can use it in your subsequent requests. In subsequent requests, this field is used to update the quote in case of changes to the order. |

In the response, you receive the `adyenMaskedQuoteId` that you need to use to mount the component in the [next step](#shipping-address).

## Get the shopper's address and available shipping methods

After an Adobe Commerce quote is created for the shopper's order, start the express checkout flow by presenting the express payment method and collecting the shopper's details.

### Tab: REST

1. Mount the express payment method component:

   * On the **cart and mini-cart pages**, you can mount the component after your shopper adds an item to their cart.
   * On the **product detail page**, you can mount the component after receiving the `adyenMaskedQuoteId`.

2. When your shopper selects the **Pay** button for the express payment method, the component shows the payment form.

   * For Apple Pay and Google Pay, you do not need to take additional action to show the payment form.
   * For PayPal, there are [extra steps to show the PayPal lightbox](#show-the-paypal-lightbox).

   **

   #### Show the PayPal lightbox

   For PayPal express payments, you need initial payment data to show the PayPal lightbox when your shopper selects the PayPal button.

   Make a request to one of the following endpoints to obtain the initial data, depending on your shopper's use case.

   #### Logged-in shoppers

   * POST `/V1/adyen/express/init-payments/mine`

     | Parameter            | Required                                                                                    | Description                                                                                                                                                               |
     | -------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | `stateData`          | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The `state.data` from the `onSubmit` event in the PayPal Web Component.                                                                                                   |
     | `adyenCartId`        |                                                                                             | **Required if** `adyenMaskedQuoteId` is not included. The logged-in shopper's real cart ID.                                                                               |
     | `adyenMaskedQuoteId` |                                                                                             | **Required if**`adyenCartId` is not included. If you initialized a quote manually to mount the payment method component on the product detail page, this is the quote ID. |

   #### Guest shoppers

   * POST `/V1/adyen/express/init-payments/guest`

     | Parameter            | Required                                                                                    | Description                                                                                                                                                                |
     | -------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | `stateData`          | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The `state.data` from the `onSubmit` event in the PayPal Web Component.                                                                                                    |
     | `guestMaskedId`      |                                                                                             | **Required if** `adyenMaskedQuoteId` is not included. The guest shopper's real cart ID.                                                                                    |
     | `adyenMaskedQuoteId` |                                                                                             | **Required if** `adyenCartId` is not included. If you initialized a quote manually to mount the payment method component on the product detail page, this is the quote ID. |

   When you make a request to one of these endpoints, we make a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request to obtain the `paymentData` object. The response includes the following:

   * `paymentData`: The payment data object that is required to show the PayPal lightbox. You need this value to update the PayPal order in later steps.

   * `response.action`: The `action` object from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response. Pass this from your server to the Component:

     ```javascript
     component.handleAction(response.action);
     ```

     If the PayPal overlay gets stuck at loading state, make sure that you pass the full `response.action` object to the Component. See [Troubleshooting PayPal](/payment-methods/paypal/paypal-troubleshooting/#paypal-overlay-keeps-loading) for more information.

3. When your shopper enters their shipping contact and address in the payment form, obtain the address changes from the event handlers of each payment method component.\
   For example, the [Apple Pay Component](/payment-methods/apple-pay/web-component/#ap-events) calls the [`onShippingContactSelected` ](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778009-onshippingcontactselected)event handler when the shopper selects their shipping contact.

4. In the event handler, make an API request to get the available shipping methods based on the shopper's shipping address.

   * **Logged-in shoppers**:
     * POST [`/V1/carts/mine/estimate-shipping-methods`](https://adobe-commerce.redoc.ly/2.4.7-admin/tag/cartsmineestimate-shipping-methods/#operation/PostV1CartsMineEstimateshippingmethods)
   * **Guest shoppers**
     * POST [`/V1/guest-carts/{cartId}/estimate-shipping-methods`](https://adobe-commerce.redoc.ly/2.4.7-admin/tag/guest-cartscartIdestimate-shipping-methods#operation/PostV1GuestcartsCartIdEstimateshippingmethods)

5. Only if you support PayPal express, [update the PayPal order](#update-paypal) after you get the available shipping methods to update the PayPal lightbox.

6. Use the response to present the available shipping methods to your shoppers.

### Tab: GraphQL

* Mount the express payment method component:

  * On the **cart and mini-cart pages**, you can mount the component anytime after your shopper adds an item to their cart.
  * On the **product detail page**, you can mount the component after receiving the `adyenMaskedQuoteId`.

* When your shopper selects the **Pay** button for the express payment method, the component shows the payment form.

  * For Apple Pay and Google Pay, you do not need to take additional action to show the payment form.
  * For PayPal, there are [extra steps to show the PayPal lightbox](#show-the-paypal-lightbox).

  **

  #### Show the PayPal lightbox

  For PayPal express payments, you need initial payment data to show the PayPal lightbox when your shopper selects the PayPal button.

  Use the `adyenExpressInitPayments` mutation to obtain the payment data. Prepare a data object to send in the mutation that includes the following:

  | Parameter            | Required                                                                                    | Description                                                                                                                                                                |
  | -------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `stateData`          | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The `state.data` from the `onSubmit` event in the PayPal Web Component.                                                                                                    |
  | `adyenCartId`        |                                                                                             | **Required if** `adyenMaskedQuoteId` is not included. The logged-in shopper's real cart ID.                                                                                |
  | `adyenMaskedQuoteId` |                                                                                             | **Required if** `adyenCartId` is not included. If you initialized a quote manually to mount the payment method component on the product detail page, this is the quote ID. |

  This mutation makes a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request to obtain the `paymentData` object. The response includes the following:

  * `paymentData`: The payment data object that is required to show the PayPal lightbox. You need this value to update the PayPal order in later steps.
  * `response.action`: The `action` object from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response. Pass this from your server to the Component:
    ```javascript
    component.handleAction(response.action);
    ```

  If the PayPal overlay gets stuck at loading state, make sure that you pass the full `response.action` object to the Component. See [Troubleshooting PayPal](/payment-methods/paypal/paypal-troubleshooting/#paypal-overlay-keeps-loading) for more information.

* When your shopper enters their shipping contact and address in the payment form, obtain the address changes from the event handlers of each payment method component.\
  For example, the [Apple Pay Component](/payment-methods/apple-pay/web-component/#ap-events) calls the [`onShippingContactSelected` ](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778009-onshippingcontactselected)event handler when the shopper selects their shipping contact.

* In the event handler, use the [`estimateShippingMethods` ](https://developer.adobe.com/commerce/webapi/graphql-api/index.html#mutation-estimateShippingMethods)GraphQL mutation to get the available shipping methods based on the shopper's shipping address.

* Only if you support PayPal express, [update the PayPal order](#update-paypal) after you get the available shipping methods to update the PayPal lightbox.

* Use the response to present the available shipping methods to your shoppers.

## Update the order with the selected shipping method

Update the order in Adobe Commerce after your shopper selects one of the available shipping methods.

### Tab: REST

1. When your shopper selects a shipping method, obtain the selected shipping method from the event handlers of each payment method component.\
   For example, the [Apple Pay Component](/payment-methods/apple-pay/web-component/#ap-events) calls the [`onShippingMethodSelected` ](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778028-onshippingmethodselected)event handler when the shopper selects a shipping method.

2. In the event handler, make an API request to one of the following endpoints to update the Adobe Commerce quote with the shopper address and shipping method that you saved to the component.

   * **Logged-in shoppers**
     * POST [`/V1/carts/mine/shipping-information`](https://adobe-commerce.redoc.ly/2.4.7-admin/tag/cartsmineshipping-information#operation/PostV1CartsMineShippinginformation)
   * **Guest shoppers**
     * POST [`/V1/guest-carts/{cartId}/shipping-information`](https://adobe-commerce.redoc.ly/2.4.7-admin/tag/guest-cartscartIdshipping-information#operation/PostV1GuestcartsCartIdShippinginformation)

   Apple Pay and Google Pay return the shopper details only after a payment is authorized. For these payment methods, use dummy values when calling the `/shipping-information` endpoint. You can call this endpoint again when you receive the shopper's details.

3. Only if you support PayPal express, [update the PayPal order](#update-paypal) after your shopper selects a shipping method to update the PayPal lightbox.

### Tab: GraphQL

* When your shopper selects a shipping method, obtain the selected shipping method from the event handlers of each payment method component.\
  For example, the [Apple Pay Component](/payment-methods/apple-pay/web-component/#ap-events) calls the [`onShippingMethodSelected` ](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778028-onshippingmethodselected)event handler when the shopper selects a shipping method.

* In the event handler, use the following GraphQL mutations to update the Adobe Commerce quote with the shopper address and shipping method that you saved to the component.

  * [`setShippingAddressesOnCart`](https://developer.adobe.com/commerce/webapi/graphql-api/index.html#mutation-setShippingAddressesOnCart)
  * [`setShippingMethodsOnCart`](https://developer.adobe.com/commerce/webapi/graphql-api/index.html#mutation-setShippingMethodsOnCart)

  Apple Pay and Google Pay return the shopper details after the payment is authorized. For these payment methods, use dummy values. You can use the mutation again when you receive the shopper's details.

* Only if you support PayPal express, [update the PayPal order](#update-paypal) after your shopper selects a shipping method to update the PayPal lightbox.

## Handle payment amount changes

The total payment amount may change depending on the shopper's selected shipping method. You must then update the payment method component and the Adobe Commerce quote with the final amount.

### Tab: REST

1. To get the total order amount, make an API request to one of the following endpoints:

   * **Logged-in shoppers**
     * POST [`/V1/carts/mine/totals-information`](https://adobe-commerce.redoc.ly/2.4.7-admin/tag/cartsminetotals-information#operation/PostV1CartsMineTotalsinformation)
   * **Guest shoppers**
     * POST [`/V1/guest-carts/{cartId}/totals-information`](https://adobe-commerce.redoc.ly/2.4.7-admin/tag/cartscartIdtotals-information#operation/PostV1CartsCartIdTotalsinformation)

2. After you obtain the updated total payment amount, pass this to the payment method component. The payment method components have functions that you can use in event handlers.\
   For example, the [Apple Pay](/payment-methods/apple-pay/web-component/express-checkout/#step-4-configure-the-callback-to-handle-shipping-method-changes) component lets you use the `resolve()` function in the event handler to set the new payment amount.

### Tab: GraphQL

* To get the total order amount, use the [`estimateTotals` ](https://developer.adobe.com/commerce/webapi/graphql-api/index.html#mutation-estimateTotals)GraphQL mutation.

* After you obtain the updated total payment amount, pass this to the payment method component. The payment method components have functions that you can use in event handlers.\
  For example, the [Apple Pay](/payment-methods/apple-pay/web-component/express-checkout/#step-4-configure-the-callback-to-handle-shipping-method-changes) component lets you use the `resolve()` function in the event handler to set the new payment amount.

## Complete the payment

To complete the payment, the shopper's cart must be active. If you show express payment methods on:

* **Cart or mini-cart pages**: the shopper's cart is already active. Proceed to [place the order](#place-the-order).
* **Product detail page**: you must [manually activate](#activate-the-cart-manually) the cart for the quote you initialized manually.

### Activate the cart manually

If you show express payment methods on the product detail page, and [initialized a quote manually](#initialize-a-quote), make an API request to activate the cart for the quote you initialized.

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

### Tab: REST

#### Logged-in shoppers

* POST `/V1/adyen/express/activate/mine`

  | Parameter            | Required                                                                                    | Description                                                                                                                                                                                                                   |
  | -------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `adyenMaskedQuoteId` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The quote initialized to mount the payment method component on the product detail page. You receive this in the `/V1/adyen/express/init/guest` response when you [initialize a quote manually](#initialize-a-quote-manually). |
  | `adyenCartId`        |                                                                                             | The ID of the logged-in shopper's real cart.                                                                                                                                                                                  |

#### Guest shoppers

* POST `/V1/adyen/express/activate/guest`

  | Parameter              | Required                                                                                    | Description                                                                                                                                                                                                                   |
  | ---------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `adyenMaskedQuoteId`   | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The quote initialized to mount the payment method component on the product detail page. You receive this in the `/V1/adyen/express/init/guest` response when you [initialize a quote manually](#initialize-a-quote-manually). |
  | `currentMaskedQuoteId` |                                                                                             | The ID of the guest shopper's real cart.                                                                                                                                                                                      |

### Tab: GraphQL

Use the `expressActivate` mutation to activate the quote you initialized on the product detail page for logged-in users. This mutation disables any other real carts.

Create a data object to send in the mutation, that includes the following:

| Parameter            | Required                                                                                    | Description                                                                                                                                                                                                                   |
| -------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `adyenMaskedQuoteId` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The quote initialized to mount the payment method component on the product detail page. You receive this in the `/V1/adyen/express/init/guest` response when you [initialize a quote manually](#initialize-a-quote-manually). |
| `adyenCartId`        |                                                                                             | The shopper's real cart ID.                                                                                                                                                                                                   |

### Place the order

When the shopper selects the express payment button, the payment method components trigger an event to complete the payment. For example, the [Apple Pay Component](/payment-methods/apple-pay/web-component/) triggers the [`onAuthorized` ](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778020-onpaymentauthorized)event. In this event, implement the steps to complete the payment.

### Tab: REST

1. Update the cart details using the data you get in the payment method component event. There are different endpoints to update the billing address and shipping information.

   | Order details        | Endpoint for logged-in shoppers                                                                                                                                    | Endpoint for guest shoppers                                                                                                                                                                  |
   | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | Billing address      | [`V1/carts/mine/billing-address`](https://adobe-commerce.redoc.ly/2.4.7-admin/tag/cartsminebilling-address#operation/PostV1CartsMineBillingaddress)                | [`/V1/guest-carts/{cartId}/billing-address`](https://adobe-commerce.redoc.ly/2.4.7-admin/tag/guest-cartscartIdbilling-address#operation/PostV1GuestcartsCartIdBillingaddress)                |
   | Shipping information | [`V1/carts/mine/shipping-information`](https://adobe-commerce.redoc.ly/2.4.7-admin/tag/cartsmineshipping-information#operation/PostV1CartsMineShippinginformation) | [`/V1/guest-carts/{cartId}/shipping-information`](https://adobe-commerce.redoc.ly/2.4.7-admin/tag/guest-cartscartIdshipping-information#operation/PostV1GuestcartsCartIdShippinginformation) |

2. Place the order with an API request to one of the following endpoints:

   * **Logged-in shoppers**
     * POST [`/V1/carts/mine/payment-information`](https://adobe-commerce.redoc.ly/2.4.7-admin/tag/cartsminepayment-information#operation/PostV1CartsMinePaymentinformation)
   * **Guest shoppers**
     * POST [`/V1/guest-carts/{cartId}/payment-information`](https://adobe-commerce.redoc.ly/2.4.7-admin/tag/guest-cartscartIdpayment-information#operation/PostV1GuestcartsCartIdPaymentinformation)

   Refer to our [headless integration documentation](/plugins/adobe-commerce/headless-integration/#place-order) to learn more about placing an order with the REST API endpoints above.

   **Example request body for the /payment-information endpoint**

   ```javascript
   let paymentInformationPayload = {
      "email":"john.smith@email.com",
      "paymentMethod":{
         "method":"adyen_applepay",
         "additional_data":{
            "brand_code":"applepay",
            "stateData":"JSON.stringify(componentData)" // componentData is the state.data from the payment method component.
         }
      }
   }
   ```

3. Only for Apple Pay, resolve the payment method component with a success message. You can use the `.resolve()` function to do this. See [an example](https://github.com/Adyen/adyen-magento2-express-checkout/blob/d63b452992f4db1c36c2cb2c2c091513e73198b4/view/frontend/web/js/applepay/button.js#L532) on our GitHub.

### Tab: GraphQL

* Update the cart details using the data you get in the payment method component event. There are different GraphQL mutations to update the billing address and shipping information.

  | Order details        | GraphQL mutation                                                                                                                       |
  | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
  | Billing address      | [`setBillingAddressOnCart`](https://developer.adobe.com/commerce/webapi/graphql-api/index.html#mutation-setBillingAddressOnCart)       |
  | Shipping information | [`setShippingAddressesOnCart`](https://developer.adobe.com/commerce/webapi/graphql-api/index.html#mutation-setShippingAddressesOnCart) |

* Place the order with 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/)Adobe Commerce GraphQL mutations.

  Refer to our [headless integration documentation](/plugins/adobe-commerce/headless-integration/#place-order) to learn more about placing an order with this GraphQL mutations.

* Only for Apple Pay, resolve the payment method component with a success message. You can use the `.resolve()` function to do this. See [an example](https://github.com/Adyen/adyen-magento2-express-checkout/blob/d63b452992f4db1c36c2cb2c2c091513e73198b4/view/frontend/web/js/applepay/button.js#L532) on our GitHub.

If you [initialized a quote manually](#initialize-a-quote-manually) to mount the payment method component on the product detail page, and disabled the shopper's real cart, the plugin activates the disabled cart after the payment is completed.

## Get the payment outcome

After you place the order, use the same REST API and GraphQL endpoints you use to [check the payment status](/plugins/adobe-commerce/headless-integration#payment-status) with your standard headless implementation.

When the payment is completed, redirect shoppers to your payment success page.

### Handle abandoned carts

[If you initialized a quote manually](#initialize-a-quote) to initiate the express checkout flow on the product detail page, and the shopper abandons the payment page, cancel the quote manually. The payment method components throw an event to handle this case. For example, the Apple Pay component throws the `onError` event.

In the payment method component's event, make an API request to cancel the quote.

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

### Tab: REST

#### Logged-in shoppers

* POST `/V1/adyen/express/cancel/mine`

  | Parameter            | Required                                                                                    | Description                                                                             |
  | -------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
  | `adyenMaskedQuoteId` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The quote initialized to mount the payment method component on the product detail page. |
  | `adyenCartId`        |                                                                                             | The logged-in shopper's real cart ID.                                                   |

#### Guest shoppers

* POST `/V1/adyen/express/cancel/guest`

  | Parameter       | Required                                                                                    | Description                                                                             |
  | --------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
  | `maskedQuoteId` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The quote initialized to mount the payment method component on the product detail page. |

### Tab: GraphQL

Use the `expressCancel` mutation to cancel the quote you initialized on the product detail page for logged-in users.

Create a data object to send in the mutation, that includes:

* `maskedQuoteId`: The quote initialized to mount the payment method component on the product detail page.

## Updating PayPal orders

For PayPal express payments, you must update the order each time your shopper changes the shipping address or method to update the PayPal lightbox. In the Adyen Checkout API, this is done with the [/paypal/updateOrder](https://docs.adyen.com/api-explorer/Checkout/latest/post/paypal/updateOrder) endpoint.

During the express flow, you have to update the order when:

* [The shopper initially enters their shipping address in the PayPal lightbox](#shipping-address).
* [The shopper selects one of the delivery methods that are available](#shipping-methods).
* The shopper modifies either of these details.

The PayPal component uses events, such as `onShippingAddressChange` or `onShippingOptionsChange`, to handle shipping address and method changes. In these events, make an API request to update the order.

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

### Tab: REST

#### Logged-in shoppers

* POST `/V1/adyen/express/paypal-update-order/mine`

| Parameter                     | Required                                                                                                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |   |
| `amount`                      | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-")                                           | The updated final payment amount. This amount is the item total plus the shipping costs of the selected `deliveryMethod`, specified as an object:* `currency` as a three-character [ISO currency code](/development-resources/currency-codes#currency-codes?target=_blank).
* `value` in [minor units](/development-resources/currency-codes#minor-units?target=_blank).                                                                                                                                                                                                                                                                                                              |
| `paymentData`                 | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-")                                           | For the first request to this endpoint, this is the `paymentData` you receive when you made a request to [show the PayPal lightbox](#show-the-paypal-lightbox). In subsequent requests, this is the updated `paymentData` you receive in the response to this endpoint.                                                                                                                                                                                                                                                                                                                                                                                                               |
| `adyenCartId`                 | Required if `adyenMaskedQuoteId` is not included                                                                                      | The logged-in shopper's real cart ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `adyenMaskedQuoteId`          | Required if `adyenCartId` is not included                                                                                             | The quote initialized to mount the payment method component on the product detail page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `deliveryMethods`             | Required only for [PayPal lightbox with delivery methods](/payment-methods/paypal/web-component/express-checkout/?tab=how-advanced_2) | The array that lists the delivery methods available for the delivery address, and their fees.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `deliveryMethods.amount`      | Required only for [PayPal lightbox with delivery methods](/payment-methods/paypal/web-component/express-checkout/?tab=how-advanced_2) | The cost of the delivery method, specified as an object:* `currency` as a three-character [ISO currency code](/development-resources/currency-codes#currency-codes?target=_blank).
* `value` in [minor units](/development-resources/currency-codes#minor-units?target=_blank).                                                                                                                                                                                                                                                                                                                                                                                                       |
| `deliveryMethods.description` | Required only for [PayPal lightbox with delivery methods](/payment-methods/paypal/web-component/express-checkout/?tab=how-advanced_2) | The description for the delivery method. This field is required by PayPal; however, the plugin allows you to configure shipping methods without a **Title** or **Label**. We recommend building fallback logic to ensure a meaningful value is always provided, and to avoid silent checkout failures. In our frontend implementation, we use the following fallback order:1) Shipping Method Title
2) Shipping Method Label
3) Shipping Method Carrier Code (as generated by the plugin)This ensures that the value is never empty, and uniquely identifies each shipping method for the shopper.The plugin automatically injects the Carrier Code into a blank `description` field. |
| `deliveryMethods.reference`   |                                                                                                                                       | Your reference for the delivery method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `deliveryMethods.selected`    |                                                                                                                                       | For [PayPal lightbox with delivery methods](/payment-methods/paypal/web-component/express-checkout/?tab=how-advanced_2), set to **true** for the delivery method that is selected. Only one delivery method can be selected at a time.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `deliveryMethods.type`        |                                                                                                                                       | The type of delivery method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

#### Guest shoppers

* POST `/V1/adyen/express/paypal-update-order/guest`

| Parameter                     | Required                                                                                                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |   |
| `amount`                      | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-")                                           | The updated final payment amount. This amount is the item total plus the shipping costs of the selected `deliveryMethod`, specified as an object:* `currency` as a three-character [ISO currency code](/development-resources/currency-codes#currency-codes?target=_blank).
* `value` in [minor units](/development-resources/currency-codes#minor-units?target=_blank).                                                                                                                                                                                                                                                                                                              |
| `paymentData`                 | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-")                                           | For the first request to this endpoint, this is the `paymentData` you receive when you made a request to [show the PayPal lightbox](#show-the-paypal-lightbox). In subsequent requests, this is the updated `paymentData` you receive in the response to this endpoint.                                                                                                                                                                                                                                                                                                                                                                                                               |
| `adyenCartId`                 | Required if `adyenMaskedQuoteId` is not included                                                                                      | The logged-in shopper's real cart ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `adyenMaskedQuoteId`          | Required if `adyenCartId` is not included                                                                                             | The quote initialized to mount the payment method component on the product detail page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `deliveryMethods`             | Required only for [PayPal lightbox with delivery methods](/payment-methods/paypal/web-component/express-checkout/?tab=how-advanced_2) | The array that lists the delivery methods available for the delivery address, and their fees.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `deliveryMethods.amount`      | Required only for [PayPal lightbox with delivery methods](/payment-methods/paypal/web-component/express-checkout/?tab=how-advanced_2) | The cost of the delivery method, specified as an object:* `currency` as a three-character [ISO currency code](/development-resources/currency-codes#currency-codes?target=_blank).
* `value` in [minor units](/development-resources/currency-codes#minor-units?target=_blank).                                                                                                                                                                                                                                                                                                                                                                                                       |
| `deliveryMethods.description` | Required only for [PayPal lightbox with delivery methods](/payment-methods/paypal/web-component/express-checkout/?tab=how-advanced_2) | The description for the delivery method. This field is required by PayPal; however, the plugin allows you to configure shipping methods without a **Title** or **Label**. We recommend building fallback logic to ensure a meaningful value is always provided, and to avoid silent checkout failures. In our frontend implementation, we use the following fallback order:1) Shipping Method Title
2) Shipping Method Label
3) Shipping Method Carrier Code (as generated by the plugin)This ensures that the value is never empty, and uniquely identifies each shipping method for the shopper.The plugin automatically injects the Carrier Code into a blank `description` field. |
| `deliveryMethods.reference`   |                                                                                                                                       | Your reference for the delivery method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `deliveryMethods.selected`    |                                                                                                                                       | For [PayPal lightbox with delivery methods](/payment-methods/paypal/web-component/express-checkout/?tab=how-advanced_2), set to **true** for the delivery method that is selected. Only one delivery method can be selected at a time.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `deliveryMethods.type`        |                                                                                                                                       | The type of delivery method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

When you make a request to one of these endpoints, we make a [/paypal/updateOrder](https://docs.adyen.com/api-explorer/Checkout/latest/post/paypal/updateOrder) request. You get an updated `paymentData` that you can use in your subsequent requests to update the PayPal order again.

Pass the updated object to the component:

```javascript
component.updatePaymentData(response.paymentData);
```

### Tab: GraphQL

Use the `adyenExpressPaypalUpdateOrder` mutation to update the PayPal order.

Create a data object to send in the mutation, that includes the following:

| Parameter                     | Required                                                                                                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |   |
| `amount`                      | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-")                                           | The updated final payment amount. This amount is the item total plus the shipping costs of the selected `deliveryMethod`, specified as an object:- `currency` as a three-character [ISO currency code](/development-resources/currency-codes#currency-codes?target=_blank).
- `value` in [minor units](/development-resources/currency-codes#minor-units?target=_blank).                                                                                                                                                                                                                                                                                                              |
| `paymentData`                 | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-")                                           | For the first request to this endpoint, this is the `paymentData` you receive when you made a request to [show the PayPal lightbox](#show-the-paypal-lightbox). In subsequent requests, this is the updated `paymentData` you receive in the `/V1/adyen/express/paypal-update-order/mine` response.                                                                                                                                                                                                                                                                                                                                                                                   |
| `adyenCartId`                 | Required if `adyenMaskedQuoteId` is not included                                                                                      | The logged-in shopper's real cart ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `adyenMaskedQuoteId`          | Required if `adyenCartId` is not included                                                                                             | The quote initialized to mount the payment method component on the product detail page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `deliveryMethods`             | Required only for [PayPal lightbox with delivery methods](/payment-methods/paypal/web-component/express-checkout/?tab=how-advanced_2) | The array that lists the delivery methods available for the delivery address, and their fees.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `deliveryMethods.amount`      | Required only for [PayPal lightbox with delivery methods](/payment-methods/paypal/web-component/express-checkout/?tab=how-advanced_2) | The cost of the delivery method, specified as an object:- `currency` as a three-character [ISO currency code](/development-resources/currency-codes#currency-codes?target=_blank).
- `value` in [minor units](/development-resources/currency-codes#minor-units?target=_blank).                                                                                                                                                                                                                                                                                                                                                                                                       |
| `deliveryMethods.description` | Required only for [PayPal lightbox with delivery methods](/payment-methods/paypal/web-component/express-checkout/?tab=how-advanced_2) | The description for the delivery method. This field is required by PayPal; however, the plugin allows you to configure shipping methods without a **Title** or **Label**. We recommend building fallback logic to ensure a meaningful value is always provided, and to avoid silent checkout failures. In our frontend implementation, we use the following fallback order:1) Shipping Method Title
2) Shipping Method Label
3) Shipping Method Carrier Code (as generated by the plugin)This ensures that the value is never empty, and uniquely identifies each shipping method for the shopper.The plugin automatically injects the Carrier Code into a blank `description` field. |
| `deliveryMethods.reference`   |                                                                                                                                       | Your reference for the delivery method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `deliveryMethods.selected`    |                                                                                                                                       | For [PayPal lightbox with delivery methods](/payment-methods/paypal/web-component/express-checkout/?tab=how-advanced_2), set to **true** for the delivery method that is selected. Only one delivery method can be selected at a time.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `deliveryMethods.type`        |                                                                                                                                       | The type of delivery method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

This mutation makes a [/paypal/updateOrder](https://docs.adyen.com/api-explorer/Checkout/latest/post/paypal/updateOrder) request. You get an updated `paymentData` that you can use in your subsequent requests to update the PayPal order again.

Pass the updated object to the component:

```javascript
component.updatePaymentData(response.paymentData);
```

## Testing

When you are done setting up your integration, test that the express checkout flow works as expected for the payment methods you support.

* For Apple Pay, use [Apple's test card numbers](/payment-methods/apple-pay/web-component#test-and-go-live).
* For Google Pay, use your [Google Pay wallet](/payment-methods/google-pay/web-component#test-and-go-live).
* For PayPal, use your [PayPal Sandbox account](/payment-methods/paypal/web-component#test-your-integration).

## See also

* [Adobe Commerce plugin](/plugins/adobe-commerce)
* [Adobe Commerce headless integration](/plugins/adobe-commerce/headless-integration)
* [Express checkout](/payment-methods/express-checkout)
