Process 3-D Secure authenticated transactions

  The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.
If you are unsure, please contact our Support Team for assistance.

The following document explains how to perform EMV 3-D Secure authentication (using our JavaScript Library) and a subsequent payment using our Webservices API.

  About EMV 3-D Secure

EMV 3-D Secure is a form of Strong Customer Authentication (SCA) designed to reduce fraud and chargebacks during e-commerce transactions. It allows card issuers to provide an extra level of protection, by authenticating cardholders at the point of sale (e.g. with a secret password or biometrics) if the payment is deemed high risk.

The Revised Directive on Payment Services (PSD2) mandates that a form of Strong Customer Authentication (SCA) is performed on all transactions initiated by the customer through their browser. You will need to utilise 3-D Secure to comply with PSD2.

Click here to learn more.

 

Overview

  This process necessitates that you capture the customer's card details on your own servers, ready to perform EMV 3DS authentication, as described below.

Hostedbymerchant.svg

  1. You will need to host a page with a form with an action to POST to an intermediary page that hosts our mark-up.
  2. The aforementioned intermediary page is effectively a holding page that is temporarily shown before the customer EMV 3DS authentication is performed. This authentication is automatically handled by st.js. Click here to learn more about EMV 3DS authentication. During this process, the customer’s browser may display an overlay, where they are asked to complete some basic actions to authenticate their identity.

  We recommend displaying a loading animation and/or message in case the JS takes more than a couple of seconds to complete the request.

  1. Following any checks and authentication required by the customer’s card issuer, the overlay will close automatically, and the response details will be returned to your server.
  2. To process the payment, your server will need to submit an AUTH request containing data returned in the response.

 

Modify the server-side payment form

You will need to host a form on the intermediary page, which is set up to initialise the st.js library with a configuration containing the JWT that was generated on the merchant's server. This step is required to initiate the EMV 3DS authentication process.

<html>
<head>
</head>
<body>
<div id="st-notification-frame"></div>
<form id="st-form" action="https://www.example.com" method="POST">
</form>
<script src="<DOMAIN>/js/v3/st.js"></script>
<script>
(function() {
var st = SecureTrading({
jwt:'INSERT YOUR JWT HERE',
submitOnError: true
});
st.Components({startOnLoad: true});
})();
</script>
</body>
</html>

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

st.js

The server-side payment form will need to include our “st.js” JavaScript Library. The st.js will handle the EMV 3DS authentication, contacting the card issuer to determine if the card is enrolled (a THREEDQUERY is processed). If the card issuer determines that there is an elevated risk of fraud, an overlay will automatically be displayed to the customer where they will be prompted for authentication.

  Please ensure your system references the st.js library on the Trust Payments servers. This ensures your solution is always using the latest version of the library.

  Our st.js will contact the card issuer to determine if the card is enrolled. If the card issuer determines that there is an elevated risk of fraud, an overlay will automatically be displayed to the customer where they will be prompted for authentication.

To enable this behaviour, you will need to reference the JavaScript Library by including a defined configuration that uses a specific method (“st.Components”) within “st.js”.

Note: Ensure you include the anonymous function as shown in the example. This prevents the JS from being executed until the st.js has been loaded.

 

st-form

You must ensure that your payment form has been assigned the id “st-form” and an action attribute that contains a valid URL address hosted on your server. The address specified must be able to handle the data returned in application/x-www-form-urlencoded format (see the example below). Click here for an example.

 

startOnLoad

You must ensure that when calling the st.Components method that you pass a config property of startOnLoad is true. This negates the need for further customer interaction for the intermediary form to submit the data to Trust Payments.

 

submitOnError

You must ensure your form includes the additional field submitOnError, with value true. This ensures that if an error occurs, the customer will be redirected to your website so they can amend their details and retry the payment.

 

jwt

  The jwt property added to the initialisation config will need to be in the form of a JSON Web Token (JWT), which consists of encoded data. JSON Web Tokens are an open, industry standard RFC 7519 method for securely transmitting data between two parties. Click here to learn more about JWT.

  1. You will need to refer to this resource and choose a library with which to generate and verify the JWT.
  2. When generating a JWT payload, our TRU Connect gateway will require you to submit a number of fields, which are detailed on this page, under section "Generating the payload".

Note: In this workflow, the JWT must also include the pan, expirydate and securitycode fields, as shown in the example below:

