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.