HPP Manual

The Adyen Hosted Payment Pages (HPP) provide a flexible, secure and easy way for shoppers to purchase goods and services:

  • Shoppers go to your site, where they select and add the desired items to their shopping cart.
  • When they are ready to checkout to pay and finalize their order, they are redirected to the hosted payment page, where they enter the necessary details to complete the payment.
  • After submitting the payment information, they are redirected back to your web site, where they can land on a summary information page displaying the result of the payment.
  • You can style and customize the look and feel of the HPP using Adyen's skin technology and toolset to create a brand-consistent, seamless checkout experience for your shoppers.

You can choose among the following payment flows:

One-page payment flow

The one-page payment flow consolidates the payment process in a single page. It makes extensive use of JavaScript to manipulate and validate the page content. It is suitable for use with modern browsers and when page complexity is not an issue. Some presentation and validation occurs automatically. For example, the credit card logo is highlighted when the shopper enters the first digits of their card and if the card number is invalid, an error is displayed prior to payment submission.

To use this payment flow, you need to make a normal payment request call to pay.shtml.

Multi-page payment flow

The multi-page payment flow splits the payment process into two or discrete steps or more. It is lightweight and it does not require JavaScript. This ensures maximum compatibility with a wide range of browsers and devices, including mobile phones and PDAs.

To use this payment flow, you need to make a normal payment request call to select.shtml.

Directory lookup

Optionally, you may choose to host the payment selection on your website and skip the HPP part (directory lookup). Directory lookup enables you to directly show the entry fields for the selected payment methods to shoppers. It sends information such as the shopper location, shopping basket value and currency to the Adyen Payment Platform, which dynamically provides the list of the most relevant payment methods for this shopper to the merchant. By using this payment data, you can dynamically generate a customized payment page allowing the shopper to complete their purchase using a targeted selection of payment methods.  By selecting a payment method, the shopper is redirected to the local payment method check out of his choice, for example the shopper’s own bank iDEAL page, the shopper's own bank Suomen Verkumaksut page, PayPal page, etc. Following any payment request, Adyen sends back a notification providing the status of the payment and updates the status as soon as it changes. This means that our customers receive information about the status of the request in all cases.

To use this payment flow, you need to make a normal payment request call to directory.shtml.

Audience

This manual targets developers who integrate merchants' systems with the Adyen payment platform.

 

While integrating the Adyen platform of products and services with a third-party system, we strongly recommend you follow defensive programming best practices.
This means, for example, that system-automated decisions should have defaulted to non-delivery of products and services:
  • Your system should deliver products and services only after receiving an explicit authorisation response to a corresponding payment request.
  • Your system should not deliver any products or services when it does not receive any explicit response.

Feedback

We strive to provide you with clear, concise, and complete documentation. We are committed to improving it continuously to make it accessible and easy to understand.

We appreciate your comments, and we'd love to hear your voice: drop us a line and share your thoughts with us!

  Adyen Support Team

HPP last update

Version

Date

Changes

4.4 2016-14-06 Removed SHA-1.

Version

Date

Changes

4.4 2016-14-06 Removed SHA-1.
4.3.1 2016-17-06 Added new parameter for signature calculation for SHA 256.
4.3 2016-11-06 Restructured.
4.2.6 2016-11-02

Updated the Directory look up call for skip HPP.

4.2.5 2015-12-09

Added information about testing a chargeback in Error codes.

4.2.4 2015-11-28

Added information about payment reminder email in HPP payment request.

4.2.3 2015-11-13

Changed the code example for the directory lookup call.

4.2.2 2015-11-11
4.2.1 2015-10-15

Updated information about HMAC SHA 256.

4.2.0 2015-09-14

Introduced merchant-specific URL endpoints for API calls to provide improved security.

4.1.0 2015-06-29
  • HMAC SHA-256 generation in the Customer Area (CA).
  • HMAC SHA-256 calculation with autogenerated key.
  • DEPRECATED: HMAC SHA-1 calculation with user-generated key.
4.0.0 2015-05-12
  • Documentation migration from PDF to web-based online deliverable as main distributable asset.
  • Versioning: version reset and adoption of semantic versioning as per v. 4.0.0.
  • Manual redesign to improve readability, navigation, content findability.
2.02 2015-04-07

Added missing entry to currency table.

2.01 2015-03-11

Fixing some inconsistencies with notifications and links.

2.00 2015-01-17

Manual redesign

HPP endpoints

This is an overview of the test and live endpoint URLs to communicate with the Hosted Payment Page (HPP) solution.

This is an overview of the test endpoint URLs to communicate with the Hosted Payment Page (HPP) solution.

Adyen Customer Area
(CA)

https://ca-test.adyen.com/

Hosted Payment Pages
(Multiple)

https://test.adyen.com/hpp/select.shtml

Hosted Payment Pages
(Single)

https://test.adyen.com/hpp/pay.shtml

Hosted Payment Pages
(Details)

https://test.adyen.com/hpp/skipDetails.shtml

Directory Lookup

https://test.adyen.com/hpp/directory.shtml

This is an overview of the live endpoint URLs to communicate with the Hosted Payment Page (HPP) solution.

Adyen Customer Area
(CA)

https://ca-live.adyen.com/

Hosted Payment Pages
(Multiple)

https://live.adyen.com/hpp/select.shtml

Hosted Payment Pages
(Single)

https://live.adyen.com/hpp/pay.shtml

Hosted Payment Pages
(Details)

https://live.adyen.com/hpp/skipDetails.shtml

Directory Lookup

https://live.adyen.com/hpp/directory.shtml

Create a skin

Skin is an interface overlay that is applied to the Adyen Hosted Payment Page (HPP) to customise it according to your brand guidelines and create a seamless consumer checkout experience. The skin is comprised of a set of custom HTML/JavaScript fragments, images and CSS.

You may create multiple skins to accommodate testing requirements or to target a specific type of device or application, such as a mobile phone browser or point-of-sale terminal. 

The skin provides you with the ability to determine which payment methods are offered by default and in what order. Minimum and maximum transaction amounts per payment method, including a payment method-specific surcharge, can also be specified.

Skins are not restricted to a single merchant account - if you have multiple merchant accounts associated with your company account, you may use the same skin to process payments for each account. Likewise, you may have multiple skins processing payments for a single merchant account. Processing over multiple accounts is usually due to reconciliation or accounting requirements, which are not covered in this section.

Managing Skins In The Adyen CA

You can create, edit, upload, test, and publish your skins on the Skins tab in the Adyen Customer Area (CA).

The List tab identifies all the skins that have been created and are associated with the company or merchant account.

  1. Click the New tab and follow the instructions the Skin Configuration section. You may further customize the skin by manipulating the Skin files directly.
  2. You can edit a skin by clicking the skin code on the List tab. This displays the Edit skin configuration screen and populates the values that were entered when creating the Skin. The fields are editable; if a shared secret is set, the input field is masked showing “****” rather than clear text.
  3. After you have created a skin, you may download its files to edit them directly on your machine. For this, click the arrow pointing down in the Download column; the system displays the skin code, the description, and the file version for confirmation. Then click the Download button to proceed with the download.
  4. After you have modified the skin files and saved it in a ZIP file (see Editing The Skin Files), it may be uploaded to the TEST system where it is combined with the current skin settings.
  5. If a skin is no longer required, you may delete it; the system displays the skin code, the description, and the file version for confirmation. Click the Remove button to proceed.

Skin Configuration

A skin is identified by a unique combination of eight digits and letters known as the skin code. It is a system generated field; in the rare instance (for example when the randomly generated skin code contains an undesirable combination of characters) you may generate a new skin code by clicking the New tab again. Since a new skin is not saved until the Save Skin to Test button is clicked, you can safely repeat this a number of times.

When creating a skin you are prompted to specify the following skin properties. The details for the LIVE environment are required when publishing the skin to LIVE, but not for initial testing within the TEST environment.

  • Description: A description of your skin, which is useful to easily identify it (in case you have multiple skins).
  • Account(s): The merchant account(s), which should be able to process payments using this skin.
  • HMAC Keys: Specify the HMAC Key for each environment, the key is used to compute the merchant signature. The same Key cannot be used for both the TEST and LIVE environments.
  • Result URLs or Continue-to URLs: The Result URL is the URL where you host your payment result page. Customers are navigated to this address after they complete the payment. We append parameters to the Result URL to inform you of the status of the payment. Although not recommended it is possible to override the Result URL on a per-payment basis. If the value of the Result URL is not set, and if the resultURL parameter value is not passed with the Payment Request, the default Adyen result page is used to display the payment result. 
    The Continue-to URL is only applicable if you use the default Adyen result page to display the payment result to the customer. When the customer has seen the payment result, clicking the Continue button navigates them to this URL. 
    Note that the payment status parameters are not appended to the Continue-to URL.

Skin options

Click the Skin Options to reveal less commonly used skin options:

  • Use an inline frame for VbV and MSC 3-D Secure interaction: For 3D secure payments a 3D window is iframed within the HPP.
  • Use deprecated back-button behaviour: The standard behaviour, when the consumer clicks the previous button on the HPP, is to redirect the consumer to the resultURL with authResult=cancelled. This option performs the action browser minus 1, taking the consumer back to the previous page.
  • ShopperInteraction for this Skin: It is recommended that this option remains set to Unset, this will ensure that the system selects the correct shopper interaction to be used. In specific circumstances this setting may need to be changed. Contact our support for further information.
  • Support partial payments: Enable partial payment for gift cards. This means that a shopper can pay a part of the transaction amount with their giftcard, the remaining amount can be paid with the other payment method.
  • Billing Address Fields (AVS): Displays the billing address input fields on the HPP for credit card payments. These are used for AVS (address verification) in the UK, US and Canada if available. This data can be pre-populated.
  • Show extra costs/discount as: Adyen provides the ability to set a surcharge or discount per payment method. This option determines how the extra cost or discount is displayed on the payment method selection screen. Cost displays the extra cost (or discount) itself, e.g. "EUR 0.50 + 3.50%", or "3.50%". Value displays the calculated cost value, e.g. "EUR 4.50".
  • Break out of frame: While implementing an iFrame solution, while this is supported, note that not all payment methods support iFrames, an example is iDEAL.
    This setting provides you with 3 options:
    • Selecting No disables breaking out of iFrames.

    • Selecting Same window opens the redirect page in the same window.

    • Selecting New Popup results in the payment method redirect being opened within a popup screen. After the shopper completes the payment flow, the popup closes and the session continues within the iFrame.

The New Popup option is only available for a limited set of payment methods, contact our support for further information.

OneClick options

  • Use new OneClick layout: After enabling this option, the OneClick values display at the payment method itself, instead of at the top of the page. Note that not all payment methods currently support the OneClick functionality.
  • OneClick Configuration: Configure the payment methods to display Store details options to store the details for OneClick payments.

Airline specific options

 

  • Show airline data on payment pages: Displays the airline data fields on the HPP
  • Show airline fields on callcenter page: Displays the airline data fields on the callcenter page

POS specific options

Show POS fields on callcenter page: Displays the POS data fields on the callcenter page.

Extra options

Some extra options that you can configure:

Save the skin before applying the settings.

Payment Methods: Payment methods configuration gives you control over the payment methods to be displayed by default, the order in which they are displayed, the minimum/maximum amounts that you want to accept per payment method, and to charge a surcharge per payment method.

Custom Fields: Custom fields are a powerful feature of the payment pages that allow you to add form fields to the HPP. These is sent to you before final payment submission for approval; you may use this feature to capture any additional data or permissions that you may require, such as collecting shipping data, forcing the shopper to accept terms and conditions, or checking a validation code.

Any form field, whose name attribute is prefixed with "customfields", is considered to be a custom field. Custom fields are added as HTML to the page in an include file which is named customfields.txt (or a localised variant, e.g. customfields_NL.txt).

<table id="basetable">
   <tr>
       <td>
           <div class="fieldDiv">
              <input type="checkbox" name="customfields.subscribe" id="customfields.subscribe" value="true" CHECKED/>Next<br />
              <input type="name" name="customfields.email" id="customfields.email" value=""/> Email address<br />
           </div>
       </td>
   </tr>
</table>

The contents of the custom fields are sent as a SOAP Web Service request to a URL of your choice as configured using the Custom Fields link on the Edit Skin page. The following is a SOAP example of such request:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema -instance">
  <soap:Body>
    <check xmlns="http://customfields.services.adyen.com">
      <Request>
        <customFields>
          <CustomField>
             <name>subscribe</name>
             <value>true</value>
          </CustomField>
          <CustomField>
             <name>VAT</name>
             <value>NLXXXB01</value>
          </CustomField>
        </customFields>
        <merchantAccount>YourMerchantAccount</merchantAccount>
        <merchantReference>YourMerchantReference</merchantReference>   
         <sessionFields>
          <sessionField>
             <name>skinCode</name>
             <value>wjCP5yTj</value>
          </sessionField>
          <sessionField>
             <name>countryCode</name>
             <value>NL</value>
          </sessionField>
          <sessionField>
             <name>paymentAmount</name>
             <value>550</value>
          </sessionField>
          <sessionField>
             <name>currencyCode</name>
             <value>EUR</value>
          </sessionField>
          <sessionField>
             <name>shopperEmail</name>
             <value>test@test.com</value>
          </sessionField>
          <sessionField>
             <name>shopperReference</name>
             <value>user1234</value>
          </sessionField>
        </sessionFields>
      </Request>
    </check>
  </soap:Body>
</soap:Envelope>

If you respond with accepted the payment is allowed to continue. If not, you can specify which fields failed validation and the validation messages to display. If you need to store this data you must do so at this point, the data cannot be sent to you via the Notification server. The following is an example of a SOAP response:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.customfields.services.adyen.com">
  <SOAP-ENV:Body>
    <ns1:checkResponse>
      <ns1:response>
        <ns1:customFields/>
        <ns1:response>[accepted]</ns1:response>
        <ns1:sessionFields/>
      </ns1:response>
    </ns1:checkResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Download Skin: Navigates you to the Download Skin page.

Remove Skin: Navigates you to the Remove Skin page.

Edit Language Files:  Adyen Customer Area (CA) offers a visual interface to view and modify the text strings in the Adyen standard language set. Languages that are not part of the standard set can be added via the Skin resource file method.

With the Skin selected click the Edit Language Files link in the Extra Options section. A table is shown with the following fields:

  • Key: A unique identifier for the text string (e.g. button.continue).

  • Adyen default: The text string Adyen associates with the key (e.g. Continue).

  • Merchant default: The text string you associate with the key (if set); this overrides the Adyen default if set.

Set the merchant default value for each key you wish to change the text from the Adyen default. Click the Save button. It is important to ensure that you save every 5 minutes to avoid your session from timing out, resulting in a loss of any changes that have not been saved. Every time you click Save, a new version of the skin is created.

For the -default- language the res/resource.properties file in the Skin will be created/updated each time you save.

To edit another language, choose its shopper locale from the Language drop-down list. A table is shown with the following fields:

  • Key: A unique identifier for the text string (e.g. button.continue).

  • Adyen default: The text string Adyen associates with the key (e.g. Continue).

  • Adyen [language] (e.g. adyen nl): The text string Adyen associates with the key for the language chosen (e.g. Continue).

  • Merchant [language] (e.g. merchant nl): The text string you associate with the key for the language chosen (if set). This overrides the Adyen default if set.

For each language, you set merchant values for, a file called resources_[language].properties is created in the res directory of the skin. For example, if shopper locale nl is chosen, a file called resources_nl.properties in the res directory is created.

Language translations for new keys that Adyen introduces may not be immediately available in all languages.

After you have completed editing the text string be sure to download the latest version of the skin to your PC before making any further changes. This ensures you have the updated skin resource files.