{
"payload":{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"currencyiso3a":"GBP",
"sitereference":"test_site12345",
"requesttypedescriptions":["THREEDQUERY"],
"pan":"4000000000001091",
"expirydate":"12/2022",
"securitycode":"123"
},
"iat":1559033849,
"iss":"jwt.user"
}

  In order to reduce fraud, Visa has mandated that all UK-based merchants with a Merchant Category Code (MCC) of 6012 are required to send additional fields in the payload for inheritance by the subsequent authorisation request.

Failure to submit these fields may prevent the transaction from being processed successfully, with a “60025” errorcode being returned in the response.

Click here for further information.

 

Handling the JWT response

Following authentication with EMV 3DS, your system will be returned a number of parameters, the most important of which are:

  1. jwt - contains gateway response
  2. threedresponse - contains step-up authentication result (not always present)

 


1. jwt - contains gateway response

Before trusting any value returned in the jwt payload, your system must first verify the signature to ensure the data has not been modified by an unauthorised third party.

The response JWT consists of three parts separated by dots (“.”), in the following format:

Header.Payload.Signature

jwt Decoded jwt
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MzMwOTg4NzMsInBheWxvYWQiOnsicmVxdWVzdHJlZmVyZW5jZSI6IlcyNC1wcWJ3aDBuMiIsInZlcnNpb24iOiIxLjAwIiwiand0IjoiZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnBjM01pT2lKM1pXSnpaWEoyYVdObGMwQnRaWEpqYUdGdWRDNWpiMjBpTENKcFlYUWlPakUyTXpNd09UZzROek1zSW5CaGVXeHZZV1FpT25zaVkzVnpkRzl0WlhKMGIzZHVJam9pUW1GdVoyOXlJaXdpWW1sc2JHbHVaM0J2YzNSamIyUmxJam9pVkVVeE1pQXpVMVFpTENKamRYSnlaVzVqZVdsemJ6TmhJam9pUjBKUUlpd2lZM1Z6ZEc5dFpYSndjbVZ0YVhObElqb2lNVElpTENKaWFXeHNhVzVuYkdGemRHNWhiV1VpT2lKT1lXMWxJaXdpYkc5allXeGxJam9pWlc1ZlIwSWlMQ0pqZFhOMGIyMWxjbXhoYzNSdVlXMWxJam9pVG1GdFpTSXNJbUpwYkd4cGJtZGxiV0ZwYkNJNkluUmxjM1JBWlhoaGJYQnNaUzVqYjIwaUxDSmlhV3hzYVc1bmNISmxiV2x6WlNJNklqRXlJaXdpYzJsMFpYSmxabVZ5Wlc1alpTSTZJblJsYzNReElpd2lZV05qYjNWdWRIUjVjR1ZrWlhOamNtbHdkR2x2YmlJNklrVkRUMDBpTENKd1lYSmxiblIwY21GdWMyRmpkR2x2Ym5KbFptVnlaVzVqWlNJNklqSTBMVGt0T0RBd05qRWlMQ0ppYVd4c2FXNW5jM1J5WldWMElqb2lWR1Z6ZENCemRISmxaWFFpTENKeVpYRjFaWE4wZEhsd1pXUmxjMk55YVhCMGFXOXVjeUk2VzEwc0ltTjFjM1J2YldWeWMzUnlaV1YwSWpvaVZHVnpkQ0J6ZEhKbFpYUWlMQ0pqZFhOMGIyMWxjbkJ2YzNSamIyUmxJam9pTVRFeU15SXNJbUpwYkd4cGJtZDBaV3hsY0dodmJtVjBlWEJsSWpvaVRTSXNJbUpoYzJWaGJXOTFiblFpT2lJeE1EQXdJaXdpWW1sc2JHbHVaM1JsYkdWd2FHOXVaU0k2SWpBeE1qTTBJREV4TVRJeU1pSXNJbUpwYkd4cGJtZG1hWEp6ZEc1aGJXVWlPaUpVWlhOMElpd2lZbWxzYkdsdVozUnZkMjRpT2lKQ1lXNW5iM0lpZlgwLkpfVzlGU19MYkVzTXQ0SjhnWUlTSDNQcjNDMl9PUHRQMVd1Nm1MRklON0UiLCJyZXNwb25zZSI6W3sidHJhbnNhY3Rpb25zdGFydGVkdGltZXN0YW1wIjoiMjAyMS0xMC0wMSAxNDozNDozMyIsImN1c3RvbWVyb3V0cHV0IjoiVEhSRUVEUkVESVJFQ1QiLCJsaXZlc3RhdHVzIjoiMCIsIm1lcmNoYW50bmFtZSI6IlRlc3QgVW5pdHRlc3QgU2l0ZSIsImRjY2VuYWJsZWQiOiIwIiwic2V0dGxlZHVlZGF0ZSI6IjIwMjEtMTAtMDEiLCJlcnJvcmNvZGUiOiIwIiwiYWNxdWlyZXJ0cmFuc2FjdGlvbnJlZmVyZW5jZSI6Ilp6eDhxYzQzUEJGQXZGVXdlNDcwIiwidGlkIjoiMjc4ODAwMDAiLCJ0aHJlZWRwYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNUzR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUkyWm1Jd1pETXlZeTA0WVdObUxUUTRNR1l0T1dZeE5DMWxNV0UwT0RjNU9UQmhaV0VpTENKaFkzTlVjbUZ1YzBsRUlqb2lNMlV6TjJZd1pUSXRNVEEyTlMwMFpEUmtMV0ZqTXprdE9XTTBNMll4TkdGaFl6RXpJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJtZXJjaGFudG51bWJlciI6IjAwMDAwMDAwIiwibWVyY2hhbnRjb3VudHJ5aXNvMmEiOiJHQiIsInN0YXR1cyI6IkMiLCJ0cmFuc2FjdGlvbnJlZmVyZW5jZSI6IjI0LTktODAwNjEiLCJ0aHJlZWR2ZXJzaW9uIjoiMi4xLjAiLCJwYXltZW50dHlwZWRlc2NyaXB0aW9uIjoiVklTQSIsImFjc3VybCI6Imh0dHBzOi8vMG1lcmNoYW50YWNzc3RhZy5jYXJkaW5hbGNvbW1lcmNlLmNvbS9NZXJjaGFudEFDU1dlYi9jcmVxLmpzcCIsImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYWNxdWlyZXJyZXNwb25zZWNvZGUiOiIwIiwicmVxdWVzdHR5cGVkZXNjcmlwdGlvbiI6IlRIUkVFRFFVRVJZIiwiaXNzdWVyIjoiU2VjdXJlVHJhZGluZyBUZXN0IElzc3VlcjEiLCJtYXNrZWRwYW4iOiI0MDAwMDAjIyMjIyMxMDkxIiwiZXJyb3JtZXNzYWdlIjoiT2siLCJvcGVyYXRvcm5hbWUiOiJ3ZWJzZXJ2aWNlc0BtZXJjaGFudC5jb20iLCJlbnJvbGxlZCI6IlkiLCJpc3N1ZXJjb3VudHJ5aXNvMmEiOiJaWiIsInNldHRsZXN0YXR1cyI6IjAifV0sInNlY3JhbmQiOiJad0VjIn0sImF1ZCI6IndlYnNlcnZpY2VzQG1lcmNoYW50LmNvbSJ9.lyPo03P1nTQNohqqF3LZdLWnXoaIzgKMzjC14LWhJG8&

  Before you can trust the response, you need to check the signature returned matches the value expected. If not, it may have been modified by an unauthorised party.

