Magento PWA storefront integration

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.

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:

1. Get the payment methods that are available on the Adyen platform, and for each of them determine the data that you need to collect.

2. Collect shopper details: 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.

3. Place the order.

   When using a card 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.

4. Check payment status
   You do this to see if you need to perform any extra steps before redirecting the user to the success page.

5. When using a credit card, if applicable, handle the 3D Secure 2 authentication flow for the card payment.

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:

  • Set up the Adyen Customer Area.
  • Set up the plugin in Magento.
  • Set up the payment methods in Magento.

  Setting up point of sale is not required for a PWA storefront.

• Make sure you are using version 6.0.0 or later of the Magento 2 plugin.

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:

1. 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 show 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 place the order.
   • 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",
        "type": "openbanking_UK"
      },
      {    ...
      }
    ]
   }

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

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

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

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

Step 3: Place the order

In this step the Magento 2 back end makes a payment request to the Adyen API endpoint /payments. To start the payment process, you need to place the order from your frontend in the way that the default Magento checkout flow requires:

1. Create the following data object that you can later send in the payment-information request.
   To get the necessary details, you can use the checkout component state.data and the threeDS2Utils library that are shipped with the Magento 2 plugin. For an example, see our credit card method renderer.

   {
      "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"
       }
   }

2. Use the data object to place the order using the payment-information endpoint from the Magento 2 REST API list. The response of the payment-information endpoint will contain the orderId in string format that you need in the next step.

Step 4: Check payment status

1. Make an API request to the /V1/adyen/orders/:orderId/payment-status endpoint. In the URL, use the order ID that you got back in the response from the payment-information endpoint when you placed the order in step 3. For an example of how you can do that, refer to our credit card method renderer.

2. Evaluate the response. 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. Redirect to the success page.

   • If the response from the Magento back end contains threeDS2: true, you need to handle the 3D Secure 2 authentication. Proceed to step 5.
     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 5: 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 using our 3D Secure 2 Component. 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.

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

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

2. If the callback result includes a device fingerprint:

   1. Make a POST request to the /V1/adyen/threeDS2Process endpoint to submit the fingerprint:

      {
       "payload":{
           "details":{
               "threeds2.fingerprint":"eyJ0aHJl..."
           },
           "paymentData":""
       }
      }

   2. 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. Redirect to the success page.

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

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

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:

1. Make a GET request to the /V1/adyen/originKey endpoint.
2. 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:

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

2. 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".

3. Go to the Adyen PHP library and in the Branch dropdown, on the Tags tab, select the library version you just found.

4. Refer to the API constants to find the versions of the Adyen APIs that the PHP library uses, for example const API_CHECKOUT_VERSION = "v41".

See also

• Magento 2 plugin
• Payment methods