Testing a skin

It is possible to send a payment request to the HPP directly from the Skin editor. This is a very useful tool to quickly test the correct operation of the skin and allows you to submit payments to the system prior to completing your integration with the HPP.

  1. Create a skin.
  2. Perform test transactions with the different payment methods you would like to offer your customers. These tests should be initiated from your web shop to our test platform.
  3. Test the modifications:
    • Cancellations
    • Captures (manually inclusive)
    • Refunds (partial amount and complete amount)
    • A subscription to a daily report has been enabled and reconciled. For example: Payment Accounting Report
  4. Successfully test notification for each of the following event codes:
    • AUTHORISATION
    • CANCELLATION
    • REPORT_AVAILABLE
    • CAPTURE
    • REFUND

Below are some recommendations that we would like you to keep in mind, to ensure a better experience using our services:

  1. The country code parameter is being sent in your payment requests. It forces showing payment methods for the related country, instead of detecting the country from the shopper's IP.
  2. The merchant reference is controlled on your side, avoiding re-using the same one for several payments.
  3. System messages have been configured for any user.

This page also shows you the versions of the Skin that are currently deployed on the TEST and LIVE HPP servers. There is always a delay between saving a skin or publishing it to the Live server. When the Latest Version value corresponds with the currently on Test or Currently on a live version, all the latest changes are deployed to that system.

The test functionality is also useful in debugging any problems you may have with your integration since it produces a complete payment setup form against which you can compare your implementation.

Editing The Skin Files

This chapter covers the basics of editing the Skin files you downloaded from the Adyen CA. Adyen provides a number of example Skins should you need a reference or starting point. If your requirements are not too complex, creating your Skin may simply consist of replacing a logo and one or two images.

Skin Files

As described previously, a Skin is comprised of a number of files that are uploaded in the Adyen CA as a ZIP archive with the following structure (assuming that the SkinCode of your Skin is 57Hw8sLg):

The contents of the ZIP file must exactly match the layout above; otherwise this ZIP file will not be accepted when uploading to the Adyen CA. File names and directory names are case-sensitive and, as a rule, extra subdirectories are not allowed and filenames should be composed of simple characters (specifically only characters in the range [a-z A-Z 0-9_-.])

Expected contents of each subdirectory:

  • css

    This directory contains the customised stylesheets which will be included in each page. The main stylesheet is screen.css which is valid for the media type “screen”. Optionally you can also supply a print.css to format a print version of the page. The optional screen_ie6.css file is included conditionally in Microsoft Internet Explorer version 6 or lower as a workaround for some non-standard interpretations of the CSS stylesheet standard. See HTML Skeleton for details on how the stylesheets are included in the pages.

  • img

    Any images referenced in the stylesheets or HTML include files can be uploaded via this directory. Filenames should be composed of simple characters.

  • inc

    You may provide custom HTML content such as menus, shop links, navigation, etc. This directory contains the HTML fragments that enable you to do so. If an included file is language-dependent, it is possible to supply an include for each language locale. For details of where these includes are inserted in the page, see HTML Skeleton.

  • res

    This directory contains files named resources_$localename.properties with text overrides for the text in payment pages. The main file is resources.properties which overrides the default string (language locale en_GB). For overriding a string in French you create file resources_fr.properties. The format of the resource files, as well as the allowed overrides, are described below.

  • js

    This directory contains the JavaScript code for the Skin. Any custom JavaScript should be added to the custom.js file which is included on each page.

Payment Detail Reminder Email

Refer the payment reminder email for more details about using and skinning.

Payment Page HTML Structure and Skeleton

A skin payment page has the following structure:

Payment page's HTML skeleton

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Page Title</title>
        <link rel="stylesheet" media="screen" type="text/css" href="/hpp/css/reset.css" />
        <link rel="stylesheet" media="screen" type="text/css" href="/sf/$SkinCode/css/screen.css" />
        <link rel="stylesheet" media="print"  type="text/css" href="/sf/$SkinCode/css/print.css" />
        <script type="text/javascript" src="/hpp/js/default.js"></script>
        <script type="text/javascript" src="/sf/$SkinCode/js/custom.js"></script>
    <!--[if lt IE 7]>
        <link rel="stylesheet" type="text/css" href="/sf/$SkinCode/css/screen_ie6.css" />
    <![endif]-->
</head>
<body>
    <!-- ### inc/cheader_[locale].txt or inc/cheader.txt (fallback) ### -->
    <form id="pageform" action="" method="post" onsubmit="return formValidate(this);">
    <script type="text/javascript">
    //<![CDATA[
    if (notNull(document.getElementById('pageform'))) {
        document.getElementById('pageform').setAttribute("autocomplete","off"); 
    }
    //]]>
    </script>
    <div id="content">
        <div id="pmcontent">
        <!-- ### inc/pmheader_[locale].txt or in/pmheader.txt (fallback) ### -->
        <div class="padDiv1"></div>

        <!-- ==================== -->
        <!-- Adyen Main Content  -->
        <!-- ==================== -->

        <div class="padDiv2"></div>
        <!-- ### inc/pmfooter_[locale].txt or inc/pmfooter.txt (fallback) ### -->
        <!-- ### inc/customfields_[locale].txt or inc/customfields.txt (fallback) ### -->
        </div>
    </div>
    <div id="foot">
        <div id="footc">
            <div id="nextstep">
                <div id="nextstepc">Next Step Text</div>
            </div>
            <div id="footerb1div">
              <input onclick="" type="submit" id="mainSubmit" value="continue" class="footerB nextB" />
            </div>
            <div id="footerb2div">
               <input onclick="" type="button" id="mainBack" value="previous" class="footerB backB" />
            </div>
        </div>
    </div>
    </form>
    <!-- ### inc/cfooter_[locale].txt or inc/cfooter.txt (fallback) ### -->
</body>
</html>

Getting the look right

The skin framework was designed to provide maximum flexibility when designing and creating your layout.

Payment page structure shows the HTML skeleton, which generates each page and indicates where each element of skin files is represented. However, when the default flow model is modified using a stylesheet virtually any layout can be created.

The “reset.css” stylesheet

If you examine the HTML in HTML Skeleton you will see that the first included stylesheet is reset.css. This stylesheet is always included to "nullify" the default HTML styling applied by the browser. Default styling can vary between browsers, so applying the reset.css stylesheet makes it much easier to create a layout which renders consistently across browsers.

