Contents

Processing the AUTH manually

 

Our default and recommended implementation of 3-D Secure 2.0 is to fully utilise our JavaScript Client SDK, which will handle the THREEDQUERY and AUTH requests for you automatically, but if you prefer to have greater control over how the AUTH request is processed, we support the ability for you to process this manually.

 


 

Overview

 

  1. The customer enters their payment details on your checkout. The server-side payment form utilises our JavaScript to capture the payment details. Unlike the standard process described on the Getting started page, the “st.js” is instructed to only perform the 3-D Secure part of the process.

 

  1. If enrolled in 3-D Secure, the customer’s browser may display an overlay, where they are asked to complete some basic actions to authenticate their identity.

 

  1. Manually process the AUTH:
    • Handle the ACS response posted back to your server.
    • Manually submit the AUTH request.
    • Handle the AUTH response returned.

 

  1. Following this, the checkout will display a success message to the customer.

 


 

Modify the server-side payment form

In your form, you will need to ensure that “THREEDQUERY” is submitted in the requestTypes field (within st.Components), and “AUTH” is not submitted. Example:


st.Components({"requestTypes":["THREEDQUERY"]}); 

 

 

Handle the ACS response

After the customer has submitted the form, the “st.js” will open the overlay in the customer’s browser for authentication. The results of the authentication performed will be added to the form (with id=st-form), which will then be posted directly to your server, in the format of an application/x-www-form-urlencoded POST.

The response will contain a new JWT (returned in the field jwt). Your system will need to decode this token to view the fields pertaining to the outcome of the request. Click here for information on checking the fields returned.

The field threedresponse may also be returned. This is also in the format of a JWT (but you don’t need to decode this).


"jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1NjE2NDM5OTcsInBheWxvYWQiOnsicmVxdWVzdHJlZmVyZW5jZSI6Ilc0Mi10OXE2OHRleCIsInZlcnNpb24iOiIxLjAwIiwicmVzcG9uc2UiOlt7InRyYW5zYWN0aW9uc3RhcnRlZHRpbWVzdGFtcCI6IjIwMTktMDYtMjcgMTM6NTk6NTYiLCJjdXN0b21lcm91dHB1dCI6IlRIUkVFRFJFRElSRUNUIiwibGl2ZXN0YXR1cyI6IjAiLCJtZXJjaGFudG5hbWUiOiJUZXN0IFVuaXR0ZXN0IFNpdGUiLCJkY2NlbmFibGVkIjoiMCIsInNldHRsZWR1ZWRhdGUiOiIyMDE5LTA2LTI3IiwiZXJyb3Jjb2RlIjoiMCIsImFjcXVpcmVydHJhbnNhY3Rpb25yZWZlcmVuY2UiOiI3OHYyc2JtM250WVdrTUdDNmlnMCIsInRpZCI6IjI3ODgwMDAwIiwidGhyZWVkcGF5bG9hZCI6IlAuOTM5MDRhMDU5MDU0OTA1MTk1M2RjMTVjZGNhMmRkZjY3OTljNTViNzRmMzdhYmNlOTZiMDM2ZTNmOGFhYTgwNjJkOGQ2ZTI1ZjYzNmU2ZmQxYTA0MDQ4ZmRmZTgxMDU2MzIwNGQ0MDg5MDllODU4OWVjOTUwYWMzNjk1MmNjYTljOGRiN2Y3MTkxMWE4OWM3MDJkZmM3MDlmMmI5YzVkNCIsIm1lcmNoYW50bnVtYmVyIjoiMDAwMDAwMDAiLCJtZXJjaGFudGNvdW50cnlpc28yYSI6IkdCIiwidHJhbnNhY3Rpb25yZWZlcmVuY2UiOiI0Mi05LTgwMTA4IiwidGhyZWVkdmVyc2lvbiI6IjEuMC4yIiwicGF5bWVudHR5cGVkZXNjcmlwdGlvbiI6IlZJU0EiLCJhY3N1cmwiOiJodHRwczovLzBlYWZzdGFnLmNhcmRpbmFsY29tbWVyY2UuY29tL0VBRlNlcnZpY2UvanNwL3YxL3JlZGlyZWN0IiwiYWNjb3VudHR5cGVkZXNjcmlwdGlvbiI6IkVDT00iLCJhY3F1aXJlcnJlc3BvbnNlY29kZSI6IjAiLCJyZXF1ZXN0dHlwZWRlc2NyaXB0aW9uIjoiVEhSRUVEUVVFUlkiLCJpc3N1ZXIiOiJTZWN1cmVUcmFkaW5nIFRlc3QgSXNzdWVyMSIsIm1hc2tlZHBhbiI6IjQxMTExMSMjIyMjIzExMTEiLCJlcnJvcm1lc3NhZ2UiOiJPayIsIm9wZXJhdG9ybmFtZSI6ImxpdmUyX2F1dG9qd3QiLCJlbnJvbGxlZCI6IlkiLCJpc3N1ZXJjb3VudHJ5aXNvMmEiOiJVUyIsInNldHRsZXN0YXR1cyI6IjAifV0sInNlY3JhbmQiOiJoWnc0Z0hxUiJ9fQ.3IdX7n5n-bpoUtvxL133V7I_NldV15sxAj2F2blOAa4"
"threedresponse":"eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1YzEyODg0NWMxMWI5MjIwZGMwNDZlOGUiLCJpYXQiOjE1NjE2NDQwMDEsImV4cCI6MTU2MTY1MTIwMSwianRpIjoiZDYwY2I3NGItOGExMy00M2FlLTg3M2EtNDYyMTk2ZGEzNTRiIiwiQ29uc3VtZXJTZXNzaW9uSWQiOiIwXzAzOThkNTBmLTc4NWUtNDI5YS04MmU4LTA2NWMzYTYyMzJiMiIsIlJlZmVyZW5jZUlkIjoiNDItZWUwN2UwZTNjNmUwMGI5ZWNkNmRiNTUzOTUxZmE0NzUwNDQ3MWQzMmExOWM3MzZlZDJjZjExNGEzNjc4ODFjNCIsImF1ZCI6IjQyLWVlMDdlMGUzYzZlMDBiOWVjZDZkYjU1Mzk1MWZhNDc1MDQ0NzFkMzJhMTljNzM2ZWQyY2YxMTRhMzY3ODgxYzQiLCJQYXlsb2FkIjp7IlZhbGlkYXRlZCI6dHJ1ZSwiUGF5bWVudCI6eyJUeXBlIjoiQ0NBIiwiUHJvY2Vzc29yVHJhbnNhY3Rpb25JZCI6Ijc4djJzYm0zbnRZV2tNR0M2aWcwIiwiRXh0ZW5kZWREYXRhIjp7IkNBVlYiOiJBQUFCQVdGbG1RQUFBQUJqUldXWkVFRmdGejhcdTAwM2QiLCJFQ0lGbGFnIjoiMDUiLCJYSUQiOiJOemgyTW5OaWJUTnVkRmxYYTAxSFF6WnBaekFcdTAwM2QiLCJUaHJlZURTVmVyc2lvbiI6IjEuMC4yIiwiUEFSZXNTdGF0dXMiOiJZIiwiU2lnbmF0dXJlVmVyaWZpY2F0aW9uIjoiWSJ9fSwiQWN0aW9uQ29kZSI6IlNVQ0NFU1MiLCJFcnJvck51bWJlciI6MCwiRXJyb3JEZXNjcmlwdGlvbiI6IlN1Y2Nlc3MifX0.lEZ907NOdZrFrSax-Jm5gQXcj2Mdv-_XsGhTberZum4"

 

 

