Skins for Hosted Payment Pages

Skin is an interface overlay that is applied to the Adyen Hosted Payment Page (HPP) to customize it according to your brand guidelines and create a seamless consumer checkout experience. The skin comprises 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 of multiple accounts is usually due to reconciliation or accounting requirements, which are not covered in this section.

Managing skins in CA

You can create, edit, upload, test, and publish your skins in your Customer Area > Settings > Skins.

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

1. Click the New tab and follow the instructions 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 tab displays the Edit skin configuration screen and populates the values entered while creating the Skin. The fields are editable if you set a shared secret, 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, you may upload it to the TEST system to combine it with the current skin settings.
5. If 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.

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. Because 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. You require the details for the LIVE environment 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. You cannot use the same Key for both the TEST and LIVE environment.

• 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 behavior: The standard behavior, when the consumer clicks the previous button on the HPP, is to redirect the shopper to the resultURL with authResult=cancelled. This option performs the action browser minus 1, taking the shopper back to the previous page.
• ShopperInteraction for this Skin: We recommend that this option remains set to Unset, this ensures that the system selects the correct shopper interaction to use.
• Support partial payments: Enable partial payment for gift cards. This means that a shopper can pay a part of the transaction amount with their gift card, the shopper can pay the remaining amount 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: Adyen provides the ability to set a surcharge or discount per payment method. This option determines how the extra cost or discount displays 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 supporting it note that not all payment methods support iFrames, an example is iDEAL.
  This setting provides you with three options:

  • Selecting No disables breaking out of iFrames.

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

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:

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.

You can add additional support for countries/regions for any payment method in the test environment as:

1. Go to Customer Area > Settings > Skins and click on the name of the skin you are using.
2. Edit the payment method.
3. Under the options column, click for the payment method you want to edit.
4. Select Overwrite available countries.
5. Select the country/region in the Deselected countries list.
6. Click  to add it to Selected countries.
7. Click Save changes.
8. Publish the skin to live.

Custom Fields: Custom fields are a powerful feature of the payment pages that allow you to add form fields to the HPP. These are 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 localized 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:

    <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>YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j</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:

    <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: Customer Area offers a visual interface to view and modify the text strings in the Adyen standard language set. You can add the languages that are not part of the standard using the Skin resource file method.

With the Skin selected click the Edit Language Files** link in the Extra Options** section. A table shows 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 want 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 is created/updated each time you save.

To edit another language, choose its shopper locale from the Language drop-down list. A table shows 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 named resources_[language].properties is created in the res directory of the skin. For example, if the shopper locale = nl, 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

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

1. Create a skin.
2. Perform test transactions with the different payment methods that you want to offer to your customers. Initiate these tests should 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 webhooks for each of the following event codes:
   • AUTHORISATION
   • CANCELLATION
   • REPORT_AVAILABLE
   • CAPTURE
   • REFUND

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.