@media screen {
    /* Don't forget to set a foreground and background color */
    /* on the 'html' or 'body' element! */
    html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,dd,dl,dt,li,ol,ul,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td
    {
        margin: 0;
        padding: 0;
        border: 0;
        font-weight: inherit;
        font-style: inherit;
        font-size: 100%;
        line-height: 1;
        font-family: inherit;
        text-align: left;
        vertical-align: baseline;
    }
    a img,:link img,:visited img {
        border: 0;
    }
    table {
        border-collapse: collapse;
        border-spacing: 0;
    }
    ol,ul {
        list-style: none;
    }
    q:before,q:after,blockquote:before,blockquote:after {
        content: "";
    }
}
@media print {
    .hideforprint {    display: none;}
}
/* Some Layout Shortcuts */
.r { text-align: right; }
.l { text-align: left; }
.fr { float: right; }
.fl { float: left; }
.b { font-weight: bold; }
.mid { vertical-align: middle; }
.red { color: #c00; }
You may notice that there are some simple stylesheet classes, which do not strictly belong in reset.css. This is purely an optimisation to reduce the number of requests to the server.

Getting Started With Customizations

When a skin is generated, the default settings render as follows:

After you have downloaded a skin, you can edit the files and directories to customize it. Here are some quick changes that you can easily implement.

Header image

  1. Save the header image that you want to use in the image directory of the skin files.

  2. Update the screen.css file to reference your header image.

    1. The latest version of the default skins have a HPP new style V2 section added to the screen.css file. Ensure to replace the #logoheader code in that section.

      # logoheader:
      { 
          height: 118px; 
          background: url("../img/<imageName>"); 
          background-position: left; 
          background-repeat: no-repeat; 
          background-color: white; 
      }

Payment method logos

  1. Save the logos you want to use in the img directory of the skin files.

  2. Update the screen.css file to override the .pmB element as shown:

    .pmB<paymentMethodName> 
    {
        background-image: url("../img/<imageName>"); 
        width: 400px; 
        height: 42px; 
        padding-left: 85px; 
        text-align: left; 
        margin-bottom: 6px; 
        font-size: 1.1em; 
        background-color: transparent !important; 
    }

Change font colors

Update the screen.css file to set the fonts you want to use:

html
{
    font-family: Arial, Helvetica, sans-serif; 
    font-size: 1.1em;
}

Change the Pay button

  1. Save the logos you want to use in the img directory of the skin files.

  2. Update the screen.css file to add the following line to the .paySubmit block:

    .paySubmit 
    {
        background: url("../img/<imageName>"); 
        background-repeat: no-repeat; 
        height: 16px; 
        width: 50px; 
        font-size: 0px; 
        border: 0px; 
    }

Automatically open the credit card payment option

  1. Open the cfooter.txt file that is saved in the inc folder of the skin files.

  2. Add the following script to the file and save:

    </div>
    <script type="text/javascript">
      if (collapsecard) {
        setTimeout(function() {
             show(collapsecard, 'completeCard.shtml', 'card', 'brandCodeUndef');
        }, 1000);
      }
    </script>

Custom Payment Methods

Adyen offers an option to display custom payment methods on your payment page. To configure your customer payment method, please contact the Adyen Support Team.

After the Support Team has configured your custom payment method, you can set a custom payment method button and a custom payment method name. A custom payment method's name will always start with "c_" (for example, "c_customPaymentMethod").

Button image

To change the button image that is displayed for a standard payment method or to add the image of your custom payment method, you must add the image file to the img directory of your skin. You will then need to add an extra style to your screen.css file. The syntax of this style is:

.pmB<paymentMethodName> { background-image: url("../img/<imageName>") !important; }

For example, if your custom payment method name is c_mycustomPayment and you have added an image file mycustomPayment.png to the img directory of your skin, the style that you should add to your screen.css file is:

.pmBc_mycustomPayment { background-image: url("../img/mycustomPayment.png") !important; }

Button name

The button name of your custom payment method must be added to the recources.properties file. If you require specific translations for different languages these may also be added to the resource files.

The syntax for the button name is:

pm.<payment method name>.buttonName=<Insert display name>

For example, if your custom payment method is c_mycustomPayment the entry in your resource file would be:

pm.c_mycustomPayment.buttonName=My Custom Payment Method Name

Custom favicon.ico

To override the default icon, which is displayed in the URL area when on the payment pages, place your favicon.ico file in the img directory of the skin. It will be picked up automatically by the payment pages.

If you don't have tools to create a custom favicon.ico file, you can generate one online at: http://www.favicon.cc/

Enabling Numeric Keyboard

While making a payment using a mobile or tablet device, the full keyboard is usually displayed to the shopper. To overcome this issue Adyen introduced a card.card_number_field_type field, which allows you to display only the numeric keyboard when the credit card field is selected by the shopper.

To integrate this field to your skin, follow these steps:

For a new skin

If you are adding a new skin, the resource key called in the resource.properties file is card.card_number_field_type. Ensure that the value of the card.card_number_field_type is tel.

If the value entered is an integer the input type also should be integer. After you have entered the values the numeric keypad on mobile devices, including tablets, is displayed.

For an existing skin

If you are using an old skin, it should be extended to use this feature. Add key and value in the resource.properties the card.card_number_field_type. 

Add the following CSS in the screen.css to hide the number controls for desktop:

input[type='tel'] {
    -moz-appearance:textfield;
}

input::-webkit-outer-spin-button,
input::-webkit-inner-spin-button {
    -webkit-appearance: none;
}

Creating and editing translations

You do not need to create a copy of a skin for every language you want to support – a single skin may contain translations for multiple languages and choose the appropriate string to display.

When a page is being loaded, the HPP searches for the string in the following order:

  1. skin resource files using the payment session locale res file (specified via the shopperLocale field).
  2. skin resource files using the default locale.
  3. default resource files using the payment session locale (via the Adyen CA).
  4. default resource files using the default locale (via the Adyen CA).

Supported languages

Adyen provides translations for some languages by default. Currently supported languages are listed below:

Language

ShopperLocale

Chinese – Traditional

zh

Czech

cz

Danish

da

Dutch

nl

English – British*

en_GB

English – Canadian

en_CA

English – US

en_US

Finnish

fi

French

fr

French – Belgian

fr_BE

French – Canadian

fr_CA

French – Swiss

fr_CH

Frisian

fy_NL

German

de

Greek

el

Hungarian

hu

Italian

it

Lithuanian

li

Norwegian

no

Polish

pl

Portuguese

pt

Russian

ru

Slovak

sk

Spanish

es

Swedish

sv

Thai

th

Turkish

tr

Ukrainian

uk

 British English is the default shopperLocale

Editing existing translations

You can edit translations for supported languages using the Adyen Customer Area. For this, do the following:

  • Select the desired skin on the List tab.
  • Then on the Edit skin configuration page locate Extra options and click Edit Language Files.
  • Choose the language, for which you need to add/edit translations:
  • After you finish editing the translations, click Save to apply the changes.

Adding translations for new languages

If you want to provide translations for a language, which is not supported by Adyen by default, we recommend that you use Customer Area for this.

Add a new language to a skin in Customer Area

In general, this process is similar to editing existing translations:

  • Select the desired skin on the List tab.
  • Then on the Edit skin configuration page locate Extra options and click Edit Language Files:
  • Specify a locale code for a new language and click add:
  • After you finish editing the translations, click Save to apply the changes.

Create a new resource file

Additionally, you can download skin files on your computer, manually add a skin resource file for a new language, and then upload the customized skin to the Customer Area.

Resource files for all languages are located in the res folder. The resources.properties file contains translations for the default locale (en_GB), while resource files containing translations for other locales have locale codes included into filenames (for example, resources_fr.properties for French and resources_en_US.properties for US English).

When creating a resource file for a new language, you can download this file, which is the resource file for the default locale, and add the locale code to the file name (for example, resources_ja.properties for Japanese). Then edit this file and specify new translations for all the values.

The resource files use the Latin 1 encoding (ISO 8859-1), but it is recommended that you treat them as US-ASCII only. This means that any character that is outside the US-ASCII set should be encoded in Unicode using the notation \u + UTF-16 code point. Thus “é” becomes “\u00e9” and “Ř” becomes “\u0158”.

MOTO Feature

Adyen's Mail Order / Telephone Order (MOTO) transactions are typically carried out offline: instead of entering payment details on an online web shop payment form, shoppers make a call to a call centre or send a coupon/voucher to communicate their credit card number. Thanks to Adyen's MOTO features, you can integrate your web shop payments with your call centre payments, and enjoy unified reporting covering both transaction flows.

By default, Adyen merchant accounts are set up for e-commerce for contractual reasons.

Contact your account manager or the Adyen Support Team to request enabling MOTO for your account.

Since MOTO transactions differ by nature from e-commerce transactions, different fees and rates may apply.

To process MOTO transactions, you need a dedicated Adyen merchant account under your company account, besides your e-commerce merchant account. The extra account is necessary because MOTO and e-commerce traffic flows are different, and therefore they require ad-hoc handling of operations and processes like flagging, supported payment methods or fraud control.

These are the basic requirements to enable MOTO:

  • Separate merchant account to handle MOTO traffic
  • Additional user permissions
  • Link to the call centre application
  • (Optional) Dedicated skin for the call centre application
  • Enable the Call Center user role in your merchant account or create a separate user account with Call Center user role rights to use the call centre.

Interfaces and integration

MOTO transactions can be accepted by using Adyen's Hosted Call Center Interface, available to all MOTO merchant accounts. This interface is similar to Adyen's Hosted Payment Pages (HPP) for e-commerce; the hosted call centre interface functionality is extended to include basic call centre features to allow your call centre representatives to log on and manually key in orders they receive via mail or phone.

You can modify the look and feel of this application by uploading a skin. Normally, this is the most efficient way to integrate.

Payment methods

The following payment methods are currently available for MOTO:

  • Credit cards
  • SEPA Direct Debit
  • Bank transfer
3D Secure authentication for credit cards is not available in the MOTO flow.

Adyen Hosted Call Center interface

You can reach the call center interface by following these URLs:

The interface consists of a login screen followed by a series of screens as shown below.

We will now discuss the various steps of a call center transaction.

Log in to the call center interface

When you visit the URL, you see the familiar Adyen login page:

 

Your employees should log on using your company account code. Only specific users should have access to this interface, namely call center representatives and administrative roles.

Enter order details

After a successful login, the following screen prompts the call center agent to enter the following information:

  • Merchant Account: the merchant account to use for this payment. If a user is assigned to one merchant account only, this field is not displayed.
  • Currency / Amount: the specified payment amount, with a decimal separator.
    For example, enter 100.00 for an amount of EUR 100.00.
    Japanese yen does not take minor units (so for example enter 1001 to specify an amount of 1001 yen).
    Currency options are available in a drop-down list that includes only the configured currencies for the selected merchant account.
  • Payment Reference the (merchant) reference for the payment.
    A reference to uniquely identify the payment. This reference is used in all communication with you about the payment status. We recommend using a unique value per payment; however, it is not a requirement.

    If you need to provide multiple references for a transaction, you can enter them in this field. Separate each reference value with a hyphen character ("-").

    This field has a length restriction: you can enter max. 80 characters.

  • Country Code: by default, the payment methods offered to the shopper are filtered based on the country the shopper's IP address is mapped to.
    For example, this prevents displaying a German payment method like Sofort to a UK shopper.
    This IP-to-country mapping is not 100% accurate; if you have already defined the country of the shopper, you may wish to set it explicitly.
  • Shopper Reference: a unique identifier for the shopper.
    For example, a customer ID in a shopping cart system.
    Recommended, as it is used in velocity fraud checks.
    This field is mandatory if the Store these details for recurring transactions checkbox is selected.
  • Email Address: the email address of the shopper. This field is mandatory if the Store these details for recurring transactions checkbox is selected.
  • Store these details for recurring transactions: if you select this checkbox, the payment details are stored for recurring payments.
    By default, the checkbox is selected.
    When the checkbox is selected, the Shopper Reference and Email Address fields become mandatory.

 

Airline data fields are displayed to be filled in, when applicable.
The information on this page can either be typed in manually, or automatically fed from another application, such as your internal ordering system (if it is web-based).

Payment pages

When you click Submit, you are directed to the payment method page. The available payment methods on this page, as well as other parameters like currency, amount and country vary, depending on your configuration.

 

Depending on the selected payment method, the regular payment screens are displayed. The call center agent can enter the payment details here, as instructed by the customer on the phone.

Sometimes, payment methods can be displayed that cannot be processed over the phone. To avoid this behaviour, you can create a skin and select for display only the appropriate payment methods.

Payment success or failure page

When a payment completes successfully, the Adyen-hosted success page is shown:

If any errors occur, the failure page is shown:

In the Adyen Customer Area (CA) you can retrieve a payment overview, payment status and payment details, as well as the MOTO user who submitted the payment.

The submit author is displayed on the payment detail page, on the row whose Item column value is set to Payment, under the the Created By column.

Extra request parameters

You can add extra parameters to the call center URL:

  • shopperLocale: A combination of language code and country code to specify the language used in the session.

    shopperLocale = language code + _ + country code

    For example, en_GB stands for for (British) English.
    When a country specification is not required, use only the language code. For example: fr, not fr_FR, for France.
    By default, the shopper locale is set to en_GB.
    This value is also forwarded to the first subsequent payment request.

  • currencyCode: defines the default currency for the transaction.
    The three-character ISO currency code.
  • paymentAmount: The payable amount that can be charged for the transaction, in minor units.
    The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

    paymentAmount is used only when the currencyCode is set as well.
  • currencies: a comma-separated list of the currencies that need to be available in the currency selection drop-down list.
    For example: currencies=EUR,GBP.
    Only the supported currencies in the currencies parameter are displayed.
    For example, if your account is not configured for USD, this currency is not displayed, even if you include it as a value in the currencies parameter.
    This value is also forwarded to the first subsequent payment request.

Call center skin

When you launch the call center application for the first time, a default skin is applied. You can override this setting by uploading your own skin. This is the same process as with e-commerce transactions. If you do not upload a skin, the Adyen default skin is used.

In the Adyen Customer Area (CA), define a Call Center Skin Code in the merchant settings page of the merchant account: go to Settings -> Merchant Settings:

The Result URL and the Continue-to URL of the call center application should be set as follows:

These settings make sure that the operator stays in the call center application after processing a transaction.

The call center interface uses the regular hosted payment pages (HPP), so you can benefit from their feature set.

The Show airline fields on callcenter page skin option can also be set if you plan to capture airline data.

Users and passwords

You need at least one user with call center user role rights and permissions. We recommend creating specific accounts for each call center agent. This way you can control access per employee and keep track of activities in the audit trail. You can find the audit trail in the Adyen Customer Area (CA), under Settings -> Audit Trail.

  • Select the Settings menu, and then the Users block.
  • Click the New tab to add a new user, or click on an existing user name.
  • Assign the CallCenter user role by clicking the checkbox in the + column.
  • Assign the relevant Associated (MOTO) Accounts by clicking on the checkbox on the + column.
  • Click the Save button to create the user or Update to update the information for an existing user.

Forced logout after inactivity

After 15 minutes of inactivity, users are logged out of the session, and they need to enter again their login details, except for the account name. This is a PCI requirement, the security standard Adyen adheres to.

A/B testing

To analyse and optimise the conversion rate, the Adyen HPPs support A/B testing. To create an A/B testing configuration:

  1. Click the Create new A/B testing configuration link on the List tab.
  2. Enter the Description and HMAC keys.
  3. Click the Create New A/B configuration on Test button. 
    The system generates a new wrapper skin Code and returns you to the List tab.

After you have created an A/B testing configuration, it must be updated to set the skins to use and the distribution of payment requests. Click the A/B testing configuration skin code to edit the settings as you would with a regular skin. From the Edit A/B testing configuration screen click Configure Distribution to configure how the shoppers are distributed between the different regular Skins.

The skin codes that are available are listed in the Deselected Skins column, select the Skin Codes that are to be used and click the --> arrow to move them to the Selected Skins column. You will note that as you add each Skin the percentage distribution appears to the right of the Skin Codes and a slide scale appears below it, so that you can adjust the distribution. There is a slider for each Skin.

Setting up a payment

When you want to use A/B testing use the Skin Code and HMAC key of the A/B testing configuration to set up a payment session. When the shopper reaches the HPP the Skin Code of the A/B testing configuration is randomly replaced by one of the Skins configured within it.

Complete a payment

Due to the Skin Code of the A/B testing configuration being replaced by one of the configured Skins, once the shopper reaches the HPP the remainder of the payment session will continue as if the regular Skin Code was submitted in the payment session request. As such, the Skin Code and HMAC key of the regular Skin will be used in the result URL.

View results

After running the A/B test for the necessary period of time you can view the results and start analysing them. This is done by navigating to the Reports menu, Conversion tab, and then selecting the Skin Comparison option in the Adyen CA.

Publishing the skin to live

If you are satisfied with the way the skin operates on the TEST system you can publish the skin to the LIVE system. The publish-to-live operation does not change any settings, it replicates the skin as it is on the TEST environment to the LIVE environment.

The skin contains shop-specific settings such as branding and payment method support. You can have multiple skins. You always create a skin on our test system, and then publish it to live. 

Ensure that the relevant fields in the Properties on Live Only have been populated and click the Save Skin to Test button.

To publish the skin:

  1. Ensure that the live HMAC secret is set up correctly in the skin.
  2. Login to the test Adyen Customer Area (CA).
  3. Go to Skins > (select your skin) > Publish.
  4. Click Publish to Live.
  5. A message Successfully copied the skin from Test to Live is displayed.

 

Change the URL from test to live

In your shopping environment you make a redirect to Adyen's HPP. For live this URL should be changed to:

Live customer area setup

  1. Login to the Adyen Customer Area (CA) with the credentials provided to you and go to Settings -> My User.
  2. Enter your current password.
    You are redirected to change your password.
  3. After entering a new password, click Save and navigate to Settings -> Notifications.
    The notification configuration is not automatically copied from test to live initially, so you have to enter a new notification configuration for live.
  4. Set the capture-delay to the correct value from Settings > Merchant Settings.
    If you set the value to Manual you have to submit a capture request yourself for each payment like card and elv payments. 

The HMAC Secret does not have to be changed as every skin includes a test as well as a live HMAC Secret.

Make a live payment to test the skin

After publishing the skin to live you are ready to make a first payment on live with the skin.

  1. Login to the test Adyen Customer Area (CA).
  2. Go to Skins > (select the same skin) > Test.
    Ensure that the skin version on live is the same as on test (this should be the case after publishing, however a delay of 5 to 10 minutes should be considered).
  3. Select the Live System radio button.
  4. Generate payment form and click Test Now.

The HPP is formatted according to your skin. You can make a payment which is processed on live.

Make a payment

Now it is time to make your first live payment. You can make a payment with a real credit card and see if the whole process functions correctly. Check if the payment is processed correctly in the shop environment and that you receive the Authorised notification. Furthermore lookup the payment in the live  Adyen Customer Area (CA) to check if all fraud settings and other payment details are right.

With credit card payments you can cancel transactions afterwards so that no actual funds are withdrawn from your card. If you want to make a full live payment cycle, however, capture the transaction and see it being settled and appearing on your credit card statement.
Some payment methods such as iDEAL do not offer a cancel operation. In this case money is always transferred from your bank account to your merchant account.

Enable live payments for all customers

If the payment is processed correctly you can enable the live payments for all your customers and you are live with Adyen.

Payment flow options

You can choose among the following payment flows:

One-page payment flow

The one-page payment flow consolidates the payment process in a single page. It makes extensive use of JavaScript to manipulate and validate the page content. It is suitable for use with modern browsers and when page complexity is not an issue. Some presentation and validation occurs automatically. For example, the credit card logo is highlighted when the shopper enters the first digits of their card and if the card number is invalid, an error is displayed prior to payment submission.

To use this payment flow, you need to make a normal payment request call to pay.shtml.

Multi-page payment flow

The multi-page payment flow splits the payment process into two or discrete steps or more. It is lightweight and it does not require JavaScript. This ensures maximum compatibility with a wide range of browsers and devices, including mobile phones and PDAs.

To use this payment flow, you need to make a normal payment request call to select.shtml.

Directory lookup

Optionally, you may choose to host the payment selection on your website and skip the HPP part (directory lookup). Directory lookup enables you to directly show the entry fields for the selected payment methods to shoppers. It sends information such as the shopper location, shopping basket value and currency to the Adyen Payment Platform, which dynamically provides the list of the most relevant payment methods for this shopper to the merchant. By using this payment data, you can dynamically generate a customized payment page allowing the shopper to complete their purchase using a targeted selection of payment methods.  By selecting a payment method, the shopper is redirected to the local payment method check out of his choice, for example the shopper’s own bank iDEAL page, the shopper's own bank Suomen Verkumaksut page, PayPal page, etc. Following any payment request, Adyen sends back a notification providing the status of the payment and updates the status as soon as it changes. This means that our customers receive information about the status of the request in all cases.

To use this payment flow, you need to make a normal payment request call to directory.shtml.

HPP payment request

Connect your web site to the HPP skin: 

  1. Set up a payment session for the shopper as a standard HTML form.
  2. Use this payment session to transfer the shopper to the HPP.
  3. To avoid tampering with payment session data, data traffic it is cryptographically signed using a shared secret

URL redirect vs form POST 

You can set up a payment session using a generated URL, for example for a browser redirect (HTTP status code 302). 

  • Not all browsers can handle long URLs. For example, Microsoft Internet Explorer cannot handle URLs that are longer than 2083 characters. It is your responsibility to ensure that this limit is not exceeded.
  • All parameters and their values should be URL-encoded using UTF-8 character encoding, as per W3C recommendation.

Use case:

A shopper makes an order for a total amount payable of GBP 100. The order reference in your backoffice is Internet order 12345.

The order details are:

  • Goods shipping date to the shopper: before or not later than October 20th, 2016.
  • Order summary information to display on the payment review page for the order: 1 digital camera.
  • Shopper's locale is British English.
  • The skin you want to use to style the HPP is 4aD37dJA.
  • The merchant account you are using is TestMerchant.
  • The order was placed before or on October 11th 2016, 10:30 am.
  • You want the payment offer to expire on October 11th 2016, 11:00 am.

Example

This example represents a complete payment session, based on the order details above.

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:


<!DOCTYPE html>
<html>
  <body>
    <form method="post" action="https://test.adyen.com/hpp/select.shtml" id="adyenForm" name="adyenForm" target="_parent">
      <input type="hidden" name="orderData" value="H4sIAAAAAAAAALMpSUzKSVVIzkksLrZVyk9RsuPlsikpApMZdi6pxclFmQUlmfl5Cjb6QAEFkGhgaWJeSWZJJZKQY25+aV4JRACoVR9qAoRMsTNUcMlMzyxJzFFwTsxNLUpU0Hg5e/fTrtkvVux5NnvH06UTn29pebKn8dnStY8bV2sCtaeAjE2BOatIyc4Qq6CBgYK7U4ACWA7TWpjKJCW7kHyg5diMwBBLUoAYrIfdbH1weNkBACLpJjE3AQAA">
      <input type="hidden" name="merchantSig" value="3iWDU/V5RMtdaiZC4YRIpoX9/v0=" />
      <input type="hidden" name="sessionValidity" value="2014-10-11T10:30:00Z" />
      <input type="hidden" name="shipBeforeDate" value="2014-10-20" />
      <input type="hidden" name="shopperLocale" value="en_GB" />
      <input type="hidden" name="merchantAccount" value="TestMerchant" />
      <input type="hidden" name="paymentAmount" value="10000" />
      <input type="hidden" name="currencyCode" value="GBP" />
      <input type="hidden" name="skinCode" value="4aD37dJA" />
      <input type="hidden" name="merchantReference" value="Internet order 12345" />
      <input type="hidden" name="shopperReference" value="test102@gmail.com" />
      <input type="hidden" name="recurringContract" value="RECURRING,ONECLICK" />
      <input type="hidden" name="shopperEmail" value="test102@gmail.com" />
      <input type="hidden" name="offset" value="0" />
      <input type="submit" value="Send" />
      <input type="reset" />
    </form>
  </body>
</html>

Directory lookup call

A directory lookup service retrieves a list with the available payment methods you can offer to the active shopper in the country they are carrying out the transaction from.

The first part of this payment flow is to make a POST to directory.shtml.

All the fields mentioned in the request example (currencyCode, merchantAccount, paymentAmount, skinCode, merchantReference, sessionValidity and merchantSig), except countryCode, are mandatory.

It is 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.

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:

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.

curl --data \
     'countryCode=DE&currencyCode=EUR&merchantAccount=TestMerchant&merchantReference=Test_directory_lookup&paymentAmount=2000&sessionValidity=2015-12-25T10%3A31%3A06Z&skinCode=sH9qpMyS&merchantSig=94AwPXSxs0ECicXi1UDdKEmdzHQ6rf7EF9CC%2FzUO5Tg%3D' \
     https://test.adyen.com/hpp/directory.shtml

{
   "paymentMethods":[
      {
         "brandCode":"ideal",
         "name":"iDEAL",
		 "logo":"https://live.adyen.com/hpp/img/pm/ideal_small.png",
         "issuers":[
            {
               "issuerId":"1121",
               "name":"Test Issuer"
            },
            {
               "issuerId":"1152",
               "name":"Test Issuer 3"
            },
            {
               "issuerId":"1151",
               "name":"Test Issuer 2"
            }
         ]
      },
      {
         "brandCode":"sepadirectdebit",
         "name":"SEPA Direct Debit",
		 "logo":"https://live.adyen.com/hpp/img/pm/sepadirectdebit_small.png"
      },
      {
         "brandCode":"moneybookers",
         "name":"Moneybookers",
		 "logo":"https://live.adyen.com/hpp/img/pm/moneybookers_small.png"
      },
      {
         "brandCode":"klarna",
         "name":"Klarna Invoice",
		 "logo":"https://live.adyen.com/hpp/img/pm/klarna_small.png"
      },
      {
         "brandCode":"afterpay_default",
         "name":"AfterPay Invoice",
		 "logo":"https://live.adyen.com/hpp/img/pm/afterpay_default_small.pngg"
      },
      {
         "brandCode":"boku",
         "name":"Boku",
		 "logo":"https://live.adyen.com/hpp/img/pm/boku_small.png"
      },
      {
         "brandCode":"paysafecard",
         "name":"Paysafecard",
		 "logo":"https://live.adyen.com/hpp/img/pm/paysafecard_small.png"
      },
      {
         "brandCode":"paypal",
         "name":"PayPal",
		 "logo":"https://live.adyen.com/hpp/img/pm/paypal_small.png"
      }
   ]
}

Skip 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 following additional parameters:
brandCode Required to define the payment method selection from the directory lookup response.
issuerId May be required, where applicable.

Request:

<html>
   <body>
      <form method="post" action="https://test.adyen.com/hpp/skipDetails.shtml" id="adyenForm" name="adyenForm" target="_parent">
         <input type="hidden" name="merchantSig" value="3iWDU/V5RMtdaiZC4YRIpoX9/v0=" />
         <input type="hidden" name="sessionValidity" value="2016-10-11T10:30:00Z" />
         <input type="hidden" name="shopperLocale" value="en_GB" />
         <input type="hidden" name="merchantAccount" value="TestMerchant" />
         <input type="hidden" name="paymentAmount" value="10000" />
         <input type="hidden" name="currencyCode" value="GBP" />
         <input type="hidden" name="skinCode" value="4aD37dJA" />
         <input type="hidden" name="merchantReference" value="Internet order 12345" />
         <input type="hidden" name="brandCode" value="ideal" />
         <input type="hidden" name="issuerId" value="1121" />
         <input type="submit" value="Send" />
         <input type="reset" />
      </form>
   </body>
</html>

Fields for this call vary per payment method, contact support for more information.


HPP payment fields

Name Type Required Description
merchantReference String (tick)
A reference to uniquely identify the payment. This reference is used in all communication with you about the payment status. We recommend using a unique value per payment; however, it is not a requirement.

If you need to provide multiple references for a transaction, you can enter them in this field. Separate each reference value with a hyphen character ("-").

This field has a length restriction: you can enter max. 80 characters.

paymentAmount

int
(long)

(tick)

The payable amount that can be charged for the transaction, in minor units.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

currencyCode String (tick)
The three-character ISO currency code.
shipBeforeDate String (tick)

The date within which the ordered goods or services need to be shipped or provided to the buyer.

This field is also used to set the expiration date of an offline payment like boletos, oxxo and 7 eleven.

skinCode String (tick)

A unique code to identify the skin you want to apply to the HPP in use to process the transaction.

Note:

  • You can skin your hosted payment page to make it consistent with your brand look and feel.
  • You can create multiple skins in your merchant account to provide tailored branding experiences to your shoppers.
merchantAccount String (tick)
The merchant account identifier you want to process the (transaction) request with.
shopperLocale String (error)
locale = language code + country code

It specifies the language to use during the transaction.

For example: en_GB sets the locale preferences to British English.

When it is not necessary to include the country-specific part, use only the language code.

For example: it instead of it_IT to set the locale preferences to Italian.

If not specified, the locale preference is set to  en_GB by default.

orderData String (error)

An HTML fragment containing the order details to display to the shopper on the payment review page, just before the shopper proceeds to the final order confirmation.

Data is compressed and encoded in the session to prevent data corruption, for example in case the locale is set to non-Latin character sets.

  • Compression: GZIP
  • Encoding: Base64
sessionValidity   (tick)

The payment deadline; the payment needs to occur within the specified time value.
This is especially useful for tickets and reservations, where you want to hold items for sale for a short, limited period of time.

merchantReturnData String (error)

This field value is appended as-is to the return URL when the shopper completes, or abandons, the payment process and is redirected to your web shop.

Typically, this field is used to hold and transmit a session ID.

Maximum allowed character length: 128 characters.

If by including merchantReturnData in a request causes it to exceed the allowed maximum size, the payment can fail.

merchantSig String (tick)
The signature in Base64 encoded format.

The signature is generated by concatenating the values of a number of the payment session fields, and by computing the HMAC using the shared secret, as configured in the skin.

countryCode String (error)

By default, the payment methods offered to a shopper are filtered based on the country the shopper's IP address is mapped to. In this way, shoppers are not offered payment methods that are not available in the country they are carrying out the transaction from.

This IP-to-country mapping is not 100% accurate, so if you have already established the country of the shopper, you can set it explicitly in the countryCode parameter.

The country value format needs to adhere to the ISO 3166-1 alpha-2 standard. An invalid country code results in a transaction/request rejection. You can look up country codes on the ISO web site.

This field may be required in a payment request call to directory.shtml to perform a directory lookup.

shopperEmail String (error)

The shopper's email address.

We recommend providing this information, as it is used in velocity fraud checks.

Depending on your integration this field may be mandatory for you, check with the Adyen Support Team.

shopperReference String (error)

A unique identifier for the shopper, for example a customer ID.

We recommend providing this information, as it is used in velocity fraud checks. and it is the key in recurring payments.

This field is mandatory in recurring payments.

allowedMethods String (error)

A comma-separated list of the allowed payment methods to filter the payment method options that would normally be available through the skinned HPP.
Only the listed payment methods are shown, if available; all other payment methods are ignored.
Spaces are not allowed.

If you do not include this optional parameter, the corresponding value in the  merchantSignature computation is an empty string.

blockedMethods String (error)

A comma-separated list of the not allowed payment methods to filter the payment method options that would normally be available through the skinned HPP.
The listed payment methods are not made available on the HPP.
Spaces are not allowed.

If you do not include this optional parameter, the corresponding value in the  merchantSignature computation is an empty string.

offset int (error) An integer value that adds up to the normal fraud score.
The value can be either a positive or negative integer.
brandCode String (error)

Defines the specific payment method used to process the payment.

This field is required in a payment request call to skipDetails.shtml to skip the payment method selection.

issuerId   (error)

Defines the specific issuer ID used to process the payment.

This field is required in a payment request call to skipDetails.shtml to skip the payment method selection.

shopperStatement String (error)

Set this field in your payment request if you want to include a variable shopper statement.

You can include placeholders for the references. For example:

  • ${reference} for the merchant reference
  • ${pspReference} for the psp reference.

Note:

  • Not all acquirers support dynamic shopper statements.
  • Maximum allowed character length: 135 characters
  • Allowed characters: a-zA-Z0-9.,-?|
  • If you set the shopperStatement field, it is included in the HMAC calculation.
  • Not supported for all payments methods, for further information contact support.
offerEmail String (error)

If offerEmail is set to prompt, an extra Pay by Email payment method is added to the available payment method list.

If the shopper selects this option, they receive an email with a link that they can use to complete the payment.

The sessionValidity time value determines the link validity.

resURL String (error)

Defines the result URL, i.e. the default result landing page shoppers are redirected to when they complete a payment on the HPP.

We recommend setting a fixed resultURL in the skin configuration.
However, sometimes it may be preferable to set the result URL on a per-payment basis: to override the resultURL value specified in the skin configuration, you need to set the result URL for the payment session with the resURL parameter.

metadata Class (error)

Metadata consists of entries, each of which include of key and value.

This field takes the following children:

  • Key
  • Value

Limitations:

  • Error "177", "Metadata size exceeds limit"
Key String (error)

Key for the information to be provided. Example: key = 'storeCountry'

Limitations:

Error "178", "Metadata key size exceeds limit"

value String (error)

Information value. Example: value = 'US'

Limitations:

Maximum length: 80 characters, value is truncated to 80 characters with '...' appended to it.

Example of a redirect URL to a result page:

http://yourSite.com/pRes.jsp

Example of a corresponding resultURL with appended URL query parameters:

http://yourSite.com/pRes.jsp?merchantReference=Internet%20order%2012345&skinCode=4aD37dJA&shopperLocale=en_GB&authResult=AUTHORISED&pspReference=1211992213193029&merchantSig=CPb2cObMxmIIE0khO8WhEYyKDJs%3D

<!-- Appended URL parameters:
* merchantReference = Internet order 12345
* skinCode = 4aD37dJA
* shopperLocale = en_GB
* authResult = AUTHORISED
* pspReference = 1211992213193029
* merchantSig = CPb2cObMxmIIE0khO8WhEYyKDJs%3D
 -->

Additional fields

Risk fields

Adyen's API for payment requests contains several optional fields that can be provided by the merchants. Some of these fields are quite important when the merchant uses several risk checks in the Risk System. We recommend the use of the following fields in order to use to its fullest the capabilities of Adyen's Risk system.

Fields Required Description

shopperEmail

(error)
shopperReference (error)
merchantReference (tick)

A unique identifier associated to a specific transaction. It is used in all communication to you regarding the status of the payment.

We recommend using a unique value per payment, but this is not a requirement.

deliveryAddress (error)

The address where the shopper is going to receive goods/services. Providing the following detailed information street, houseNumberOrName, city, postalCode, stateOrProvince, country.

Used in the following risk checks:

billingAddress (error)

The address where the shopper is going to receive the bill. Providing the following detailed information street, houseNumberOrName, city, postalCode, stateOrProvince, country.

Used in the following risk checks:

dfValue (error)

Information from the shopper's device and uses the combined value to identify the device of the shopper.

Used in the following risk checks:

shopper (error)

Shopper personal informational that includes shopper.firstName, shopper.lastName, shopper.infix, shopper.gender, shopper.dateOfBirthDayOfMonth, shopper.dateOfBirthMonth, shopper.dateOfBirthYear, shopper.telephoneNumber and shopper.socialSecurityNumber (only in countries where it is legal to collect).

Used in the following risk checks:

riskdata.deliveryMethod (error)

The method to deliver the goods to the shopper.

Used in the following risk checks:

riskdata.externalRiskScore (error)

Used only before authorisation and when external risk provider is used by merchant.

Used in the following risk checks:

deliveryDate (error)

The expected date of delivery or fulfilment of the goods/services to the shopper.

Used in the following risk checks

offset (error) An integer that is added to the final fraud score of all risk checks. The value can be either positive or negative.
merchantOrderReference (error) A reference that merchants can use to link multiple transactions to each other.
browserInfo (error) With the browser info data, we can determine if the device is mobile or not, which is used for device fingerprinting and other device logic.

Shopper information fields

Shopper details can be sent to Adyen. They can also be encrypted using a signature. These are the fields Adyen recognizes as shopper information:

Field Type Required Description
shopper.firstName String (tick) The shopper's first name.
shopper.infix String (tick)

The shopper infix.

shopper.lastName String (tick) The shopper's last name.
shopper.gender String (tick) The shopper's gender.
shopper.dateOfBirthDayOfMonth String (tick) The day of the month of the shopper's birth.
shopper.dateOfBirthMonth String (tick) The month of the shopper's birth.
shopper.dateOfBirthYear String (tick) The year of the shopper's birth.
shopper.telephoneNumber String (tick) The shopper's telephone number.
shopperType String (tick)

This field can be used if validation of the shopper fields is desired.

Possible values:

 

1 - unmodifiable / visible

2 - unmodifiable / invisible

Billing address and AVS

Address Verification Service (AVS) is a security feature that verifies the billing address of the card holder. It does so by comparing the numeric portions of the card holder's registered billing address to those entered by the shopper.

AVS is only supported on a limited set of acquiring connections and only for a limited set of countries:

  • Canada
  • United Kingdom
  • United States

AVS-supported card types:

  • Visa
  • MasterCard

American Express supports AVS as an additional fraud check in all countries that issue AmEx cards.

Enable AVS check

To enable AVS for an HPP skin, go to the skin configuration area:

  • Under Skin Options, check the Billing Address Fields (AVS).

This is a skin-specific setting, so you need to apply it to each skin you want to enable AVS for.

Billing address pre-population

You can choose to have the payment pages collect the billing address and/or pre-populate these values from your own system.

If you wish to pre-populate these fields, you can add them to the payment session using the following parameters:

Field Type Required Description
billingAddress.street String (tick) The street name.
billingAddress.houseNumberOrName String (tick) The house number (or name).
billingAddress.city String (tick) The city.
billingAddress.postalCode String (tick) The postal/zip code.
billingAddress.stateOrProvince String (tick) The state or province.
billingAddress.country String (tick)

The country code information of the billing address section.

The country value format needs to adhere to the ISO 3166-1 alpha-2 standard. An invalid country code results in a transaction/request rejection. You can look up country codes on the ISO web site.

billingAddressType String (tick)

You can specify the billingAddressType to define whether the shopper is allowed to view and/or modify these personal details.

The billingAddressType field is part of the merchantSignature, which is used to calculate the HMAC.

The billingAddressType can be:

  • Not supplied - modifiable / visible
  • 1 - unmodifiable / visible
  • 2 - unmodifiable / invisible

If you want the shopper to enter the billing address on the payment pages, you need to select the Billing Address Fields (AVS) checkbox on the skin edit page in the Adyen Customer Area (CA), without supplying a billingAddressType value. 

The billing address details are stored with the transaction. They are visible in the Adyen Customer Area (CA)  when either a billingAddressType value is provided, or when Billing Address Fields (AVS) is configured for a skin.


Partial payments

A flexible, secure and easy way to allow your customers to pay for your goods or services. When a shopper needs to pay to complete an order they are transferred from your site to the HPP where the customer performs the payment. The shopper is then directed back to your site along with the result of the payment. In some cases, you may wish for a shopper to pay the full payment amount via multiple payment methods. This is called partial payments: a single payment request that is paid via multiple payment methods. 

The first until the second-last partial payment can be one of the following payment methods: 

Payment Method

Value

Webshop Giftcard

webshopgiftcard

VVV Giftcard

vvvgiftcard

Other giftcards

-

The last partial payment must always be a payment method which has a direct/online result. Below a list of all supported payment methods: 

Payment Method

Value

Visa

visa

Master Card

mc

Amex

amex

iDEAL

ideal

SofortUberweisung

directEbanking

PayPal

paypal

Webshop Giftcard

webshopgiftcard

VVV Giftcard

vvvgiftcard

Payment methods like bank transfers are not supported as these do not have an online result.

Skin Settings

To enable partial payments, in the Skin Options drop-down, activate the Support partial payments option on the skin you use with Adyen via Adyen Customer Area (CA)


Finish by clicking the Save Skin to Test button.

Payment Selection

Before processing the first partial payment an order is created. Like a normal payment, this order has a unique pspReference. All partial payments are available in the Payment List as normal payments. The merchant reference for the partial payments of one order are the same.

After a partial payment the shopper is redirected back to the HPP to pay for the pending amount. The second payment can also be a partial payment of the amount that is pending. The sum of the payment amounts of the partial payments for one order should be the same as the total amount of the order (if all payments were successful).

There isn't any maximum number of partial payments for a single payment request.

You can add a custom Column Configuration in the Payment list. In this custom configuration, you can add the Order Reference column. This column contains the pspReference as submitted back in the ORDER_OPEN and the ORDER_CLOSED notifications.

Partial payments notifications

Open an order

If the first payment for your payment request is a partial payment, an order is created. This generates an ORDER_OPENED notification. The following fields are sent in this notification:

Field Required Description
live (tick) Boolean indicating if the notification originated from the Live payment system (TRUE) or from the Test payment system (FALSE).
eventCode (tick) The value ORDER_OPENED.
pspReference (tick) The reference we assigned to the order. This is guaranteed to be globally unique and is used when communicating with us about this payment.
merchantReference (tick) This reference you assigned to the order/ payment request.
merchantAccountCode (tick) The merchant account the order was created for.
eventDate (tick) The time the order was generated.
success (tick) Always true.
amount (tick) The amount of the order.

Authorize payments

For each payment you receive an AUTHORISATION notification with the merchantReference and pspReference numbers. In the case of multiple partial payments, you receive multiple AUTHORISATION notifications with the same merchantReference and pspReference numbers corresponding to each partial payment.

Close an order

After the full order amount is paid, you receive a ORDER_CLOSED notification. This notification has the same pspReference as you received in the ORDER_OPENED notification. The success value for this notification is true.

It is also possible that the last payment is refused or the browser is closed before the total order amount is paid. In this case, the order expires when the sessionValidity date/time has been met in the payment request, and you receive a ORDER_CLOSED notification, but with the success value set to false. All partial payments that were processed previously are automatically cancelled or refunded. For more details see the Adyen API Manual.

Test partial payments

Partial payments can be tested via the Adyen Test system:

  1. Activate partial payments on your skin, and wait until your skin is up to date on all Test systems.
  2. Create a normal payment request, for example, for EUR 10.00.
  3. Select one of the supported partial payment methods, for example, Plastix.
  4. Enter in the card details. The test details are available on our support website. 
    For Plastix it is; cardholder: <anything> card number: 4010100000000000000 pin: 73737. By specifying the cardholder name as 'balance EUR 100' you can force that the balance on the card is only EUR 1.00 (amount is specified in minor units).
  5. Select the option that you want to pay the rest of the payment amount with another payment method if there is not enough balance.
  6. After the payment is authorised you are redirected back to the Hosted Payment Page. You now do another partial payment or finalise the order by completing payment (in our example EUR 9.00).
  7. After the last payment is authorised you are redirected back to the result URL.

BACS Direct Debit HPP

The Bankers' Automated Clearing Services (BACS) is used for electronic processing of financial transactions within the UK.

Direct debits are protected by the Direct Debit Guarantee which provides safeguards to the shopper including:

  • An immediate money back guarantee from the bank in the event that an error is made in the payment of a Direct Debit.
  • A new advance notice in case the date or amount changes.
  • The right to cancel the Direct Debit Instruction at any time.
  • The money back guarantee is only applicable to erroneous direct debit payment. It cannot be used to in case of contractual disputes with the customer. The customer may change or cancel the direct debit at any time by contacting the bank, service user or merchant. In case of an error with a direct debit, the customers bank refund the shopper under the terms of the Direct Debit Guarantee via the indemnity claim process. Direct Debit indemnity claims are processed electronically from banks to the service users and must be settled within 14 working days.

Direct Debits may be returned as unpaid by the paying bank when:

  • The paying bank gives advice to the service user of a change of circumstances to the DDI (e.g. Instruction cancelled).
  • The payer disputes the due date, amount or frequency of a Direct Debit.
  • The paying bank is referring the collection back to the service user as a notification of non-payment e.g. ‘Refer to payer’.
  • The unpaid direct debits also include the returns for transactions that can not be collected, e.g. due to insufficient funds on the shopper's account. The customer's bank might charge an additional fee for unpaid direct debits to the payer. An unpaid Direct Debit is debited from a service user’s account within 3 working days after the entry day and booked as a chargeback accordingly with the reason code provided by the paying bank. Hence, Adyen expects utmost care of merchants using the BACS service to reduce the returned items. 

Transaction flow

BACS transactions are processed via the domestic GBP bank account held by Adyen. Adyen provides full reconciliation service and settles the transaction to the merchant's account accordingly.

Flow:

  1. The shopper initiates the original payment via the payment pages by providing account and address details.
  2. The address details can be provided in the payment request sent to Adyen so these don’t have to be provided on payment pages. The original payment can be submitted to Adyen as a recurring transaction so future direct debits can automatically be collected via the recurring payment API.
  3. The account details for the payments are validated to make sure that the bank branch is existing and the account number is valid for the bank sort code. As an additional service, payments can also be verified where the ownership of the bank account is confirmed via the account owner name and address details.
  4. AUDDIS submission: If the payment details are valid, a DDI is generated and submitted by Adyen via AUDDIS (AutomatedDirectDebitInstructionService) to send to the bank for registration.
  5. DDI confirmation and advance notice (Adjust the DDI setup/registration section)
  6. The payment is not authorized immediately. After receiving, the payment is booked as authorized and settled after the payment is confirmed by BACS. On completion of the payment session, a response is sent to the merchant, the merchant needs to send a confirmation that the DDI is setup, then the account is debited accordingly.
  7.  BACS submission: It typically takes several business days for the bank to register the DDI’s that have been submitted via AUDDIS. So, the actual direct debit to BACS is submitted with a delay. After the BACS file with direct debits is submitted to BACS, the payment enters a 3-day cycle before the amount is debited from the shopper’s account (day 1: Input day, day 2: Processing day and day 3: Entry day). 
  8. After the successful registration, the payment is authorized.
  9. After the Direct Debit Instruction is setup, the actual capture/collection of the payment is created and send to BACS.
  10. Settlement and Reconciliation: The payment is credited to the merchant on the same day as the collection is debited from the shopper's account and is reconciled accordingly. 

Refunds:

The merchant can submit a refund when they want to refund the payment to the shopper. Else, the refund with Adyen is linked to the original transaction, BACS processes the refund as a separate payment. For this reason, a possibility is that the transaction is refunded by the merchant and is returned by shopper via their bank accordingly.

  1. Chargebacks and amendments (ADD)
  2. As per the Direct Debit Guarantee BACS direct debit, payments can be returned. The payment can also be returned as unpaid by the banks. Several reasons that are sent with the chargeback to the merchant but the defend disputed/returned transactions process is not available.

API integration option for BACS comes with a risk, contact our support for further information.

Payment Response

After the shopper completes a payment, they are redirected to the merchant's website and a result URL based on merchant configuration is created.

A notification regarding the status of the transaction containing the following fields is sent to the merchant:

Name Type Returned by default Description
additionalData class (tick)

The additionalData object is a generic container that can hold extra fields.

It includes the following:

  • mandateID
  • sequenceType
  • dateOfSignature
  • serviceUserNumber

  • serviceUserName

mandateID

String (tick)

Reference for the DDI/Mandate (DirectDebitInstruction) which is submitted for registration to the debtor bank.

The MandateId should be communicated to the shopper and is used for the recurring direct debits.

sequenceType

String (tick)

The sequence type is visible to the shopper on thier statement. For BACS, first payment is flagged as 01-First direct debit payment while one-off and recurring payments are submitted as 17-Normal payment.

The sequence type is not reported for final payments.

dateOfSignature

String (tick)

Date Mandate is signed.

In case of a new payment, the date of the first transaction is considered.

In case of a recurring payment, the date of the initial transaction, and creation of the recurring contract is considered.

serviceUserNumber String (tick) Hard coded parameter.
serviceUserName String (tick) Hard coded parameter.
pspReference String (tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

resultCode String (tick)

The outcome of the payment. The possible values are:

  • Authorised
  • Refused
  • Received 

See HPP payment response for more information.

After the shopper completes a payment, they are redirected to the merchant's website and a result URL based on merchant configuration is created.

A notification regarding the status of the transaction containing the following fields is sent to the merchant:

The notification is sent by PAL/PSP or both.

Confirmation letter and Advance notice

The merchant should send a confirmation and advance notice to the shopper before the actual capture, for each payment, including the following values: 

Confirmation letter:

Value Description

Sort Code 

Initial digits of bank sort codes are allocated to settlement members of the banking industry in the United Kingdom.

These bank codes are used to route transfer between banks.

These numbers are six digits long, formatted into three pairs which are separated by hyphens.

Account name

Name of the account holder which can be a consumer or a business.

Account number Account number.
Service User Number

A service user number (SUN) is a unique six digit number that BACS uses to identify originating institutions. The service user number assigned to Adyen which is used for processing your BACS payments is 298288

 Service User Name  The service user name is the name of the originating institution and is displayed on the shopper’s/beneficiary’s bank statement. The service user name that is displayed against your BACS payments is Adyen Payments.
Reference (DDI) 

DDI reference (mandateId) is a reference related to the mandate/recurring contract.

The DDI reference from the service user is unique to the shopper and appears for all direct debits. Recurring payment contains the DDI reference was originally submitted with the initial transactions followed by a unique payment reference.

A six digit DDI reference is given in the statement and an eleven digit unique payment reference separated by a full-stop.

Advance notice:

In case of recurring contract.

Value Description

Amount to be debited

The amount that was submitted in the payment request to Adyen is debited.
Frequency

Recurring payments frequency where shopper's account is debited on a weekly, monthly or yearly basis. The shopper should be informed about the payment frequency related to the direct debit commitment.

Date to be debited

Shoppers should be informed about the upcoming debit from their account. The initial payment is debited within 5 business days as the DDI need to be registered with the bank first before the direct debit can be cleared.

Recurring payments are debited within 3 business days.

Advance notice period

Shoppers should be informed about the upcoming debit by providing the direct debit details at least 3 working days before the debit is cleared on the account.

Design of payment form

When designing your online payment form there are some mandatory requirements you need to be followed:

  • Two checkboxes to confirm that the shopper agrees with the amount to be debited, and the shopper is the only signatory required to authorize the direct debit in the provided account.
  • You need to show that Adyen Payments processes the direct debit and appears on their bank statement against the direct debit.  Adyen processes the direct debit using Service User Number 298288.
  • You must provide the e-mail, of your customer service, and telephone, local (GB) phone number, after the payment is accepted.

All these requirements are already available by default if you decided to use our HPP solution.

Bacs HPP notifications

We send notifications to keep you updated on the transaction status.

Pending

These notifications are sent out at the payment creation moment.

The pending notifications are not enabled by default, contact Adyen Support Team if you want to request this notification.

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "directdebit_GB.mandateId":"424544",
               "directdebit_GB.serviceUserNumber":"298288",
               "directdebit_GB.serviceUserName":"Adyen Payments",
               "directdebit_GB.sequenceType":"OneOff",
               "directdebit_GB.dateOfSignature":"2016-10-21"
            },
            "amount":{
               "currency":"GBP",
               "value":1000
            },
            "eventCode":"PENDING",
            "eventDate":"2016-10-21T11:34:15+02:00",
            "merchantAccountCode":"TestMerchant",
            "merchantReference":"TMRef1234",
            "paymentMethod":"directdebit_GB",
            "pspReference":"9914770424540842",
            "success":"true"
         }
      }
   ]
}

