Express checkout

Integrate express payment methods for your headless Adobe Commerce integration.

Our express checkout module lets you implement express checkout for your headless Adobe Commerce integration.

The module supports express payments with Apple Pay, Google Pay, and 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. Web Components integrations for the express payment methods that you want to support.
Setup steps	Before you begin: Install the Adobe Commerce express checkout module. Implement express checkout for the express payment methods that you offer.

Headless integration types

Learn more

Find the GraphQL schema definition and the REST API implementation for express checkout on our GitHub.

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

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

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 that you need to use.

How it works

With a headless Adobe Commerce integration, you can use the Adyen Web Components 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:

Adobe Commerce initializes a quote for the order.
When the shopper enters their shipping address, present the available shipping methods.
When the shopper selects a shipping method, update the order with the shipping method.
The total payment amount may change depending on the shipping method the shopper selects, in such cases, handle the changes to the payment amount.
When the shopper selects the express payment button, the payment method components trigger an event.
Use the Adobe Commerce API to 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. Proceed to get the shopper's address and available shipping methods.
Product detail page: 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.

Logged-in shoppers

POST /V1/adyen/express/init/mine

Parameter	Required	Description
`productCartParams`		An instance of the `ProductCartParamsInterface` , 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.

Guest shoppers

POST /V1/adyen/express/init/guest

Parameter	Required	Description
`productCartParams`		An instance of the `ProductCartParamsInterface` , 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.

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.

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.

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.

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`		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`		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 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 response. Pass this from your server to the Component:
```
Copy code
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 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 calls the onShippingContactSelected event handler when the shopper selects their shipping contact.
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
- Guest shoppers
  - POST /V1/guest-carts/{cartId}/estimate-shipping-methods
Only if you support PayPal express, update the PayPal order 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.

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 calls the onShippingMethodSelected event handler when the shopper selects a shipping method.
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
- Guest shoppers
  - POST /V1/guest-carts/{cartId}/shipping-information
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.
Only if you support PayPal express, update the PayPal order 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.

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
- Guest shoppers
  - POST /V1/guest-carts/{cartId}/totals-information
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 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.
Product detail page: you must manually activate 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, 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.

Logged-in shoppers

POST /V1/adyen/express/activate/mine

Parameter	Required	Description
`adyenMaskedQuoteId`		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.
`adyenCartId`		The ID of the logged-in shopper's real cart.

Guest shoppers

POST /V1/adyen/express/activate/guest

Parameter	Required	Description
`adyenMaskedQuoteId`		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.
`currentMaskedQuoteId`		The ID of the guest shopper's real cart.

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 triggers the onAuthorized event. In this event, implement the steps to complete the payment.

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`	`/V1/guest-carts/{cartId}/billing-address`
Shipping information	`V1/carts/mine/shipping-information`	`/V1/guest-carts/{cartId}/shipping-information`

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

Logged-in shoppers
- POST /V1/carts/mine/payment-information
Guest shoppers
- POST /V1/guest-carts/{cartId}/payment-information

Refer to our headless integration documentation to learn more about placing an order with the REST API endpoints above.

Example request body for the /payment-information endpoint

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

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 on our GitHub.

If you initialized 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 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 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.

Logged-in shoppers

POST /V1/adyen/express/cancel/mine

Parameter	Required	Description
`adyenMaskedQuoteId`		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 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 endpoint.

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

The shopper initially enters their shipping address in the PayPal lightbox.
The shopper selects one of the delivery methods that are available.
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.

Logged-in shoppers

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

Parameter	Required	Description
`paymentData`		For the first request to this endpoint, this is the `paymentData` you receive when you made a request to 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`	Only for PayPal lightbox with delivery methods	The array that lists the delivery methods available for the delivery address and their fees. Use the `selected` field to specify the chosen delivery method by setting it to true.

Guest shoppers

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

Parameter	Required	Description
`paymentData`		For the first request to this endpoint, this is the `paymentData` you receive when you made a request to 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`	Only for PayPal lightbox with delivery methods	The array that lists the delivery methods available for the delivery address and their fees. Use the `selected` field to specify the chosen delivery method by setting it to true.

When you make a request to one of these endpoints, we make a /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:


Copy code
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.
For Google Pay, use your Google Pay wallet.
For PayPal, use your PayPal Sandbox account.

Express checkout

Requirements

Headless integration types

Learn more

How it works

Initialize a quote

Initialize a quote manually

Logged-in shoppers

Guest shoppers

Get the shopper's address and available shipping methods

Show the PayPal lightbox

Logged-in shoppers

Guest shoppers

Update the order with the selected shipping method

Handle payment amount changes

Complete the payment

Activate the cart manually

Logged-in shoppers

Guest shoppers

Place the order

Get the payment outcome

Handle abandoned carts

Logged-in shoppers

Guest shoppers

Updating PayPal orders

Logged-in shoppers

Guest shoppers

Testing

See also