Magento PWA storefront integration

Learn how to integrate a Magento PWA storefront with the Adyen platform.

On this page we provide Adyen-specific information you'll need when building a Progressive Web Application (PWA) storefront on top of a headless Magento 2 back end that has the Adyen plugin for Magento 2 installed and configured.

This page describes the integration steps up to and including version 4.5.4 of the plugin. For more information about the releases, refer to our releases notes on GitHub.

Ecommerce checkout flow

With a headless Magento 2 back end, you build your own payment form for the Magento PWA storefront. In the checkout flow, data pass from the PWA storefront, through the Magento back end, to an Adyen API. Then data pass back from the Adyen API, through the Magento 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: present 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.
Start the payment process.

When using a local payment method that requires additional actions, such as redirecting the shopper to their bank's website or app to complete the payment, the Magento back end will handle this.
When using a credit card, if applicable, handle the 3D Secure 2 authentication flow for the card payment.
Place the order.

The next sections explain these steps in more detail.

Before you begin

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

Make sure you have completed the procedures to configure the Magento 2 back end:
Setting up point of sale is not required for a PWA storefront.
Make sure you are using version 3.0.0 or higher of the Magento 2 plugin (see Mandatory plugin upgrade).

Step 1: Get available payment methods

In this step, the Magento 2 back end retrieves the available payment methods from the Adyen API endpoint /paymentMethods.
To determine the payment methods that are available to the shopper and the data that you need to collect:

Make a POST request to one of the following endpoints:
- If the shopper is a guest who has not logged in, use /V1/guest-carts/:cartId/retrieve-adyen-payment-methods and specify:
  - cartID: Your reference to the shopper's cart. Use this to retrieve the currency and value of the payable amount.
- If the shopper is logged in, use /V1/carts/mine/retrieve-adyen-payment-methods and specify:
  - cartID: Your reference to the shopper's cart. Use this to retrieve the currency and value of the payable amount.
  - shippingAddress: Optional object to specify shopper details. You can use this to retrieve the payment methods for the shopper's country, based on the two-character country code in shippingAddress.countryID.
Sample request to retrieve payment methods for a logged-in shopper
```
 {
   "cartId":"48",
   "shippingAddress":
     {
       "customerAddressId":"1",
       "countryId":"NL",
       "regionCode":null,
       "region":null,
       "customerId":"1",
       "street":["Neherkade 1 XI"],
       "telephone":"0612345678",
       "postcode":"2521VA",
       "city":"Gravenhage",
       "firstname":"Test",
       "lastname":"Test"
     }
 }
```
The request calls the getPaymentMethods method, which makes a POST request to the /paymentMethods endpoint.

The Magento back end receives a response from the Adyen API containing all available payment methods, or all payment methods available for the shopper's countryId. For each payment method, the /paymentMethods response includes:
- name: Name of the payment method, which you can display to your shopper in your payments form.
- type: Unique payment method code. Pass this back to indicate the shopper's chosen payment method when you make the payment.
- details: An array that contains the required fields for the payment method.
Partial /paymentMethods response
```
{
 "paymentMethods":[
   {
     "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"
   },
   {
     "details": [
       {
         "items": [
           {"id": "1",
            "name": "Allied Irish Bank},
           {...},                 
           {"id": "19",
            "name": "Bank of Ireland}
         ],
         "key": "issuer",
         "type": "select"
       }
     ],
     "name": "Online banking",
     "supportsRecurring": false,
     "type": "openbanking_UK"
   },
   {    ...
   }
 ]
}
```
Pass the response to your front end.

On our Github we have some examples of how we implement the interfaces. You can use these examples to check the parameters that we accept and to see the flow after submitting your request.

Example for a guest shopper: GuestAdyenPaymentMethodManagement.php.
Example for a logged-in shopper: AdyenPaymentMethodManagement.php.

Step 2: Collect shopper details

Now you need to present the available payment methods on your front end, and collect the shopper details that are required for the payment method that the shopper selects.

Use the name values from the /paymentMethods response to show all available payment methods to your shopper.