Authorise

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "directdebit_GB.mandateId":"424544",
               "directdebit_GB.serviceUserNumber":"298288",
               "directdebit_GB.serviceUserName":"Adyen Payments",
               "directdebit_GB.sequenceType":"OneOff",
               "directdebit_GB.dateOfSignature":"2016-10-21"
            },
            "amount":{
               "currency":"GBP",
               "value":1000
            },
            "eventCode":"AUTHORISATION",
            "eventDate":"2016-10-21T11:34:15+02:00",
            "merchantAccountCode":"TestMerchant",
            "merchantReference":"TMRef1234",
            "paymentMethod":"directdebit_GB",
            "pspReference":"9914770424540842",
            "success":"true"
         }
      }
   ]
}

ACH Direct Debit payments

ACH (Automated Clearing House)  direct debit is an increasingly popular form of payment and a cost-effective alternative to credit and debit cards in the United States.

Currency: USD.

Settlement time: Depending on a shopper's bank account, settlement time varies between 2-3 days.

ACH payments over Adyen HPP follows the payment flow outlined in this document. You can customize appearance of these pages and specify available payment methods using skins.

  1. On the payment selection page, a shopper should choose the ACH Direct Debit method.

  2. A shopper enters payment details, such as bank account information and the billing address.

  3. Clicks pay.