The library you chose earlier to generate and verify the JWT included on your payment form can also be used to verify the JWT returned.

How this works

The signature is hashed using SHA-256, and as such, cannot be decoded. This means that to check the signature is correct, it will need to be re-calculated using the header and payload returned.
Providing the same secret is used during this process, the recalculated signature should match that returned in the response JWT. In summary:

  1. Base64URL decode JWT header
  2. Base64URL decode JWT payload
  3. Re-generate the signature by re-encoding the header, the payload and signing them with the secret.

Once this process has been completed, we recommend ensuring the errorcode value returned in the response is “0”, indicating success.

 


2. threedresponse - contains step-up authentication result (not always present)

The signature of the threedresponse will be verified by Trust Payments when sent in the subsequent AUTH request. It is imperative that is included in the AUTH request when returned in the authentication response. The following is an example of a threedresponse:

eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1YzEyODg0NWMxMWI5MjIwZGMwNDZlOGUiLCJpYXQiOjE2MzMwOTg4NzcsImV4cCI6MTYzMzEwNjA3NywianRpIjoiNGQyMjA5NGMtZjY3Mi00YTRjLWIwMTktYjhjZDY2ZDM0MzBiIiwiQ29uc3VtZXJTZXNzaW9uSWQiOiIwXzU2OTgwMzA1LTk1ZmQtNDNmOC05NzRlLTQ0NmFhMGU4MjgzNCIsIlJlZmVyZW5jZUlkIjoiMjQtMmJhNzBjYTMxZDMyYzI0ZGU4OGEzNTE4ZjE0NTMzY2FlOGViMjhhZjRhNDVlODBiODQwNmZkNGE4MTRjZmI0YSIsImF1ZCI6IjI0LTJiYTcwY2EzMWQzMmMyNGRlODhhMzUxOGYxNDUzM2NhZThlYjI4YWY0YTQ1ZTgwYjg0MDZmZDRhODE0Y2ZiNGEiLCJQYXlsb2FkIjp7IlZhbGlkYXRlZCI6dHJ1ZSwiUGF5bWVudCI6eyJUeXBlIjoiQ0NBIiwiUHJvY2Vzc29yVHJhbnNhY3Rpb25JZCI6Ilp6eDhxYzQzUEJGQXZGVXdlNDcwIiwiRXh0ZW5kZWREYXRhIjp7IkFtb3VudCI6IjEwMDAiLCJDQVZWIjoiTVRJek5EVTJOemc1TURFeU16UTFOamM0T1RBXHUwMDNkIiwiQ3VycmVuY3lDb2RlIjoiODI2IiwiRUNJRmxhZyI6IjA1IiwiVGhyZWVEU1ZlcnNpb24iOiIyLjEuMCIsIlBBUmVzU3RhdHVzIjoiWSIsIlNpZ25hdHVyZVZlcmlmaWNhdGlvbiI6IlkifX0sIkFjdGlvbkNvZGUiOiJTVUNDRVNTIiwiRXJyb3JOdW1iZXIiOjAsIkVycm9yRGVzY3JpcHRpb24iOiJTdWNjZXNzIn19.A5t9bo59kFKehQIwjaqQ2UAAqEdVlBCbI2ZbEFvUz98

 

