Hosted Payment Page


If you are integrating into our Hosted Payment Page (HPP) we will handle a lot of the steps required to authenticate your customers as detailed in ourEMV® 3-D Secure (v2) guides.

This developer documentation focuses on integrating 3-D Secure as well as ensure there is no effect on your PCI compliance responsibilities – keeping you in-scope for SAQ A.

By completing this integration guide, you will cater for all scenarios and be SCA ready.


As you will see in the HPP Documentation we've marked which additional parameters are required for EMV® 3-D Secure (v2).

To save you needing to go take a closer look, here is a summary:

Make sure you have set the is_tds parameter as 2 to let us know you want to use 3-D Secure.

It is best practice to send on additional customer data the issuing bank will need to authenticate the cardholder. This consists of:

  • The cardholder's billing address (billing_street, billing_city, billing_zipcode and billing_country_code_iso2).
  • The cardholders' contact details (billing_email).
  • A link to the "Contact Us" page on your website (merchant_contact_url).

In case it is EMV® 3-D Secure (v2), we need to know some additional settings / preferences you have for the authentication (tds_source, tds_type and tds_preference).

Once we have all of this information, we can handle any scenario that pops up.

Be careful - When you add in these new parameters make sure you include them in your request hash or it will cause errors.


As you will see in the API documentation for EMV® 3-D Secure (v2) there are a few extra steps required to complete authentication including:

  • Checking the version of 3-D Secure supported by the card issuer.
  • Gathering the Device ID via the method_url.
  • Gathering the user's browser data.

We've added all these actions to our acquired.js file in the default HPP template (which you can get from the Hub) to ensure everything works as it should.


In the event that there is a ‘challenge’, we will display the issuer's ACS page to the user in order to complete the authentication - nothing you need to do here.


Once authentication is complete, we'll respond back to you in your chosen method but there are some additional response codes / fields you should be aware of:

Parameter Format Length Description
code int 1-3 If the Authentication is successful, we'll return one of our standard authorisation response codes.

However, if it fails you'll see one of the following values:

540 SCA: Failed
541 SCA: Not Successful
542 SCA: Issuer Rejected
565 SCA: Required
eci int 1 Just like the existing version of 3-D Secure the ECI (e-Commerence Indicator) has been used to indicate the outcome of the authentication.

Possible values for Visa and American Express are: 5 (Success), 6 (Attempted), 7 (Failed).
Possible values for MasterCard are: 2 (Success), 1 (Attempted), 0 (Failed).
reason int 1-2 Provides more information on the outcome of the authentication. Possible values are:

01 = Authentication Failed
02 = Unknown Device
03 = Unsupported Device
04 = Exceed Authentication Frequency Limit
05 = Expired Card
06 = Invalid Card Number
07 = Invalid Transaction
08 = No Card Record
09 = Security Failure
10 = Stolen Card
11 = Suspected Fraud
12 = Transaction Not Permitted to Cardholder
13 = Cardholder Not Enrolled in Service
14 = Transaction Timed Out at ACS
15 = Low Confidence
16 = Medium Confidence
17 = High Confidence
18 = Very High Confidence
19 = Exceeds ACS Max Challenges
20 = Not Payment Transction Not Supported