After the payment is successfully completed, a shopper is redirected to the result page.

Custom payment flow

If you have a shopper's billing information, you may skip initial payment pages and redirect a shopper directly to the confirmation page.  If you already have a shopper's bank account and billing address information, we recommend that you skip the payment details page and immediately proceed to Step 3 (ACH default payment flow). In this case a shopper will only need to review the payment details and click Pay, which provides better user experience and reduces the number of incomplete payment transactions.

To implement this custom payment flow:

Post a payment request directly to the  https://test.adyen.com/hpp/skipDetails.shtml endpoint with the following parameters.

http://test.adyen.com/hpp/skipDetails.shtml?ach.ownerName=Andrews&ach.bankCountryCode=US&ach.bankAccountNumber=4640348490&ach.bankLocationId=011000138&ach.billingAddress.street=Bakkerstraat&ach.billingAddress.houseNumberOrName=137&ach.billingAddress.postalCode=12010&ach.billingAddress.city=Amsterdam&ach.billingAddress.stateOrProvince=NY&ach.billingAddress.country=US&ach.acceptDirectDebit=true&sig={YOUR SIGNATURE}&merchantReference=TMRef1234&brandCode=ach&paymentAmount=8650&currencyCode=USD&shipBeforeDate=2016-08-30&skinCode=aF563qQs&merchantAccount=TestMerchant&sessionValidity=2016-08-24T14%3A22%3A22Z

For the complete list of parameters required for this call, refer to the API manual.

ACH default payment flow

ACH payments over Adyen HPP follows the payment flow outlined in this document. You can customize appearance of these pages and specify available payment methods using skins.

If you have a shopper's billing information, you may skip initial payment pages and redirect a shopper directly to the confirmation page. To learn more on this, refer to Custom payment flow.

  1. On the payment selection page, a shopper should choose the ACH Direct Debit method.

  2. Then a shopper must enter payment details, such as bank account information and the billing address.

    All these fields are mandatory.

  3. A shopper should review the payment details and click pay.

After the payment is succesfully completed, a shopper is redirected to a page confirming the payment was accepted.


ACH custom payment flow

If you already have a shopper's bank account and billing address information, we recommend that you skip the payment details page and immediately proceed to Step 3 (ACH default payment flow). In this case a shopper will only need to review the payment details and click Pay, which provides better user experience and reduces the number of incomplete payment transactions.

To implement this custom payment flow:

Post a payment request directly to the  https://test.adyen.com/hpp/skipDetails.shtml endpoint with the following parameters.

http://test.adyen.com/hpp/skipDetails.shtml?ach.ownerName=Andrews&ach.bankCountryCode=US&ach.bankAccountNumber=4640348490&ach.bankLocationId=011000138&ach.billingAddress.street=Bakkerstraat&ach.billingAddress.houseNumberOrName=137&ach.billingAddress.postalCode=12010&ach.billingAddress.city=Amsterdam&ach.billingAddress.stateOrProvince=NY&ach.billingAddress.country=US&ach.acceptDirectDebit=true&sig={YOUR SIGNATURE}&merchantReference=TMRef1234&brandCode=ach&paymentAmount=8650&currencyCode=USD&shipBeforeDate=2016-08-30&skinCode=aF563qQs&merchantAccount=TestMerchant&sessionValidity=2016-08-24T14%3A22%3A22Z