If you need payment method and issuer logos for your payment form, see Downloading logos for more information.

After the shopper selects a payment method, render the input fields to get the required payment details.

Use the details array from the /paymentMethods response 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 displaying the options specified within the `items` array.
select	A list displaying 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 PCI Level 1 or 2 certified 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 Component.

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.

On GitHub we have some examples of how you can implement this step. For example our credit card payment renderer and our hpp payment method renderer.

Step 3: Start payment process

In this step the Magento 2 back end makes a payment request to the Adyen API endpoint /payments.
To start the payment process:

Use the JSON.stringify() method to create a JSON string from the payload which consists of:

payload.method: The payment method that the shopper selected.
payload.addtional_data: The shopper details you collected.

Sample payload for a credit card payment before JSON-stringifying

{  
  "payload":{  
     "method":"adyen_cc",
     "additional_data":{  
        "cc_type":"VI",
        "number":"adyenjs_0_1_18$Koc9NbabvyEHXhAhl+8U...",
        "cvc":"adyenjs_0_1_18$XNBQfuz...",
        "expiryMonth":"adyenjs_0_1_18$h+p5PowYj1A...",
        "expiryYear":"adyenjs_0_1_18$B5H...",
        "holderName":"S. Hopper",
        "store_cc":false,
        "java_enabled":false,
        "screen_color_depth":24,
        "screen_width":1440,
        "screen_height":900,
        "timezone_offset":-120,
        "language":"en-US",
        "is_active_payment_token_enabler":true
     }
  }
}

Sample JSON-stringified payload for a credit card payment

{"payload":"{\"method\":\"adyen_cc\",\"additional_data\":{\"guestEmail\":null,\"cc_type\":\"VI\",\"number\":\"adyenjs_0_1_25...\",\"cvc\":\"adyenjs_0_1_25$TsfhJ...\",\"expiryMonth\":\"adyenjs_0_1_25$jneo+mG...\",\"expiryYear\":\"adyenjs_0_1_25$L...\",\"holderName\":\"Name test\",\"store_cc\":false,\"java_enabled\":false,\"screen_color_depth\":24,\"screen_width\":1440,\"screen_height\":900,\"timezone_offset\":-120,\"language\":\"en-US\"}}"}

Make a POST request to the /V1/adyen/payment endpoint, specifying the stringified payload.

Refer to our payment method renderers on GitHub for examples of how you can construct the request. For example, see the getCcData function in our credit card method renderer on GitHub.

See AdyenPaymentProcess.php on our Github for an example of how we implement the interface. You can use this example to check the parameters that we accept and to see the flow after submitting your request.

The request calls the initiate method, which makes a POST request to the /payments endpoint.

For card payments, verify if 3D Secure 2 authentication is required: Make a POST request to the V1/adyen/threeDS2Process endpoint, specifying the payload you received in the response to the /payments request.

For an example of how you can implement this, refer to the threeds2 model on our GitHub
Evaluate the response from the Magento 2 back end. For an example of how you can do that, refer to our credit card method renderer.
- If the response from the Magento back end contains threeDS2: false, no 3D Secure 2 authentication is required. Proceed to place the order.
- If the response from the Magento back end contains threeDS2: true, you need to redirect the shopper to complete 3D Secure 2 authentication. Proceed to step 4.
  The response will look like this:
```
[
"threeDS2": true,
"type": "TYPE",
"token": "TOKEN"
]
```
  The type indicates the authentication that is required:
  - type: IdentifyShopper means you need a device fingerprint from the issuer.
  - type: ChallengeShopper means the issuer requires some interaction from the shopper.

Step 4: Handle 3D Secure 2 for card payments

If you made a credit card payment request and received a response with threeDS2: true, you need to handle the 3D Secure 2 authentication flow. There are two ways to do this:

Use our 3D Secure 2 Component. This is the preferred method because it is easier to implement. These are some useful resources on our GitHub:
- Example of rendering the 3D Secure 2 Component.
- AdyenThreeDS2Process model: example of the class that handles the request where you provide the data provided by the callback.
- Example of validating the callback result.
Build your own 3D Secure 2 implementation. This method requires much more effort on your part.

