Search

Are you looking for test card numbers?

Would you like to contact support?

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.

The instructions for ecommerce do not cover all payment methods explicitly. The focus is on online credit card payments.

Before you begin

Endpoints

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

Retrieve an origin key

To securely collect and encrypt sensitive cardholder data, the Adyen Magento 2 plugin uses the Checkout Card Component. This Component and the various payment method Components require 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.

Ecommerce checkout flow

With a headless Magento 2 back end, you build your own checkout for the Magento PWA storefront. In the checkout flow, data pass from the PWA front end, through the Magento back end, to an Adyen API; and back from the Adyen API, through the Magento back end, to the PWA storefront. In the checkout flow, you need to address the following steps:

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

  2. Present the available payment methods on your payments form and, when the shopper selects a payment method, present the shopper with the applicable fields to fill out, or options to choose from.

  3. Start the payment process.

    When using a local payment method that requires additional actions, such as redirecting the shopper to the website or app of their bank to complete the payment, the Magento back end will handle this.

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

  5. Place the order.

The next sections explain these steps in more detail.

Step 1: Retrieve payment methods

In this step, you let the Magento 2 back end retrieve the available payment methods from the Adyen API endpoint /paymentMethods. As you can see when you try out calls to this endpoint in our API Explorer, the required parameters are: merchantAccount, countryCode, currency and value of the payable amount, and optionally a shopperReference for one-click payments. You will need to write front-end code to accommodate this. In the API Explorer, don't forget to select the API version that the Magento 2 plugin uses.

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 that are available to the Magento 2 plugin:

    • 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 in the shopper's country. 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"
   },
   {    ...
   }
 ]
}
  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.

Step 2: Present payment methods

Now you need to present the available payment methods to the shopper 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.

    We also provide payment method and issuer logos that you can use on your payment form. See Downloading logos for details.

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

    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 you let the Magento 2 back end make a payment request to the Adyen API endpoint /payments. As you can see when you try out calls to this endpoint in our API Explorer, the required parameters are: amount.currency, amount.value, paymentMethod, and other parameters depending on the payment method and 3D Secure implementation. You will need to write front-end code to accommodate this. In the API Explorer, don't forget to select the API version that the Magento 2 plugin uses.

To start the payment process:

  1. Make a POST request to the /V1/adyen/payment endpoint, specifying:

    • payload.method: The payment method that the shopper selected.
    • payload.addtional_data: The shopper details you collected.
    • Other details required for the payment method and 3D Secure implementation.

    Sample request for a credit card payment

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

    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.

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

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

To use the Adyen Checkout Components for 3D Secure 2, proceed as follows:

  1. Use the Adyen Checkout Components to request 3D Secure 2 authentication: a device fingerprint for IdentifyShopper and/or an challenge result for ChallengeShopper.
    When this is finished, you receive a callback with the result.

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

  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. Proceed to place the order.

Step 5: Place order

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

Checking library and API versions

When troubleshooting unexpected results, you might want to check the library and API versions you are using.
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".