Submit AUTH request using Webservices API

After the EMV 3DS authentication has been performed, you will need to submit an AUTH request to Trust Payments using our Webservices API to in order to process the payment.

  If you haven't done so already, we recommend reading our Getting started documentation to learn how to process a basic request with our Webservices API.

Click here to open this in a new tab.

You must read the schema table below and ensure the required fields are submitted in the request, as shown in the following example:

Authorisation field specification

  Field Format Description
table-required.png parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric (25) Value of the THREEDQUERY transactionreference returned in the jwt response you have verified above.

table-conditional.png

threedresponse
XPath: /operation/threedresponse
The format of this value is subject to change. We recommend you don't validate this value. The threedresponse field is returned when the customer is challenged during authentication for 3-D Secure versions 1 and 2, and must be submitted in the AUTH request if returned to your server.

Trust Payments verifies the signature of the threedresponse submitted and analyses the request to determine whether or not the cardholder was successfully authenticated on their card issuer’s ACS.

Failure to submit the threedresponse in the AUTH when returned in the authentication response may lead to the liability shift being forfeited.

 

Code example

Python PHP cURL Raw JSON Raw XML
#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
"sitereference": "test_site12345",
"requesttypedescriptions": ["AUTH"],
"orderreference": "My_Order_123",
"parenttransactionreference": "24-9-80061",
"threedresponse": "XXXXX"
}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Handle the Authorisation response

Finally, your server will be returned an Authorisation response.

{
"requestreference":"W23-n68rw97k",
"version":"1.00",
"response":[{
"transactionstartedtimestamp":"2021-10-01 14:34:35",
"parenttransactionreference":"24-9-80061",
"livestatus":"0",
"issuer":"Test Issuer",
"xid":"NmVxNGtsTDBkSVJzcmwrSnEyMFc=",
"dccenabled":"0",
"settleduedate":"2021-10-01",
"errorcode":"0",
"tid":"00000000",
"merchantnumber":"00000000",
"merchantcountryiso2a":"GB",
"status":"Y",
"transactionreference":"24-9-80061",
"merchantname":"Test Merchant",
"paymenttypedescription":"VISA",
"baseamount":"1050",
"enrolled":"Y",
"eci":"05",
"accounttypedescription":"ECOM",
"cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=",
"acquirerresponsecode":"00",
"requesttypedescription":"AUTH",
"securityresponsesecuritycode":"2",
"currencyiso3a":"GBP",
"authcode":"TEST",
"errormessage":"Ok",
"operatorname":"webservices@example.com",
"securityresponsepostcode":"2",
"maskedpan":"400000######1091",
"securityresponseaddress":"0",
"issuercountryiso2a":"US",
"settlestatus":"0"
}],
"secrand":"bsZP"
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request