On this page we provide Adyen-specific information for building a Progressive Web Application (PWA) storefront. The PWA storefront works with a headless Adobe Commerce back-end that has the Adyen plugin installed and configured.
Two web APIs can be used to utilize the Adyen functionality:
- REST - This is the most widely used web API. All of the functionalities provided by the Adyen plugin can be accessed using this method.
- GraphQL - This is an alternative way to interact with web APIs. The Adyen plugin utilizes the
/graphql
endpoint exposed by the Adobe Commerce back-end and adds the functionality that is related to the plugin. All of the essential functionalities provided by the Adyen plugin can be accessed using this method. For more information, checkout the Adobe Commerce GraphQL documentation.GraphQL is only available with plugin version 8.2.0 or later.
Ecommerce checkout flow
With a headless Adobe Commerce back end, you build your own payment form for the Adobe Commerce PWA storefront. In the checkout flow, data passes from the PWA storefront through the Adobe Commerce back end to the Adyen API. Then, data passes back from the Adyen API through the Adobe Commerce back end to the PWA storefront. In the checkout flow, you need to do the following steps:
- Get the payment methods that are available on the Adyen platform, and for each of them determine the data that you need to collect.
- Collect shopper details by presenting the payment methods on your payment form. Then, when the shopper selects a payment method, present the fields to fill out or the options to choose from, and collect these details.
- Place the order.
- Check the payment status to see if you need to perform any extra steps before redirecting the user to the success page or showing an error message.
- Handle additional actions like redirecting the customer to the issue page for additional authentication, or presenting a QR code to complete the payment. If the payment fails, the following attempts will need to handle the additional actions as well
Before you begin
Before you start integrating a Adobe Commerce PWA storefront with the Adyen platform:
-
Make sure you have completed the steps to configure the Adobe Commerce back end:
- Set up the Adyen Customer Area.
- Set up the plugin in Adobe Commerce.
- Set up the payment methods in Adobe Commerce.
- Configured headless integration settings in Adobe Commerce.
- Get familiar with the front end components implementation. We suggest using the components to gather the payment related information in a secure way.
Setting up point of sale is not required for a PWA storefront.
-
From version 9.0.1 onwards, the plugin uses Adobe Commerce’s recommended authentication methods to authenticate requests coming from the front-end application. The endpoints use
self
resources for logged-in shoppers andanonymous
resources for guest shoppers.
Therefore, an integration token is no longer required. Customer token needs to be used asBearer Token
for logged-in shoppers. For guest shoppers, no token is required because a masked cart ID is used to authenticating their requests.
For more information on resource access, refer to Adobe Commerce documentation.
Step 1: Get available payment methods
In this step, the Adobe Commerce back end retrieves the available payment methods from the /paymentMethods API endpoint and adds some extra information that you will need for rendering the components on the front end.
To get the available payment methods and extra information:
- Make an API request to get the payment methods and data that you need to collect.
- Parse the API response to get a JSON object that contains the Adyen
/paymentMethods
response and required extra information.
1. Make an API request
If you are using REST, the endpoint differs per use case. If you are using GraphQL, the endpoint is /graphql
.
-
Guest shoppers (not logged-in)
- GET
/V1/guest-carts/{cartId}/payment-information
Alternatively, - POST
/V1/guest-carts/{cartId}/shipping-information
- GET
-
Logged-in shoppers
- GET
/V1/carts/mine/payment-information
Alternatively, - POST
/V1/carts/mine/shipping-information
- GET
Available payment methods and required extra information are added to the extension_attributes
of payment-information
and shipping-information
endpoints of Adobe Commerce as adyen_payment_methods_response
. The required extra information is relevant when collecting shopper details in Step 2.
The payment_methods
object in the response of payment-information
or shipping-information
endpoints is filtered and sorted according to the response of /paymentMethods endpoint.
2. Parse the API response
The Adobe Commerce back end receives a response from Adyen containing all available payment methods for the current session filtered by currency, amount, country, etc. For each payment method, the /paymentMethods response includes:
name
: Name of the payment method, which you can show to your shopper in your payments form.type
: Unique payment method code. Pass this back to indicate the shopper's selected payment method when you place an order.details
: Array that contains the required fields for the payment method.
The plugin also collects some extra information other than the /paymentMethods
response. This data is included in the response as the following fields:
icon {url, width, height}
: Payment method icon details.configuration
: Includes any extra payment method specific configuration that the checkout component should get on the front end which is not accessible from the/paymentMethods
details response.isOpenInvoice
(boolean): Indicates if the payment method is an open invoice payment method. Note that this field is deprecated and will be removed later.
- The REST endpoint's response contains payment methods as a JSON encoded string. Parse this string to get a JSON object. For example, using
JSON.parse();
.
After parsing the response, you get two root objects:
paymentMethodsResponse
: Includes the full and unmodified response object from the Adyen/paymentMethods
API endpoint.paymentMethodsExtraDetails
: Holds the extra information that the plugin gathered for each payment method that is available in thepaymentMethodsResponse
.
Example response after parsing
{
"paymentMethodsExtraDetails": {
"applepay": {
"icon": {
"url": "full url for icon",
"width": 1,
"height": 1
},
"configuration": {
"amount": {
"value": 1,
"currency": "currency ISO code like EUR"
}
}
},
"ideal": {
...
},
"klarna": {
...
},
"klarna_paynow": {
...
},
...
},
"paymentMethodsResponse": {
"paymentMethods": [
{
"details": [
{
"items": [
{
"id": "1121",
"name": "Test Issuer"
},
{
"id": "1154",
"name": "Test Issuer 5"
},
{
"id": "1153",
"name": "Test Issuer 4"
},
"..."
],
"key": "issuer",
"type": "select"
}
],
"name": "iDEAL",
"type": "ideal"
},
{
"brands": [
"mc",
"visa",
"maestro"
],
"details": [
{
"key": "number",
"type": "text"
},
{
"key": "expiryMonth",
"type": "text"
},
{
"key": "expiryYear",
"type": "text"
},
{
"key": "cvc",
"type": "text"
},
{
"key": "holderName",
"optional": true,
"type": "text"
}
],
"name": "Credit Card",
"type": "scheme"
},
{
"configuration": {
"intent": "capture",
"merchantId": "Merchant id"
},
"name": "PayPal",
"type": "paypal"
},
{
"name": "Pay later with Klarna.",
"type": "klarna"
},
{
"details": [
{
"key": "sepa.ownerName",
"type": "text"
},
{
"key": "sepa.ibanNumber",
"type": "text"
}
],
"name": "SEPA Direct Debit",
"type": "sepadirectdebit"
},
{
"configuration": {
"merchantId": "Merchant id",
"merchantName": "Merchant name"
},
"details": [
{
"key": "applepay.token",
"type": "applePayToken"
}
],
"name": "Apple Pay",
"type": "applepay"
},
...
}
}
}
Step 2: Collect shopper details
Next, present the available payment methods on your front end, and collect the shopper details that are required for the payment method selected by the shopper. To do so:
-
Use the
name
values from the /paymentMethods response to show all available payment methods to your shopper.If you need payment methods and issuer logos for your payment form, use the
paymentMethodsExtraDetails.icon
from the/payment-information
response as described in the previous step. -
After the shopper selects a payment method, render the input fields to get the required payment details. This can be done in two ways:
Rendering the input fields using our Drop-in or Components
We provide front end solutions that render and validate the necessary input fields:
-
Web Components
: Render individual payment methods anywhere on your website with our customizable UI components.
When you are implementing multiple payment methods on your PWA storefront we suggest that you pass the full
paymentMethodsResponse
object to the Web Component configuration. After creating the newAdyenCheckout
object you can loop through the methods and generate the components instead of doing it manually for each payment method. With this approach, you make sure that your integration can handle new payment methods that you enable in your Customer Area. - Web Drop-in : Render a list of available payment methods anywhere on your website with our pre-built UI.
Rendering the input fields manually
Use the details
array from the paymentMethodsResponse
for the selected payment method to determine what you need to collect from the shopper.
key
: Shopper detail you need to collect using your payments form.type
: Input type for collecting the payment detail from the shopper:
Type | Description |
---|---|
emailAddress | Email address. |
radio | Radio buttons showing the options specified within the items array. |
select | A list showing the options specified within the items array. Usually the options represent issuer (bank) names. Present each name in this array to the shopper. |
tel | Telephone number. |
text | Generic string. For "type": "scheme" , if you are fully PCI compliant you can alternatively collect and submit raw card data. See Collecting raw card data for more information. Otherwise, you need to generate encrypted card data using our custom card integration. |
If a payment method does not have a details
array, you do not need to collect any shopper details in your form. This usually means that the shopper must be redirected to another site to complete the payment.
Step 3: Place the order
After the customer has filled in their data, you can place the order. In this step, the storefront makes a request to the Adobe Commerce back end which then makes a payment request to the /payments endpoint.
To start the payment process, place the order from your front end in the way the default Adobe Commerce checkout flow requires:
- Create a data object to send in the Adobe Commerce API request.
- Place the order with the created object.
1. Create a data object
First, create a data object that you can later send in the Adobe Commerce /payment-information
Adobe Commerce 2 REST API request.
To get the necessary details for this object, you can do either of the two:
- Use
state.data
from the Web component. -
Replicate the request object yourself based on the documentation for the /payments endpoint. To replicate the object, follow this structure:
Parameter Required Description method
Payment method name in Adobe Commerce. For example, adyen_cc
,adyen_ideal
, oradyen_googlepay
.cc_type
If method
isadyen_cc
Card type.
Get the card type available in Adobe Commerce based on thestate.data.paymentMethod.brand
orstate.brand
. See example.
If you implement theonBrand
callback for the Web Component, then you can find it asstate.brand
. See example.brand_code
If method
is an alternative payment methodThe value of state.data.paymentMethod.type
field.recurringProcessingModel
The recurring processing model for the request, overwrites the default value in the plugin configuration. Set to Subscription, CardOnFile, UnscheduledCardOnFile depending on the recurring payment type you are making the request for. stateData
JSON.stringify() the state.data
object that you get from the Web Component or Drop-in. See example.
Thestate.data
object can be set in a separate request to accommodate special checkout flows.
2. Place an order
Place the order with the /payment-information
endpoint from the Adobe Commerce REST API. Use the object created in the previous step.
If you can't use the payment-information
endpoint to set state.data
, see setting the payment state.data
in a separate request.
For more information, refer to the Adobe Commerce API documentation.
The response contains orderId
in integer format that you need for the next step.
Setting the payment `state.data` in a separate request
Plugin version 7.2.0 and newer support setting the payment's state.data
by using the /V1/adyen/carts/mine/state-data
or /V1/adyen/guest-carts/:cartId/state-data
endpoint. This is useful for checkout flows where this information can't be sent using the /payment-information
Adobe Commerce REST API endpoint.
The /stateData
endpoint receives the following parameters:
Parameter | Description |
---|---|
state_data | state.data from the Web Component. |
quote_id | The ID of the Adobe Commerce quote related to state.data . |
state.data
saved with this endpoint is used in the payment request if no state.data
was supplied in the /payment-information
request.
Using this endpoint will persist payment data which can be useful for complex checkout flows, but could have implications for your integration's PCI scope. Reach out to our Support team for questions.
Step 4: Check payment status
To see if there are any additional steps required after placing the order, call the payment status endpoint:
-
Make a POST request:
- For logged-in shoppers, use the
/V1/adyen/orders/carts/mine/payment-status
endpoint. - For guest shoppers, use the
/V1/adyen/orders/guest-carts/{cartId}/payment-status
endpoint.
In the request body, include
orderId
that you received in the response from the/payment-information
endpoint in the previous step. See an example from our plugin's credit card method renderer. - For logged-in shoppers, use the
- Parse the JSON response and evaluate it. There are two paths that you can follow based on the
isFinal
response field.- The
isFinal
field is true:- If the
resultCode
field is Authorised or Received, the payment was successful and you can redirect the customer to the success page. - If the
resultCode
field is PresentToShopper, present the voucher or QR code to the shopper so they can complete the payment. - If the
resultCode
field is Refused, Error or unhandled, you receive a response containing an HTTP400
result code and a default Adobe Commerce localized error response. - If the
action
field is present and is not empty, then handle the additional action using the Web Component.
- If the
- The
isFinal
field is false:- The
action
field is present and is not empty, then handle the additional action using the Web Component.
- The
- The
Step 5: Handle additional actions
This step is only needed if the action
field is present and not empty in the response of the previous step.
Handle action
from the /payment-status
or /payment-details
response
Some payment methods require additional action from the shopper. For example, to scan a QR code, to authenticate a payment with 3D Secure, or to log in to their bank's website to complete the payment. To handle these additional front-end actions, follow the Web Components documentation or find specific documentation for each payment method in this list.
All payment methods use the createFromAction
method, except for PayPal. The PayPal Component uses the handleAction
method to process additional action from the PayPal pop-up window.
Optional: Validate the state.data
from the action component
In case the shopper is already redirected to the success page, you don't need to validate anything because the Component presents a QR code or additional information to the customer, and no additional steps are required from you. Adyen is going to send a notification to your system as soon as the customer finishes the payment.
The plugin handles webhooks on its own.
In case the shopper is still in the checkout process, you need to perform additional checks of the state.data
that you get back from the Component. To do this, implement the onAdditionalDetails
callback when creating the new AdyenCheckout
component.
To validate the state.data
:
- Use the
/V1/adyen/carts/mine/payments-details
endpoint for logged-in shoppers. - Use the
/V1/adyen/guest-carts/:cartId/payments-details
endpoint for guest shoppers.
Create your request
Create your request with the following field:
payload
: JSON.stringify() the object that you get from the action component in thestate.data
field.orderId
: TheorderId
you received in the response when you placed the order.
Example request:
{
"payload": "{\"details\":{\"threeDSResult\":\"eyJ0cmFuc1N..."}}",
"orderId": "175",
"cartId": "r8Mktr..."
}
Troubleshooting
When you get unexpected results, you can:
-
Check the endpoints on Adyen's GitHub as a starting point to see if there are any changes. In addition, check your /swagger where all the endpoints are listed.
-
Use our API Explorer to try out calls to the Adyen API endpoints and for example see what kind of errors you might get. Make sure you select the API version that the Adobe Commerce plugin uses. Check the library and API versions you are using.
Checking library and API versions
The Adobe Commerce plugin uses a specific version of the Adyen PHP library, which uses specific versions of the Adyen APIs. You can try out calls to the Adyen APIs in our API Explorer. The API Explorer is versioned, and you need to select the API version that your Adobe Commerce plugin version is using before trying calls.
To look up which PHP library and Adyen API versions you are using, refer to the release notes.
Alternatively:
- Go to the Adyen Adobe Commerce (formerly Magento 2) plugin on GitHub.
- In the Branch dropdown, on the Tags tab, select the version of your Adobe Commerce plugin.
- At
adyen/php-api-library
, find the version of the Adyen PHP library that the plugin uses. For example,"adyen/php-api-library": "~2.1"
. - Go to the Adyen PHP library.
- In the Branch dropdown, on the Tags tab, select the library version you've just found.
- Refer to the API constants to find the versions of the Adyen APIs that the PHP library uses, for example
const API_CHECKOUT_VERSION = "v41"
.