Additional features for Hosted Payment Pages

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 requires additional configuration on Adyen's end. To enable it, contact the  Support Team.
 

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-character 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. It is generated by concatenating the values of payment session fields, and by computing the HMAC using the shared secret, as configured in the skin.

For more information, refer to HMAC signature calculation.

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.

Address Verification System (AVS)

This is a security feature that verifies the billing address of the cardholder. It does so by comparing the numeric portions of the card holder's registered billing address to those entered by the shopper. It must be supported for a limited set of card types in certain countries.

For more information, refer to AVS.