For the complete list of parameters required for this call, refer to the API manual.

One click payments

If a significant portion of your business consists of returning shoppers, you can use the CVC-only functionality of the Adyen payment system to store the card details used by shoppers. In this way, returning shoppers store a credit card details, and they can pay by filling in the stored card security code (CVC/CVV) before completing their order by confirming the purchase.

Set up the payment

The payment session is set up just like a regular payment, with the following differences:

  • Two optional fields in the standard payment session are compulsory for the CVC-only option.
  • The CVC-only payment session form includes one additional field.

One click specific fields

Field Type Required Description
shopperEmail String  (tick)
A shopper's email address.
shopperReference String  (tick)

A shopper's reference, which is the unique identifier for a shopper.

This is the only parameter used to uniquely identify shoppers. Therefore, make sure shoppers can securely log in to your site, and that they are not allowed to modify the value of the  shopperReference parameter.

recurringContract

 String (tick)  Used to define the type of recurring contract to be used. For CVC-only payments, its value needs to be set to ONECLICK.

<input type="hidden" name="shopperEmail" value="gras.shopper@somewhere.org" />
<input type="hidden" name="shopperReference" value="grasshopper52" />
<input type="hidden" name="recurringContract" value="ONECLICK" />

Payment opt-out

The initial purchase flow is the same as a normal payment, with the following exception:

  •   A checkbox is displayed on the HPP allowing the shopper to opt-out of having their details stored.

If the shopper does not opt out during the initial purchase, during subsequent payments they see an image representing their credit card with a blank field underneath, where they need to enter their card security code (CVC/CVV).

HPP payments with airline data

It is possible to provide airline and/or lodging information in your payment requests to our Hosted Payment Pages.

If you are using the new SHA-256 HMAC signature calculation method, all you need to do is to simply include the relevant airline/lodging fields in the payment request (see code example below).

If you wish to submit different airline/lodging data in your captures and refunds for payments submitted via the HPP, you will need to do that via API. See Airline specific information for more information.

Parent Child
airline  












agency_invoice_number

agency_plan_name

airline_code

customer_reference_number

boarding_fee

passenger_name

ticket_issue_address

ticket_number

travel_agency_code

travel_agency_name
flight_date
airline_designator_code

passenger

leg

airline.passenger  
 

first_name

last_name

traveller_type

date_of_birth
phone_number
airline.leg  
 

carrier_code

class_of_travel

date_of_travel

depart_airport

depart_tax

destination_code

fare_base_code

flight_number

stop_over_code

Airline fields

Parent container object for airline data fields: airline

Name Type Required Description Notes
passenger_name
String (error)

Passenger name, initials and title name.

  • Format: last name + first name or initials + title
    Example: EARHART/AMELIA MARY MS.
  • minLength: 1
  • maxLength: 49
customer_reference_number String (error)

Reference number; alphanumeric.

  • minLength: 0
  • maxLength: 20
ticket_issue_address String (error) Addres of the place/agency that issued the ticket.
  • minLength: 0
  • maxLength: 16
airline_code String (error)

IATA 3-digit accounting code (PAX); numeric.

It identifies the carrier.

  • Format: IATA 3-digit accounting code (PAX)
    Example.: KLM = 074
  • minLength: 3
  • maxLength: 3
airline_designator_code String (error)

IATA 2-letter accounting code (PAX); alphabetical.

It identifies the carrier.
  • Format: IATA 2-letter airline code
    Example.: KLM = KL
  • minLength: 2
  • maxLength: 2
ticket_number String (error) The ticket's unique identifier.
  • minLength: 1
  • maxLength: 150
travel_agency_code String (error)

IATA number, also ARC number or ARC/IATA number.

Unique identifier number for travel agencies.

  • minLength: 1
  • maxLength: 8
travel_agency_name String (error) The name of the travel agency.
  • minLength: 1
  • maxLength: 25
agency_plan_name String (error) 2-letter agency plan identifier; alphabetical.
  • minLength: 2
  • maxLength: 2
agency_invoice_number String (error) Reference number for the invoice, issued by the agency.
  • minLength: 1
  • maxLength: 6
flight_date String (error)

Flight departure date.

Local time (HH:mm) is optonal.

  • Date format: yyyy-MM-dd
  • Date and time format: yyyy-MM-dd HH:mm
  • minLength: 10
  • maxLength: 16
boarding_fee String (error)

Chargeable amount for boarding the plane.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

  • minLength: 1
  • maxLength: 18

Airline leg fields

Parent container object for airline leg data fields: airline.leg<legNr.>

Name Type Required Description Notes
depart_airport String (error)

Alphabetical identifier of the departure airport.
This field is required/mandatory if the airline data includes leg details.

  • Format: IATA 3-letter airport code.
    Example: Amsterdam = AMS
  • minLength: 3
  • maxLength: 3
flight_number String (error) The flight identifier.
  • minLength: 1
  • maxLength: 5
carrier_code String (error)

IATA 2-letter accounting code (PAX); alphabetical.
It identifies the carrier.
This field is required/mandatory if the airline data includes leg details.

  • Format: IATA 2-letter airline code
    Example.: KLM = KL
  • minLength: 2
  • maxLength: 2
fare_base_code String (error) Fare basis code; alphanumeric.
  • minLength: 1
  • maxLength: 7
class_of_travel String (error)

1-letter travel class identifier; alphabetical.

There is no standard; however, the following codes are used rather consistently:

  • F: first class
  • J: business class
  • Y: economy class
  • W: premium economy
  • minLength: 1
  • maxLength: 1
stop_over_code String (error)

1-letter code that indicates whether the passenger is entitled to make a stopover.

Only two types of characters are allowed:

  • O: Stopover allowed
  • X: Stopover not allowed
  • minLength: 1
  • maxLength: 1
destination_code String (error)

Alphabetical identifier of the destination/arrival airport.
This field is required/mandatory if the airline data includes leg details.

  • Format: IATA 3-letter airport code.
    Example: Amsterdam = AMS
  • minLength: 3
  • maxLength: 3
date_of_travel

String

(error) Date and time of travel.
ISO 8601-compliant.
  • Format: yyyy-MM-dd HH:mm
  • minLength: 16
  • maxLength: 16
depart_tax

String

(error)

Departure tax. Amount charged by a country to an individual upon their leaving.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

  • minLength: 1
  • maxLength: 12

Airline passenger fields

Parent container object for airline passenger data fields: airline.passenger<passengerNr.>

Name Type Required Description Notes
first_name String (error)

Passenger first name/given name.
This field is required/mandatory if the airline data includes passenger details.

This field does not have a max. character length constraint. However:
  • passenger_name cannot be longer than 49 character.
  • Most acquirers truncate this field at ~40 characters, sometimes even at ~30 characters.

Therefore, it's advisable to keep this field length within the recommended maxLength value.

  • minLength: 1
  • maxLength: ~20
last_name String (error)

Passenger last name/family name.
This field is required/mandatory if the airline data includes passenger details.

This field does not have a max. character length constraint. However:
  • passenger_name cannot be longer than 49 character.
  • Most acquirers truncate this field at ~40 characters, sometimes even at ~30 characters.

Therefore, it's advisable to keep this field length within the recommended maxLength value.

  • minLength: 1
  • maxLength: ~20
traveller_type String (error)

Passenger type code (PTC).

IATA PTC values are 3-letter alphabetical. Example: ADT, SRC, CNN, INS.

However, several carriers use non-standard codes that can be up to 5 alphanumeric characters.

  • minLength: 3
  • maxLength: 6
telephone_number String (error) Telephone number of the passenger, including country code. This is an alphanumeric field that can include the '+' and '-' signs.
  • minLength: 3
  • maxLength: 30
date_of_birth String (error) Date of birth of the passenger.
  • Date format: yyyy-MM-dd
  • minLength: 10
  • maxLength: 10

Code example

Below is a code example for submitting airline data in the authorisation via the Adyen Hosted Pages:

HPP via travel data (PHP)

<?php    /*
     This PHP code provides a payment form for the Adyen Hosted Payment Pages
     */
     
    /*
     account details
     $skinCode:        the skin to be used
     $merchantAccount: the merchant account we want to process this payment with.
     $sharedSecret:    the shared HMAC key.
     */
     
    $skinCode        = "[skin code e.g. GBIMwmE4]";
    $merchantAccount = "[merchant Account e.g. TestCompanyCOM]";
    $hmacKey         = "[HMAC key e.g. D21EB2ASD44BA234C8A0AF13CF0BCACA3D4727C6162630D712C857124B213270]";
     
     
    /*
     payment-specific details
     */
     
    $params = array(
                    "merchantReference" => "SKINTEST-1435226439255",
                    "merchantAccount"   =>  $merchantAccount,
                    "currencyCode"      => "EUR",
                    "paymentAmount"     => "199",
                    "sessionValidity"   => "2015-12-25T10:31:06Z",
                    "shipBeforeDate"    => "2015-07-01",
                    "shopperLocale"     => "en_GB",
                    "skinCode"          => $skinCode,
                    "brandCode"         => "",
                    "shopperEmail"      => "test@adyen.com",
                    "shopperReference"  => "123",
                     
                    // Shopper information
                    "shopper.FirstName"=> "Testperson-nl",
                    "shopper.LastName"=> "Approved",
                    "shopper.DateOfBirthDayOfMonth"=> "10",
                    "shopper.DateOfBirthMonth"=> "07",
                    "shopper.DateOfBirthYear"=> "1970",
                    "shopper.Gender"=> "MALE",
                    "shopper.TelephoneNumber"=> "0104691602",
                    "shopper.IP"=> "62.128.7.69",
                     
                    // Billing Address fields (used for AVS checks)
                    "billingAddress.street" =>"Neherkade",
                    "billingAddress.houseNumberOrName" => "1",
                    "billingAddress.city" => "Gravenhage",
                    "billingAddress.postalCode" => "2521VA",
                    "billingAddress.stateOrProvince" => "NH",
                    "billingAddress.country" => "NL",
                     
                    // Delivery/Shipping Address fields
                    "deliveryAddress.street" => "Neherkade",
                    "deliveryAddress.houseNumberOrName" => "1",
                    "deliveryAddress.city" => "Gravenhage",
                    "deliveryAddress.postalCode" => "2521VA",
                    "deliveryAddress.stateOrProvince" => "NH",
                    "deliveryAddress.country" => "NL",
                    "deliveryAddressType" => "",
                    // Optional airline data lines. supports up to 4 legs and 10 passengers.
                    "airline.passenger_name" => "Kate Winslet",
                    "airline.ticket_number" => "XC123",
                    "airline.airline_code" => "111",
                    "airline.travel_agency_code" => "000000",
                    "airline.travel_agency_name" => "UNKNOWN",
                    "airline.customer_reference_number" => "******5837",
                    "airline.ticket_issue_address" => "YREWX08AA",
                    "airline.boarding_fee" => "12",
                    "airline.airline_designator_code" => "AA",
                    "airline.agency_plan_name" => "AA",
                    "airline.agency_invoice_number" => "222",
                    "airline.flight_date" => "2015-02-19 00:00",
                     
                    "airline.passenger1.first_name" => "Kate",
                    "airline.passenger1.last_name" => "Winslet",
                    "airline.passenger1.traveller_type" => "ADT",
                    "airline.passenger1.phone_number" => "0031634323232",
                    "airline.passenger1.date_of_birth" => "2011-04-31",
     
                    "airline.leg1.depart_airport" => "HKG",
                    "airline.leg1.flight_number" => "364",
                    "airline.leg1.carrier_code" => "AA",
                    "airline.leg1.fare_base_code" => "E",
                    "airline.leg1.class_of_travel" => "E",
                    "airline.leg1.stop_over_code" => "X",
                    "airline.leg1.destination_code" => "AMS",
                    "airline.leg1.date_of_travel" => "2015-02-19 00:00",
                    "airline.leg1.depart_tax" => "396",
                     
                    // Optional lodging data lines
                    "lodging.checkInDate" => "20150607",
                    "lodging.checkOutDate" => "20150607",
                    "lodging.folioNumber" => "1234",
                    "lodging.specialProgramCode" => "1",
                    "lodging.renterName"=>"Peter Pan",
                    "lodging.numberOfRoomRates" => "2",
                     
                    "lodging.room1.rate"=>"1220",
                    "lodging.room1.numberOfNights" => "4",
                     
                    "lodging.room2.rate"=>"1220",
                    "lodging.room2.numberOfNights" => "2",
                     
    );
     
    /*
     process fields
     */
     
    // The character escape function
    $escapeval = function($val) {
        return str_replace(':','\\:',str_replace('\\','\\\\',$val));
    };
     
    // Sort the array by key using SORT_STRING order
    ksort($params, SORT_STRING);
     
    // Generate the signing data string
    $signData = implode(":",array_map($escapeval,array_merge(array_keys($params), array_values($params))));
     
    // base64-encode the binary result of the HMAC computation
    $merchantSig = base64_encode(hash_hmac('sha256',$signData,pack("H*" , $hmacKey),true));
    $params["merchantSig"] = $merchantSig;
     
    ?>
 
<!-- Complete submission form -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Adyen Payment</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
</head>
<body>
<form name="adyenForm" action="https://test.adyen.com/hpp/select.shtml" method="post">
<?php
    foreach ($params as $key => $value){
        echo '        <input type="hidden" name="' .htmlspecialchars($key,   ENT_COMPAT | ENT_HTML401 ,'UTF-8').
        '" value="' .htmlspecialchars($value, ENT_COMPAT | ENT_HTML401 ,'UTF-8') . '" />' ."\n" ;
    }
    ?>
<input type="submit" value="Submit" />
</form>
</body>
</html>

HPP payment response

After shoppers complete a payment, they are redirected to a default result page. You can set a custom result page in the skin configuration section.

We append URL parameters to the resultURL value to inform you about the payment status of the payment.

When you direct shoppers to the Adyen platform, you need to cryptographically sign the payment session with a shared secret key. When we return to you the payment status as URL parameters, we use the same shared secret key to sign the data. This ensures that the data has not been tampered with.

Example of a redirect URL to a result page:

http://yourSite.com/pRes.jsp

Example of a corresponding resultURL:

http://yourSite.com/pRes.jsp?merchantReference=Internet%20order%2012345&skinCode=4aD37dJA&shopperLocale=en_GB&authResult=AUTHORISED&pspReference=1211992213193029&merchantSig=CPb2cObMxmIIE0khO8WhEYyKDJs%3D

<!-- Appended URL parameters:
* merchantReference = Internet order 12345
* skinCode = 4aD37dJA
* shopperLocale = en_GB
* authResult = AUTHORISED
* pspReference = 1211992213193029
* merchantSig = CPb2cObMxmIIE0khO8WhEYyKDJs%3D
 -->

 

 

Response fields

These are the parameter that are returned with a payment response:

Name Type Returned by default Description
authResult String (tick)

Returns the outcome of the payment.
It can take one of the following values:

  • AUTHORISED: the payment authorisation was successfully completed
  • REFUSED: the payment was refused. Payment authorisation was unsuccessful.
  • CANCELLED: the payment was cancelled by the shopper before completion, or the shopper returned to the merchant's site before completing the transaction.
  • PENDING: it is not possible to obtain the final status of the payment.
    This can happen if the systems providing final status information for the payment are unavailable, or if the shopper needs to take further action to complete the payment.
  • ERROR: an error occurred during the payment processing.
