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.