To use our 3D Secure 2 Component, proceed as follows:

Use the 3D Secure 2 Component to get the device fingerprint for IdentifyShopper and/or to request a challenge result for ChallengeShopper.
You will receive a callback with the result.
If the callback result includes a device fingerprint:

a. Make a POST request to the /V1/adyen/threeDS2Process endpoint to submit the fingerprint:
```
  {  
     "payload":{  
         "details":{  
             "threeds2.fingerprint":"eyJ0aHJl..."
         },
         "paymentData":""
     }
  }
```
b. Validate the response to see if you can proceed to place the order or need to continue the 3D Secure 2 flow:
- If the response contains threeDS2: false, the device fingerprint was sufficient authentication. Proceed to place the order.
- If the response contains threeDS2: true and type: ChallengeShopper, further authentication is required. Request a challenge result from the card issuer.
```
{  
   "threeDS2":true,
   "type":"ChallengeShopper",
   "token":"eyJhY3NSZWZ..."
}
```
  Refer to our credit card method renderer on GitHub for an example of validating the response.
If the callback result includes a challenge result, make a POST request to the /V1/adyen/threeDS2Process endpoint to submit the challenge result:
```
{  
  "payload":{  
     "details":{  
        "threeds2.challengeResult":"eyJ0cmFuc1N0YXR1cyI6IlkifQ=="
     }
  }
}
```
You will not receive a response other than an HTTP response code. Proceed to place the order.

Step 5: Place order

When there are no more actions to perform for the 3D Secure 2 authentication flow, place the order.

Retrieving an origin key

To securely collect and encrypt sensitive cardholder data, and also to handle various other payment methods, the Adyen Magento 2 plugin requires an origin key for the base URL (the website domain) where the payment request comes from.

To get an origin key:

Make a GET request to the /V1/adyen/originKey endpoint.
Pass the origin key to the front end. In the Magento 2 plugin we show how you can do that.

Troubleshooting

When you get unexpected results, you can:

Use the endpoints on our GitHub as a starting point to check for any changes.
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 Magento 2 plugin uses.
Check the library and API versions you are using.

Endpoints

To know which endpoints are exposed to the Adyen plugin for Magento 2, see https://github.com/Adyen/adyen-magento2/blob/develop/etc/webapi.xml on our GitHub.

Checking library and API versions

The Magento 2 plugin uses a specific version of the Adyen PHP library, which in turn uses specific versions of the Adyen APIs. You can try out calls to the Adyen APIs in our API Explorer. This Explorer is versioned, so before trying a call you need to select the API version that your Magento 2 plugin version is using.

To look up which PHP library and Adyen API versions you are using:

Go to the Adyen Magento 2 plugin on GitHub (this will show the latest develop branch), and in the Branch dropdown, on the Tags tab, select the version of your Magento 2 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 and in the Branch dropdown, on the Tags tab, select the library version you 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".

Magento PWA storefront integration

Ecommerce checkout flow

Before you begin

Step 1: Get available payment methods

Sample request to retrieve payment methods for a logged-in shopper

Partial `/paymentMethods` response

Step 2: Collect shopper details

Step 3: Start payment process

Sample payload for a credit card payment before JSON-stringifying

Sample JSON-stringified payload for a credit card payment

Step 4: Handle 3D Secure 2 for card payments

Step 5: Place order

Retrieving an origin key

Troubleshooting

Endpoints

Checking library and API versions

See also

Magento PWA storefront integration

Ecommerce checkout flow

Before you begin

Step 1: Get available payment methods

Sample request to retrieve payment methods for a logged-in shopper

Partial /paymentMethods response

Step 2: Collect shopper details

Step 3: Start payment process

Sample payload for a credit card payment before JSON-stringifying

Sample JSON-stringified payload for a credit card payment

Step 4: Handle 3D Secure 2 for card payments

Step 5: Place order

Retrieving an origin key

Troubleshooting

Endpoints

Checking library and API versions

See also

Partial `/paymentMethods` response