pspReference String (error)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.


When authResult equals PENDINGERROR or CANCELLED, the pspReference may not yet be known; therefore, it may be empty or not included.
merchantReference String (tick) The reference you assigned to the original payment.
skinCode String (tick) The code that identifies the skin used to process the payment.

merchantSig

String (tick)
The signature in Base64 encoded format.

The signature is generated by concatenating the values of a number of the payment session fields, and by computing the HMAC using the shared secret, as configured in the skin.

paymentMethod String (error) The payment method used in the transaction.
When authResult equals CANCELLED, the payment method may not be known; in this case, it is not included.
shopperLocale String (tick)

The  shopperLocale value provided in the payment request.

If no value is specified in the request, the default value en_GB is returned.

merchantReturnData

String (error)

If you define this field in the payment session setup, the value is returned as is.
This information is useful to build a custom result page, and it integrates seamlessly with the shopper's session on your server.
When the payment status is defined, we send you a server-to-server notification. This notification is the recommended way to update the payment status in your backoffice.
The notification system is more reliable in its delivery because the  resultURL parameter relies on the shopper's browser/computer/Internet connection, any of which could fail at any time.

We recommend setting a fixed resultURL in the skin configuration.
However, sometimes it may be preferable to set the result URL on a per-payment basis: to override the resultURL value specified in the skin configuration, you need to set the result URL for the payment session with the  resURL parameter.

additionalData.acquirerReference String (error)

This field is returned for open invoice in the result URL.

Payment response merchantSig - SHA 256

To verify that the values, which you have received in the result URL, are valid and have not been tampered in the process, refer to this example.

Example:

https://test.adyen.com/hpp/result.shtml?&authResult=AUTHORISED&merchantReference=SKINTEST-test&merchantReturnData=YourMerchantReturnData&merchantSig=ctYgiLlrjyG5OxoXmy8nn5n%2BYToDmw%2BR%2BqrC%2FhQxzE8%3&paymentMethod=ideal&pspReference=7914447419663319&reason=3542&shopperLocale=nl_NL&skinCode=314lwMhy

If you extract the parameters, you have:

Key

Value

authResult

AUTHORISED

merchantReference

SKINTEST-test

merchantReturnData

YourMerchantReturnData

paymentMethod

ideal

pspReference

7914447419663319

reason 3542

shopperLocale

nl_NL

skinCode

314lwMhy

Concatenate the keys and values as:

authResult:merchantReference:merchantReturnData:paymentMethod:pspReference:reason:shopperLocale:skinCode:AUTHORISED:SKINTEST-test:YourMerchantReturnData:ideal:7914447419663319:3542:nl_NL:314lwMhy

This string contains values for you to calculate merchantSig with HMAC SHA-256 key.

If some parameters are missing in the URL, they should be also omitted in the concatenated string. For example, if the merchantReturnData and reason fields are not provided, the string above should look as follows:

authResult:merchantReference:paymentMethod:pspReference:shopperLocale:skinCode:AUTHORISED:SKINTEST-test:ideal:7914447419663319:nl_NL:314lwMhy

HPP error handling

When an error condition occurs, there are some cases where Adyen cannot determine which Skin and language to use to display the error message with.

To enhance the shopper experience, you have the option to include the following fields in the URL that the shopper is directed to:

Field Description
skinCode The code of the skin used.

shopperLocale

A combination of language code and country code to specify the language used in the session.

These fields are prepended to pay.shtml or to select.shtml, and they separated by a forward slash (/), resulting in the following format options:

<skinCode>/pay.shtml

or

<skinCode>/<shopperLocale>/pay.shtml

These values are used as a fallback when Adyen is unable to determine skin and language configuration.

HPP HMAC calculation

We use HMAC signing for setting up the payment in our systems; you should use it to verify the payment result when the shopper returns to your site.

  • The signature is computed using the HMAC algorithm with SHA-256 hashing.
  • The data passed in the form fields is concatenated into a string – the signing string.
  • The merchant signature is then computed using the key specified in the skin settings.
  • The signature is passed along with the form data.
  • When Adyen receives it, we use the key to verify that the data has not been tampered with while in transit.
  • The signing string should be packed into a binary format containing hex characters, and then Base64-encoded for transmission.

Setting in Customer Area 

In the Adyen Customer Area (CA), in the Skins section, you can set an HMAC key for your test and live skins:

  1. Log into the Adyen Customer Area (CA) using your merchant credentials.
  2. On the left navigation sidebar, go to Skins.
  3. In the Skins section, select the New tab.
  4. Select the HMAC SHA-256 option.
  5. On the following screen, in the Test & Live configuration section, click the Generate new HMAC key buttons under Test platform and under Live platform.
    You need to generate both test and live HMAC values; otherwise, it is not possible to correctly save the new skin.
    The new HMAC values are stored with the corresponding skin settings.

    The HMAC key is used to verify the integrity of the payment and must always be stored on the server even when using in-app payments. If not done so, the payment details can be tempered if the app is compromised which will result in consequences.


  6. Save your changes.

Payment setup

 Create the merchant signature (HMAC SHA-256)

This example uses the following sample key/value pairs to generate the signing string: 

Key

Value

shopperLocale

en_GB

merchantReference

PAYMENTTEST:143522\64\39255

merchantAccount

TestMerchant

currencyCode

EUR

paymentAmount

1995

sessionValidity

2015-06-25T10:31:06Z

shipBeforeDate

2015-07-01

skinCode

X7hsNDWp

Sort key/value pairs by key

Sort the signing string key/value components by key. This is the default or natural order the String Java class uses.

Key

Value

currencyCode EUR
merchantAccount TestMerchant
merchantReference PAYMENTTEST:143522\64\39255

paymentAmount

1995

sessionValidity

2015-06-25T10:31:06Z

shipBeforeDate

2015-07-01

shopperLocale en_GB

skinCode

X7hsNDWp

Open invoice parameter

For open invoice, additionalData.acquirerReference is returned in the return URL.

Remove unnecessary keys

Remove the following keys, as they are not used in the signature:

  • sig
  • merchantSig
  • Any keys whose name starts with ignore. (dot included).

Concatenate and delimit key names and key values

  • Concatenate the key names, first; then, the key values.
  • Use a colon (":") to delimit key names and key values.
  • Escape embedded "\" characters as "\\", and embedded ":" as "\:".

Key (sorted + escaped)

Value (escaped)

currencyCode

EUR

merchantAccount

TestMerchant

merchantReference

PAYMENTTEST\:143522\\64\\39255

paymentAmount

1995

sessionValidity

2015-06-25T10\:31\:06Z

shipBeforeDate

2015-07-01

shopperLocale

en_GB

skinCode

X7hsNDWp

currencyCode:merchantAccount:merchantReference:paymentAmount:sessionValidity:shipBeforeDate:shopperLocale:skinCode:EUR:TestMerchant:PAYMENTTEST\:143522\\64\\39255:1995:2015-06-25T10\:31\:06Z:2015-07-01:en_GB:X7hsNDWp 

Calculate the HMAC SHA-256

To calculate the HMAC SHA-256 you need:

  • The concatenated key names + key values string.
  • The HMAC key, decoded from the corresponding hex representation.

Encode the HMAC SHA-256

  • After calculating the HMAC, encode it using Base64.

# Returns the binary data represented by the hexadecimal string
hmac_key = binascii.a2b_hex("4468D9782DEF54FCD7....AAA7550C48")

# Calculates HMAC SHA-256
hm = hmac.new(hmac_key, signing_string, hashlib.sha256)

# Encodes HMAC SHA-256 using Base64
merchantSig =  base64.b64encode(hm.digest())

Pass the signature

  • Pass to the HPP all signed key/value pairs.
  • Pass the signature with the merchantSig parameter.

You can input the calculated HMAC also as a hexadecimal-encoded 64-character key (it needs to be as long as the automatically generated 32-byte SHA-256).

  • Apart from the unnecessary keys, all the key/value pairs that are passed to the HPP must be signed.
  • Do not pass any unsigned parameters.
  • Sort the signing string key/value components by key. This is the default or natural order the String Java class uses.
  •  If a key value is null or if it is an empty value, do not submit it (recommended). If you do need or want to submit it, make sure the value is an empty string ("").
  • Whenever possible, it is a good idea to remove embedded newlines, as browsers often attempt to convert them. If you can't remove them, make sure they only consist of CR-LF pairs.
  • Set UTF-8 as the encoding for your code and for the HPP web page.
  • The deliveryAddressType field is necessary only when using the open invoice payment method.

Code examples

The examples below show simple implementations of the HMAC SHA-256 calculation for HPP.

package tests;

import java.nio.charset.Charset;
import java.security.SignatureException;
import java.util.SortedMap;
import java.util.TreeMap;
import java.util.stream.Collectors;
import java.util.stream.Stream;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

import com.google.common.io.BaseEncoding;

public class SigningTest {

    private static final String HMAC_SHA256_ALGORITHM = "HmacSHA256";
    private static final Charset C_UTF8 = Charset.forName("UTF8");

    public static void main(String[] args) {
        
        byte[] hmacKey =  BaseEncoding.base16().decode("4468D9782DEF54FCD706C9100C71EC43932B1EBC2ACF6BA0560C05AAA7550C48");

        // Sort order is important (using natural ordering)
        SortedMap<String, String> params = new TreeMap<>();
        params.put("merchantAccount", "TestMerchant");
        params.put("currencyCode", "EUR");
        params.put("paymentAmount", "199" );
        params.put("sessionValidity", "2015-06-25T10:31:06Z");
        params.put("shipBeforeDate", "2015-07-01");
        params.put("shopperLocale", "en_GB"); 
        params.put("merchantReference", "SKINTEST-1435226439255");
        params.put("skinCode", "X7hsNDWp");

        // Calculate the data to sign
        String signingData = Stream.concat(params.keySet().stream(), params.values().stream())
                .map(SigningTest::escapeVal)
                .collect(Collectors.joining(":"));

        // Create the signature and add it to the parameter map
        try {
            params.put("merchantSig",calculateHMAC(signingData, hmacKey));
        } catch (SignatureException e) {
            e.printStackTrace();
            return;
        }
        // Expected sig: GJ1asjR5VmkvihDJxCd8yE2DGYOKwWwJCBiV3R51NFg=
        System.out.println(params);
    }

    private static String escapeVal(String val) {
        if(val == null) { return ""; }
        return val.replace("\\", "\\\\").replace(":", "\\:");
    }
    
    private static String calculateHMAC(String data, byte[] key)  throws java.security.SignatureException {
        try {
            // Create an hmac_sha256 key from the raw key bytes
            SecretKeySpec signingKey = new SecretKeySpec(key, HMAC_SHA256_ALGORITHM);

            // Get an hmac_sha256 Mac instance and initialize with the signing key
            Mac mac = Mac.getInstance(HMAC_SHA256_ALGORITHM);
            mac.init(signingKey);

            // Compute the hmac on input data bytes
            byte[] rawHmac = mac.doFinal(data.getBytes(C_UTF8));

            // Base64-encode the hmac
            return  BaseEncoding.base64().encode(rawHmac);

        } catch (Exception e) {
            throw new SignatureException("Failed to generate HMAC : " + e.getMessage());
        }
    }
}

<?php
/*
    This PHP code provides a payment form for the Adyen Hosted Payment Pages
*/

/*
account details
    $skinCode:        the skin to be used
    $merchantAccount: the merchant account we want to process this payment with.
    $sharedSecret:    the shared HMAC key.
*/

    $skinCode        = "X7hsNDWp";
    $merchantAccount = "TestMerchant";
    $hmacKey         = "4468D9782DEF54FCD706C9100C71EC43932B1EBC2ACF6BA0560C05AAA7550C48";


/*
    payment-specific details
*/

    $params = array(
      "merchantReference" => "SKINTEST-1435226439255",
      "merchantAccount"   =>  $merchantAccount, 
      "currencyCode"      => "EUR", 
      "paymentAmount"     => "199", 
      "sessionValidity"   => "2015-06-25T10:31:06Z", 
      "shipBeforeDate"    => "2015-07-01", 
      "shopperLocale"     => "en_GB", 
      "skinCode"          => $skinCode );


/*
    process fields
*/
    
    // The character escape function
    $escapeval = function($val) {
     return str_replace(':','\\:',str_replace('\\','\\\\',$val));
    };
    
    // Sort the array by key using SORT_STRING order
    ksort($params, SORT_STRING);

    // Generate the signing data string
    $signData = implode(":",array_map($escapeval,array_merge(array_keys($params), array_values($params))));
    
    // base64-encode the binary result of the HMAC computation
    $merchantSig = base64_encode(hash_hmac('sha256',$signData,pack("H*" , $hmacKey),true));
        $params["merchantSig"] = $merchantSig;
    
?>


<!-- Complete submission form -->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>Adyen Payment</title>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8" />
</head>
<body>
    <form name="adyenForm" action="https://test.adyen.com/hpp/pay.shtml" method="post">
        
<?php
foreach ($params as $key => $value){
    echo '        <input type="hidden" name="' .htmlspecialchars($key,   ENT_COMPAT | ENT_HTML401 ,'UTF-8'). 
                                   '" value="' .htmlspecialchars($value, ENT_COMPAT | ENT_HTML401 ,'UTF-8') . '" />' ."\n" ;
}
?>
    <input type="submit" value="Submit" />
    </form>
</body>
</html>

#!/usr/bin/env python
# -*- coding: UTF-8 -*-

import base64
import hmac
import hashlib
import binascii
from collections import OrderedDict

def escapeVal(val):
  return val.replace('\\','\\\\').replace(':','\\:')

def signParams(parms):
  signing_string = ':'.join(map(escapeVal, parms.keys() + parms.values()))
  hm = hmac.new(hmac_key, signing_string, hashlib.sha256)
  parms['merchantSig'] =  base64.b64encode(hm.digest())
  return parms

hmac_key = binascii.a2b_hex("4468D9782DEF54FCD706C9100C71EC43932B1EBC2ACF6BA0560C05AAA7550C48")

rawparams = {
  'merchantAccount': 'TestMerchant', 
  'currencyCode': 'EUR', 
  'paymentAmount': '199', 
  'sessionValidity': '2015-06-25T10:31:06Z', 
  'shipBeforeDate': '2015-07-01', 
  'shopperLocale': 'en_GB', 
  'merchantReference': 'SKINTEST-1435226439255', 
  'skinCode': 'X7hsNDWp' }

params = OrderedDict(sorted(rawparams.items(), key=lambda t: t[0]))

# expected merchantSig = GJ1asjR5VmkvihDJxCd8yE2DGYOKwWwJCBiV3R51NFg=
print signParams(params)

Testing

If you experience any issues with the merchant signature, you can check your HMAC calculation in the Adyen Customer Area (CA). To do so, enter the payment session fields, then check if your merchant signature matches the merchant signature computed by Adyen.

After logging in to the Adyen Customer Area (CA), you can also check your HMAC calculation by submitting a payment request to ca-test.adyen.com/ca/ca/skin/checkhmac.shtml. Besides the standard payment fields, you can also submit the signingString field value.

Payment reminder email

For offline payment methods that require the shopper to perform an action after the payment flow has completed, the shopper is given the option to get notified through an email about a payment detail. For example in a bank transfer the bank details, amount, and transfer reference is required to complete the payment. If you are not using such a payment method you can ignore this section.

The shopper can specify their email address in the supplied field, but if the shopperEmail parameter is sent with the payment request the field is pre-populated with this data.

After clicking the Pay button, the shopper is redirected to the next page which provides instructions about the transfer to be processed:

The shopper has the option of receiving an email message with these instructions.

This is a branded example of such an email message in German:

By default, a generic Adyen branded email is sent, the look of this email can be customised in the skin. The following resource keys are used:

pmDetailEmailReminder.sendCopyCheckbox=Send a copy of these details to my email address 
pmDetailEmailReminder.emailAddress=Email Address 
pmDetailEmailReminder.orderDetailsHeader=Order Details 
pmDetailEmailReminder.reminderNote=Added Note 
pmDetailEmailReminder.noteToSelfMessage=Add a note to the email 
pmDetailEmailReminder.bankTransfer_NL.subject=Copy of Your Bank Transfer Details 
pmDetailEmailReminder.bankTransfer_NL.title=Copy of Your Bank Transfer Details

The last two keys are specific for the payment method used. For example, use pmDetailEmailReminder.bankTransfer_FR.subject for French bank transfers, or pmDetailEmailReminder.bankTransfer_IBAN.subject for international bank transfers.

For more details about how to overwrite resource entries see the how to create and edit translations.
Three other files used in the email message are:

File name

Description

inc/bankTransfer_email.txt

Can contain HTML markup and is included at the bottom of the email. This file can be internationalised as, for example, bankTransfer_email_nl.txt.

inc/header_detail_email_reminder.txt

There is a default inline stylesheet/header included with the email. If you would like to change these styles you can add this file, which is then inserted in the head of the HTML email content and overwrites the default value. See, default remiinder email for the default value of this header.

img/pm_detail_reminder.png

Assumed to be 475 pixels wide.
If you want to use an image with a different width, you may need to make some changes to the stylesheet/header (see above).

Looking at the German email example in more detail:

  • Block A: Logo is set in the skin in img/pm_detail_reminder.png
  • Block B: Shows the note the shopper wrote when setting the notification email.
  • Block C: Is set in the skin in inc/bankTransfer_email.txt
  • Block D: Border is removed or customised in inc/header_detail_email_reminder.txt (border in #content section)
  • Block E: Information is taken from the transaction

Default reminder email example:

<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<title>Copy of Your Bank Transfer Details</title>
    <style type="text/css">
		body {
    		font-size: 0.75em;
		    font-family: tahoma, verdana, arial, sans-serif;
   	 		background-color: #fff;
	    	color: #333;
		}
            
		table td, table th {
    		font-size: 0.75em;
		}
            
		#content {
     		padding: 15px;
		    width: 475px;
		    margin-left: 20px;
		    margin-right: 20px;
		    border: 1px solid #666;
		}
            
		#logoheader {
		    text-align: center;
		}
                                   
		h1,h2 {
		    color: #73981d;
		    padding-top: 6px;
		    font-size: 1.3em;
		    font-weight: bold;
		    margin-top: 0.5em;
		    margin-bottom: 0.8em;
		}
            
		h3 {
		    margin-left: 5px;
		    font-size: 1.3em;
		    font-weight: bold;
		    margin-top: 0.5em;
		    margin-bottom: 0.5em;
	    }
            
		a {
		    text-decoration: none;
		    color: #39f
		}
            
		a:visited {
		    text-decoration: none;
		    color: #39f
		}
            
		#paymenturlimg {
		    border: 0px;
		}
	</style>
</head>

Email with direct payment instructions

If you want to communicate to your customers directly with offers, you can include a direct link to the payment page in every email – with descriptions, payment amount, etc. already pre-filled.

This means that you can generate payment links without Adyen's intervention, even when sending out thousands of emails to your customers.  For example, if you have an offer for a cooking set as depicted below. You send out a mail to your customers and they get the following message in their mailbox: 

By clicking the Pay Now! button, the shopper is immediately sent to the (one-page) payment screen, where all order details are already filled in. Shopper only needs to enter their payment details.

When to use

  • Marketing actions to your existing customer base
  • If you have seen shoppers abandon the ordering processing

When constructing the email your system builds a link to our payment page just as would happen in your webshop. The example below shows what such links look like:

https://test.adyen.com/hpp/pay.shtml?paymentAmount=8650&currencyCode=EUR&shipBeforeDate=2009-09-23&merchantReference=TMRef1234&skinCode=aF563qQs&merchantAccount=TestMerchant&sessionValidity=2009-09-17T11%3A38%3A55Z&merchantSig=62unnLF...ubZc%3D-&shopperLocale=en_GB&orderData=H4sIAAAAA.....OQBQDxrK1skQEAAA%3D%3D

Due to restrictions of most Internet browsers, the GET URL is limited to a maximum of 1024 characters. You also need to properly urlencode the URL.

Ensure that the sessionValidity value is in set sometime in the future to allow the shopper time to pay for the product since this is communicated offline (via email).

HPP modifications

After a payment has been submitted via HPP and it has been authorised, you need to define the next steps in the transactions. A payment can go through different states, depending on the actions that are performed.

These are the available payment states in the Adyen payment system:
 

Payments transition from a state to another through modifications, i.e. actions that affect the current state of the payment. These modifications are:

  • Cancel. Cancels the payment before any funds are transferred from the shopper to the merchant.
  • Capture. Captures (partially) the amount that was authorised for the payment. This modification will transfer the funds from the shopper to the merchant's bank account.
  • Refund. Returns the funds from the merchant to the shopper, after the transaction was already captured.

Depending on the current state of a payment, these modifications are available in the Adyen Customer Area (CA), under the page displaying the details of a payment.

If you process more than a handful of payments daily, we recommend automating payment modifications by making calls to our API and by using our payment web service.

HPP notifications

We send you notifications to inform you about the outcome of an action: when a payment is made, a modification is processed or a report is available for download, we notify the event and whether it was successful or not.

The purpose of notifications is to sync your backoffice system, so that payment and modification statuses are always up to date.

(tick) You receive capture notifications for capture requests submitted via your web service or the Adyen CA.
(error) You do not receive capture notifications for automatic captures initiated by the Adyen platform.

Additional features

HPP in an iFrame

Although possible, using iFrames can introduce known usability, security and cross-domain browser issues.

Please keep the following in mind:

  • Some redirect payment methods, such as iDEAL, do not allow displaying their pages in an iFrame; they will break out of it. Other redirect payment methods may require more available screen space than your iFrame allows. You should also be prepared to handle the difference in behaviour for the payment result URL, as once the payment completes you may not be in an iFrame anymore.
  • Another problem you may face is the browser's cookie policy. The HPP solution requires cookies. Using an iFrame means that the browser may impose restrictions regarding the conditions in which cookies are allowed to be set within the iFrame. While there are workarounds to get the browser to accept cookies in a default configuration, the shopper may have configured a more restrictive policy. The most common problem is with Apple Safari and Google Chrome browsers: by default, they require user-initiated page loading inside an iFrame. This means that first the iFrame needs to be loaded with a page hosted at the parent domain. Secondly, on this page the user needs to actively click on a button submitting the redirect to the HPP.

Adyen cannot guarantee that all payment methods will work when using an iFrame, nor that the behaviour of a payment method will remain the same. Furthermore, the exact operation of a redirect payment method can differ between the test and the live environments.

Filtering payment methods

For some payment requests, you may decide to filter the payment methods that are displayed on the HPP or bypass the HPP entirely.

  • The allowedMethods field is used to display specific payment methods.
  • The blockedMethods field is used to prevent specific payment methods from being displayed.
  • The brandCode and the issuerId fields are used to take the customer directly to a specific payment method.

All the payment methods that are configured for your account, including the value you use to indicate the specific payment method, are available in the Adyen Customer Area (CA) interface under Settings | Payment Methods | Name.
For the allowedMethods and blockedMethods fields you can use a group payment method value:

Payment group name

Value

Cards (includes all debit and credit cards)

card

Bank Transfers (from all countries)

bankTransfer

Payment method availability

Some payment methods are not available in all countries. For example, iDEAL is only offered if the shopper is from The Netherlands.

If the payment method selection is done on your web site, and the allowedMethods parameter contains a value for a payment method that is not available in all countries, we advise that you set the countryCode parameter as well. This ensures that the shopper only sees the payment methods that are relevant for their country.

For example, if you set allowedMethods to ideal, you need to set countryCode to NL to ensure that the iDEAL payment method is displayed.
The list of countries where a payment method is offered is also available in the payment methods list in the CA interface, under the Available Countries column.

The list of payment methods may differ in the test and live environments. All payment methods are not automatically configured for the LIVE environment.

Custom payment methods

Adyen offers an option to display custom payment methods on the HPP. 

This functionality is not enabled by default, as it requires additional configuration on Adyen's end. Contact the  Adyen Support Team to request enabling it for you.
 

The name of a custom payment method always starts with c_. For example, c_invoice.

The custom payment method is displayed like all other payment methods on your HPP. This also means that you can add extra charges to the payment method, change the display order, and so on. 

When a shopper selects a custom payment method, they are redirected to a static URL, which you need to provide during the setup of the custom payment method. The following parameters are passed back to this redirect URL.

Field Description

pspReference

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

merchantReference

This is the reference that you assigned to the original payment.

skinCode

The code of the Skin used to process the payment.

paymentAmount

The payment amount as specified in your initial payment request.

currencyCode

The three-character ISO currency code.

additionalAmount (optional)

An additional amount when there are extra charges configured for this custom payment method in your skin. Similiar to the paymentAmount field, the additionalAmount is specified in minor units, without a decimal separator.

customPaymentMethod

The custom payment method used for the transaction.

paymentMethod

The payment method used for the transaction; it holds the same value as customPaymentMethod.

merchantSig

The signature in Base64 encoded format.

The signature is generated by concatenating the values of a number of the payment session fields, and by computing the HMAC using the shared secret, as configured in the skin.

merchantReturnData

If you set this field in the payment session setup, the value is passed back as-is.

The customPaymentMethod and paymentMethod parameters hold the same value, and they are both included in the URL to keep consistent with the resultUrl value.

Given that there are extra fields in the custom payment URL the associated merchantSig is also calculated differently.
authResult is not one of the parameters because its value is not known. It should be determined by the system that is behind the redirect URL.
After a shopper has selected the custom payment method, the payment request is stored in our system with the HandledExternally status.

Testing

AVS

You can use a set of test card numbers and test accounts for QA purposes and to verify that your implementation works as expected.

You can test all available AVS result codes. To do so, you can use the billingAddress.street and the billingAddress.houseNumberOrName fields in a standard payment request form to submit the AVS code data you want to check.

<input type="hidden" name="billingAddress.city" value="Burbank" />
<input type="hidden" name="billingAddress.street" value="Test AVS result" />
<input type="hidden" name="billingAddress.houseNumberOrName" value="4" />
<input type="hidden" name="billingAddress.postalCode" value="91521" />
<input type="hidden" name="billingAddress.stateOrProvince" value="California" />
<input type="hidden" name="billingAddress.country" value="US" />
<input type="hidden" name="billingAddressType" value="0" />
<input type="hidden" name="billingAddressSig" value="m+fDzztb/oMEO4BEGc4mvedlKHU=" />

 Test AVS result codes 

You can test AVS result values. Assign the appropriate values to the child elements of the  billingAddress element, as described below:
Parent Child Value to test AVS
billingAddress    
  street Test AVS result
  houseNumberOrName <specify_here_the_avsResult_value_to_test>

You still need to include and define all the other billingAddress child elements, but their values do not impact the avsResult return value you want to test.

You can use a test card number from this list to test AVS results.

AVS result values

0 Unknown
1 Address matches, postal code doesn't
2 Neither postal code nor address match
3 AVS unavailable
4 AVS not supported for this card type
5 No AVS data provided
6 Postal code matches, address doesn't match
7 Both postal code and address match
8 Address not checked, postal code unknown
9 Address matches, postal code unknown
10 Address doesn't match, postal code unknown
11 Postal code not checked, address unknown
12 Address matches, postal code not checked
13 Address doesn't match, postal code not checked
14 Postal code matches, address unknown
15 Postal code matches, address not checked
16 Postal code doesn't match, address unknown
17 Postal code doesn't match, address not checked
18 Neither postal code nor address were checked
19 Name and postal code matches
20 Name, address and postal code matches
21 Name and address matches
22 Name matches
23 Postal code matches, name doesn't match
24 Both postal code and address matches, name doesn't match
25 Address matches, name doesn't match
26 Neither postal code, address nor name matches

CVV-CVC results

To test CVC/CVV result codes on HPP, you need to prefix the code number you want to test with two padding zeroes: 00<CVCCCVcode>

For example, to test CVC/CVV result code 4 No CVC/CVV provided, enter it as  004 in the CVV field on the HPP.

You can test CCV/CVV result codes. Assign the appropriate values to the child elements of the card element, as described below:

Parent Child Value to test CVC/CVV
card    
  number <specify_here_a_test_card_number>
  cvc <specify_here_the_CVC/CVV_code_to_test>

You still need to include and define all the other card child elements, but their values do not impact the cvc return value you want to test.

You can use a test card number with a CVC from this list to test CVC/CVV results.

Card examples

The following examples show how use the card element to test specific CVC/CVV result codes.

"card" : {
    "number" : "4111111111111111", // Use a test card number that has a CVC number
    "cvc" : "737", // Use padding zeroes as necessary before the 1- or 2-digit CVC-CVV code you want to test
    "expiryMonth" : "08",
    "expiryYear" : "2018",
    "holderName" : "Adyen Test"
}

&card.cvc=737&card.expiryMonth=08&card.expiryYear=2018&card.holderName=Adyen+Tester&card.number=4111111111111111

<!-- cvc: use padding zeroes as necessary before the 1- or 2-digit CVC-CVV code you want to test
     paymentRequest.card.number: use a test card number that has a CVC number -->

<card xmlns="http://payment.services.adyen.com">
    <cvc>737</cvc> // Use padding zeroes as necessary before the 1- or 2-digit CVC-CVV code you want to test
    <expiryMonth>08</expiryMonth>
    <expiryYear>2018</expiryYear>
    <holderName>Adyen Test</holderName>
    <number>4111111111111111</number> // Use a test card number that has a CVC number
</card>

CVC-CVV result codes

0 Unknown
1 Matches
2 Doesn't match
3 Not checked
4 No CVC/CVV provided, but was required
5 Issuer not certifed for CVC/CVV
6 No CVC/CVV provided

Error codes

You can test refused transactions and the specific refusal reason that are returned when a transaction fails. Assign the appropriate values to the  holderName child element of the  card element, as described below:
Parent Child Value to test refusal reason
card    
  holderName <specify_here_[refusal_code]+[:]+[raw string refusal reason to test]>

This is the format of the refusal reason code you want to test, and whose value you need to assign to the holderName element:

[Response code] : [Refusal reason raw string to test]
DECLINED : 05 : ISSUER_UNAVAILABLE

You can use a test card number with a CVC from this list to test CVC/CVV results.You still need to include and define all the other card child elements, but their values do not impact the refusal reason return value you want to test.

  • The holderName field value cannot be longer than 80 characters max.
  • You may need to lower the risk score value to take into account non-alphabetic characters in the card holder name like a colon  (":"). This and other non-alphabetical characters trigger the risk check, which may cause the payment to be declined with a FRAUD reason code.

  • If you specify an incorrect CVC or an invalid expiry date, the payment fails and the operation returns a generic DECLINED refusal reason.

These are the available response codes for testing:

  • REFERRAL

  • ERROR

  • BLOCK_CARD

  • CARD_EXPIRED

  • DECLINED

  • INVALID_AMOUNT

  • INVALID_CARD

  • NOT_SUPPORTED

  • NOT_3D_AUTHENTICATED

  • NOT_ENOUGH_BALANCE

  • APPROVED

Testing chargebacks

To test a chargeback, create a payment and enter Chargeback in the Cardholder name field.

This simulates a flow for a chargeback, the payment goes through the normal process for authorisation and settlement.

After settlement, the chargeback is initiated.