This section describes the classic integration with the Adyen payments platform. To know more about a newer integration, refer to the Checkout documentation instead.
Learn how to accept local payment methods (such as direct bank transfer, ewallets, or mobile payments) using the Directory Lookup integration.
With Directory Lookup, you can fetch the available payment methods from Adyen. In return, the Adyen payments platform responds with a list of cards and local payment methods supported for the specified payment amount in the current region.
Enable payment methods
Local payment methods vary per country or region.
To know which methods can be enabled for you, contact Support Team.
After selecting a payment method, the shopper is redirected to the payment method's page (for example, iDEAL or Sofort) and completes the payment.
Following any payment request, Adyen sends back a notification providing the status of the payment.
The flow of a payment using a local payment method is illustrated in the diagram below:
Before you begin
To process local payment methods, create a new skin and style the form to let your shopper select a payment method:
- Go to Customer Area > Account > Skins > Create a new skin .
- Add the skin description.
- Generate the HMAC keys for the test and live platforms (remember to take a note of this key) and click Save.
- Select the skin from the list and click Test from the menu bar to verify that Currently on Test displays the version information in green.
Step 1: Request local payment methods
To retrieve a list of available local payment methods make a POST request to the
directory.shtml endpoint with the fields in the code example. For Adyen to verify the authenticity of the request calculate the signature of the request and include this in the
The example below shows how to make such a request. For additional fields and more details for the payment methods request, refer to the API Reference.
All the fields mentioned in the request example (
countryCode, are mandatory.
We recommended that you provide the
countryCode field, to accurately state the actual location of the payment, so that the correct payment methods for that location are retrieved.
Step 2: Display local payment methods
The directory lookup returns the available payment methods for the shopper based on the country they are shopping from, the amount and currency and skin code you provided. The returned data is a JSON object containing an array with the payment methods. You can parse the response and provide the list of payment methods to your shopper.
A response returns a JSON object containing a list of applicable payment methods. Each payment method has a
brandCode, and optionally, a list of issuers (depending on the payment method). In this case, the
issuerId identifies a specific issuer and can be used to direct a shopper to the related method's webpage.
When parsing this response, you can format and display the methods according to your design if you like.
In case you made a directory lookup request to version 2 (https://test.adyen.com/hpp/directory/v2.shtml), each payment method also returns the
logos field containing links to normal, small, and tiny images.
Step 3: Submit a payment request
After your shopper selects the local payment method, make a POST request including the
issuerId (if available) of the selected payment method.
Recalculate the signature of your payment request with the
issuerId as extra fields and post the request to the
skipDetails.shtml endpoint. Your shopper is then redirected to the selected local method to finalize the payment.
Some payment methods restrict WebView in the app for security reasons. We recommend using the following if you want to display local payment method in your app:
- iOS: SFSafariViewController (https://developer.apple.com/reference/safariservices/sfsafariviewcontroller)
- Android: Chrome Custom Tabs (https://developer.chrome.com/multidevice/android/customtabs)
The HTML code below is an example form.
Step 4: Payment response
After shoppers have completed the payment, they are redirected to a result page of your choice. You can set a custom result URL in the Customer Area on the skin configuration page. Another option is to include the result URL in the
resURL field in the payment request.
Adyen appends parameters to this result URL to inform you about the payment status. If the status is already determined (either authorised or refused), you can use this information to display a payment successful or payment failed page. In a case when the current status is pending, use payment notifications to get the outcome of a payment request and store this result in your back office, if necessary.
An example of a redirect URL to a result page:
An example of a corresponding
To ensure that the response is not tampered with validate the response by calculating the signature of the returned fields, except the merchantSig field. Adyen uses your secret HMAC key to sign the data, so the calculated signature should be the same as the
merchantSig included in the response.
For more information on additional response fields, visit the API Reference.
Skip Hosted Payment Pages (HPP)
If you want, you can skip displaying the payment method selection page with the list of available payment methods returned by the directory lookup. You can route your shopper directly to the payment or order detail entry page.
To use this payment flow:
- Make a payment request call to skipDetails.shtml.
- In the call, include the
For more information on Skins and Hosted Payment Pages, see Skin.
Fields for this call vary per payment method, contact Support Team for more information.