Submit the AUTH request

You will then need to submit an AUTH request to process the payment. This request must follow the structure shown in the example below. Of particular importance, the threedresponse field is required. This must contain the value of threedresponse (this is in JWT format), which is posted to your server as part of the st-form, as shown below:

 


{"alias":"[email protected]","version":"1.00","request":[{"orderreference":"order.ref","parenttransactionreference":"1-2-345","threedresponse":"XXXXX","sitereference":"test_site12345","requesttypedescription":"AUTH"}]}

 

Field specification

Field Type Length Required Comment
parenttransactionreference an Max 25 Yes Value of the transactionreference returned in the JWT of the THREEDQUERY response.
threedresponse n Undefined Conditional Take the JWT posted to your server in the threedresponse field and submit this in the threedresponse field in the AUTH.

This value must not be modified.

Secure Trading analyses the threedresponse submitted in the request to determine whether or not the cardholder was successfully authenticated on their card issuer’s ACS.

This is required, except if the transaction is a frictionless payment – in this case, you won’t be returned a threedresponse value to submit here.

 


 

Handle the AUTH response

Finally, your server will be returned an AUTH Response:


{"requestreference":"W23-n68rw97k","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 17:21:59","parenttransactionreference":"1-2-345","livestatus":"0","issuer":"SecureTrading Test Issuer1","xid":"NmVxNGtsTDBkSVJzcmwrSnEyMFc=","dccenabled":"0","settleduedate":"2016-12-08","errorcode":"0","tid":"00000000","merchantnumber":"00000000","merchantcountryiso2a":"GB","status":"Y","transactionreference":"1-2-346","merchantname":"Test Merchant","paymenttypedescription":"VISA","baseamount":"100","enrolled":"Y","eci":"05","accounttypedescription":"ECOM","cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"2","maskedpan":"411111######0211","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"bsZP"}