Hosted Payment Page

Overview

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 our 3-D Secure v1 and EMV® 3-D Secure (v2) guides.

This developer documentation focuses on integrating both versions of 3-D Secure in one go to avoid the need to complete any work to firstly identify which version is supported and secondly to have 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.

Request

As you will see in the HPP Documentation we've marked which additional parameters are required for 3-D Secure v1 and 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.

Since we don't know what version is supported yet, 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_street2, billing_city, billing_zipcode and billing_country_code_iso2)
  • The cardholders' contact details (billing_phone_code, billing_phone and 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.

Template

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.

If you are on an older version of the HPP template - you will need to update it include acquired.js in order to support EMV® 3-D Secure (v2) and all these additional steps.

Authentication

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.

Response

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
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 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