1. Trust Payments
  2. TRU Security
  3. 3DS API

3-D Secure version 1 using 3DS API

Avatar
Michael Buckley

 3-D Secure v1 will be fully retired 14th October 2022. In the interest of security, and to ensure your transactions meet the PSD2 mandate, you must immediately migrate your solution to use 3-D Secure version 2 (EMV 3DS) if you have not already done so. Click here to learn how.

  This article is written for those processing transactions that are to be authenticated with 3-D Secure version 1. This is to be read in conjunction with our 3DS API documentation.

  Only Mastercard and Visa-branded cards are supported.

 

Process overview

standalone-3ds1-2306-01.svg

  1. THREEDLOOKUP

    Your system submits a THREEDLOOKUP request using Webservices API. The response determines whether the customer's card is enrolled in the 3-D Secure scheme and the version to be used for authentication. You will need to parse the cachetoken from the THREEDLOOKUP response, as this is required in the THREEDQUERY request (step 3).

      Click to scroll to this section

  2. Method URL

      This step is only required if threedversion is returned (with value 2.1.0 or higher) in the THREEDLOOKUP response.

    For 3-D Secure version 1, threedversion is not returned, proceed to step 3 below.

  3. THREEDQUERY

    This is to determine whether the card is enrolled in a 3-D Secure version 1 scheme and to initiate the authentication process. Your system submits a THREEDQUERY request using Webservices API containing the following fields:

    • cachetoken, returned in step 1 (THREEDLOOKUP).
    • termurl - The termurl is the endpoint that you define, for the customer's browser to be returned following authentication on the page hosted by the ACS.

    You will need to parse the THREEDQUERY response for the following fields:

    • acsurl - The customer's browser needs to be redirected to this URL as part of step 4 (step-up authentication).
    • md - Unique reference for the 3-D Secure transaction. This must be included in the subsequent HTTPS POST to the ACS (step 4).
    • pareq - The authentication request for the 3-D Secure transaction. This is required to be submitted in the HTTPS POST to ACS (step 4).

      Click to scroll to this section

  4. Challenge

    Your server will need to submit an HTTPS POST to the acsurl for authentication, including the values of fields md and pareq that were returned in the THREEDQUERY.

    Once completed, the customer's browser will be redirected to the termurl you define in step 3, including fields md (which will not be modified) and pares, which is the authentication response for the 3-D Secure transaction. It is used by Trust Payments to determine whether or not the customer has been authenticated by the card issuer.

      Click to scroll to this section

  5. THREEDRESULT

    Your server then submits a THREEDRESULT request using Webservices API, including the md, pares and the parenttransactionreference that references the THREEDQUERY from step 3.

    A THREEDRESULT response will include the authentication result data that you can use to determine whether it is safe to proceed with a payment.

      Click to scroll to this section

  6. AUTH

    Once the 3-D Secure process has completed, it is now time to process a transaction. Should you wish to proceed with the payment using the TRU Connect gateway, your server submits an AUTH request using Webservices API, including additional fields that you have received in the THREEDRESULT response.

    Click here to learn more.

 

             

 

Step 1. THREEDLOOKUP

THREEDLOOKUP Request

The following is an example of a THREEDLOOKUP request submitted using the Webservices API:

Raw JSON Raw XML
{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "accounttypedescription": "ECOM", 
    "baseamount": "23100", 
    "currencyiso3a": "GBP", 
    "expirydate": "01/2038", 
    "pan": "4111110000000211", 
    "paymenttypedescription": "VISA", 
    "requesttypedescription": "THREEDLOOKUP", 
    "sitereference": "test_site12345"
  }]
}

 

Field specification

Required Field Format Length Description
table-required.svg accounttypedescription
XPath: /operation/accounttypedescription		 Alpha

20

Submit "ECOM" (e-commerce) in this field.
table-optional.svg applicationtype
XPath: /operation/applicationtype		 Alpha

3

Submit one of the following supported values:

  • "APP" - Payment using a mobile app.
  • "WAP" - For browser-based payments.
table-required.svg baseamount
XPath: /billing/amount		 Numeric

13

 The amount of the transaction in base units, with no commas or decimal points, so £10 is submitted as 1000. This value must be greater than zero. (Max length may vary depending on your acquiring bank – Contact your bank for further info)
table-required.svg currencyiso3a
XPath: /billing/amount/@currencycode		 Alpha

3

The currency of the transaction.

Click here for a full list of available currencies.
table-required.svg expirydate
XPath: /billing/payment/expirydate		 Date MM/YYYY

7

 The expiry date printed on the card.
table-optional.svg orderreference
XPath: /merchant/orderreference		 Alphanumeric including symbols

25

 Your unique order reference that can be stored on the Trust Payments system.

Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction.
table-required.svg pan
XPath: /billing/payment/pan		 Numeric

12-19

 This is the long number printed on the front of the customer’s card.
table-required.svg paymenttypedescription
XPath: /billing/payment/@type		 Alpha

20

 Payment method (e.g. “VISA” or “MASTERCARD”).
table-required.svg requesttypedescription
XPath: /@type		 Alpha

20

 You must submit “THREEDLOOKUP”, as shown in the request example.
table-required.svg sitereference
XPath: /operation/sitereference		 Alphanumeric & underscore

50

Identifies your site on the Trust Payments system.

If you do not know your site reference, please contact our Support Team.

 

THREEDLOOKUP Response

The following is an example of a THREEDLOOKUP response returned:

Raw JSON Raw XML
{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "cachetoken": "XXXXX",
    "errorcode": "0",
    "errormessage": "Ok",
    "maskedpan": "411111######0211",
    "paymenttypedescription": "VISA",
    "requesttypedescription": "THREEDLOOKUP",
    "transactionstartedtimestamp": "2022-03-11 10:24:33"
  }],
  "secrand":"zO9"
}

 

Field specification

Required Field Format Length Description
table-returned.svg cachetoken
XPath: /operation/cachetoken		 Alphanumeric

64

 Unique identifier that represents the customer's card details on Trust Payment's system. This must be included in the THREEDQUERY request (step 3). It is valid for 15 minutes from when the THREEDLOOKUP response is returned.
table-returned.svg errorcode
XPath: /error/code		 Numeric

1-5

 The error code should be used to determine if the request was successful or not.
  • If the error code is “0” then the transaction was successful.
  • If the error code is not “0” then the transaction was not successful.

Click here for a full list of errorcode and message values.
table-conditional.svg errordata
XPath: /error/data		 Alphanumeric

255

Additional information to help troubleshoot the error.

Only returned if there has been an error.
table-returned.svg errormessage
XPath: /error/message		 Alphanumeric

255

 This provides a brief explanation as to the cause of the error.

For successful transactions, this is returned as “Ok”.

Click here for a full list of errorcode and message values.
table-returned.svg maskedpan
XPath: /billing/payment/pan		 Alphanumeric including “#”

12-19

The maskedpan field represents the customer’s unique token number used to perform the transaction. The value of maskedpan field is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
table-returned.svg paymenttypedescription
XPath: /billing/payment/@type		 Alpha

20

 Payment method (e.g. “VISA” or “MASTERCARD”).
table-returned.svg requesttypedescription
XPath: /@type		 Alpha

20

 “THREEDLOOKUP” is returned in the response.
table-returned.svg transactionstartedtimestamp
XPath: /timestamp		 Date time YYYY-MM-DD hh:mm:ss

19

 The time the request was processed.

 

             

 

Step 2. Method URL

  This step is only required if threedversion is returned (with value 2.1.0 or higher) in the THREEDLOOKUP response. For documentation on this step, please refer to our 3DS API documentation.

If threedversion is not returned, proceed to step 3 below, where it can be determined whether the card is enrolled in a 3-D Secure version 1 scheme.

             

 

Step 3. THREEDQUERY

THREEDQUERY Request

The following is an example of a THREEDQUERY request submitted using the Webservices API:

Raw JSON Raw XML
{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "accounttypedescription": "ECOM",
    "acquirerbin": "111111",
    "baseamount": "23100",
    "cachetoken": "XXXXX",
    "currencyiso3a": "GBP",
    "expirydate": "01/2038",
    "merchantnumber": "00000000",
    "pan": "4111110000000211",
    "paymenttypedescription": "VISA",
    "requesttypedescription": "THREEDQUERY",
    "sitereference": "test_site12345",
    "termurl": "https://termurl.com",
    "threedscompind": "U",
    "useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.93 Safari/537.36"
  }]
}

 

Field specification

Required Field Format Length Description
table-required.svg accounttypedescription
XPath: /operation/accounttypedescription		 Alpha

20

 Submit "ECOM" (e-commerce) in this field.
table-required.svg acquirerbin
XPath: /acquirer/acquirerbin		 Alphanumeric

11

 This value correlates to the Acquirer BIN as defined by each Payment System or DS.
table-required.svg baseamount
XPath: /billing/amount		 Numeric

13

 The amount of the transaction in base units, with no commas or decimal points, so £10 is submitted as 1000. This value must be greater than zero. (Max length may vary depending on your acquiring bank – Contact your bank for further info)
table-required.svg cachetoken
XPath: /operation/cachetoken		 Alphanumeric

64

Unique identifier that represents the customer's card details on Trust Payment's system. It is valid for 15 minutes from when the THREEDLOOKUP response is returned.

This is returned to you in the THREEDLOOKUP response (step 1).
table-required.svg currencyiso3a
XPath: /billing/amount/@currencycode		 Alpha

3

The currency of the transaction.

Click here for a full list of available currencies.
table-required.svg expirydate
XPath: /billing/payment/expirydate		 Date MM/YYYY

7

 The expiry date printed on the card.
table-optional.svg merchantcountryiso2a*
XPath: /merchant/merchantcountryiso2a		 Alpha

2

Country code associated with your account.

If not submitted, we'll use the data stored in our records by default. Otherwise, you can submit this field to override this value on a per-request basis.
table-optional.svg merchantname
XPath: /merchant/merchantname		 Alphanumeric

255

Name associated with your account with Trust Payments.

If not submitted, we'll use the data stored in our records by default. Otherwise, you can submit this field to override this value on a per-request basis.
table-optional.svg merchantnumber
XPath: /merchant/merchantnumber		 Alphanumeric

32

The merchant number that was used to process the transaction. Provided by the acquiring bank.

If not submitted, we'll use the data stored in our records by default. Otherwise, you can submit this field to override this value on a per-request basis.
table-optional.svg orderreference
XPath: /merchant/orderreference		 Alphanumeric including
symbols

25

Your unique order reference that can be stored on the Trust Payments system.

This field is returned if submitted in the request.
table-required.svg pan
XPath: /billing/payment/pan		 Numeric

12-19

 This is the long number printed on the front of the customer’s card.
table-required.svg paymenttypedescription
XPath: /billing/payment/@type		 Alpha

20

 Payment method (e.g. “VISA” or “MASTERCARD”).
table-required.svg requesttypedescription
XPath: /@type		 Alpha

20

 You must submit “THREEDQUERY”, as shown in the request example.
table-required.svg sitereference
XPath: /operation/sitereference		 Alphanumeric
& underscore

50

Identifies your site on the Trust Payments system.

If you do not know your site reference, please contact our Support Team.
table-required.svg termurl
XPath: /merchant/termurl		 URL

1024

This URL is used to instruct the card issuer where to send the customer’s browser after they have been authenticated on the card issuer’s ACS (for step-up authentication).
table-required.svg useragent
XPath: /customer/useragent		 Alphanumeric

2048

Exact content of the HTTP user-agent header. If length submitted exceeds max length 2048, the 3-D Secure server truncates the excess portion.

 

THREEDQUERY Response

The following is an example of a THREEDQUERY request submitted using the Webservices API;

Raw JSON Raw XML
{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "accounttypedescription": "ECOM", 
    "acsurl": "https://www.example.com",
    "enrolled": "Y", 
    "errorcode": "0", 
    "errormessage": "Ok", 
    "issuercountryiso2a": "US", 
    "livestatus": "0", 
    "maskedpan": "411111######0211", 
    "md": "Qzl3WVc1TVpXNW5kR2crUEcxbGMzTmhaMlZKWkQ1UVFWSmxjUzB4TWpnNU", 
    "merchantcategorycode": "7001", 
    "merchantcountryiso2a": "GB", 
    "merchantname": "Test Merchant", 
    "merchantnumber": "00000000", 
    "operatorname": "webservices@example.com", 
    "pareq": "eJxVUltPgzAU/sf9kxGkJ0ybTp3T1Pm0fA4CYVNLpTrqfoq2zH/QHgGHBLQ==", 
    "paymenttypedescription": "VISA", 
    "requesttypedescription": "THREEDQUERY", 
    "settleduedate": "2022-03-11", 
    "settlestatus": "0", 
    "threedversion": "1.0.2", 
    "transactionreference": "76-100-178", 
    "transactionstartedtimestamp": "2022-03-11 10:24:33",
    "xid": "VEw4TkFrakFYMmEreXdoZE5xZUU="
  }],
  "secrand":"zO9"
}

 

Field specification

Required Field Format Length Description
table-returned.svg accounttypedescription
XPath: /operation/accounttypedescription		 Alpha

20

 "ECOM" (e-commerce) will be returned.
table-conditional.svg acquirerresponsecode
XPath: /acquirerresponsecode		 Numeric

255

Contains information regarding errors returned during the 3-D Secure process.

Only returned in case of an error.
table-conditional.svg acquirerresponsemessage
XPath: /acquirerresponsemessage		 Alphanumeric

255
table-returned.svg acsurl
XPath: /threedsecure/acsurl		 URL

1024

Customer's browser needs to be redirected to this URL as part of step 4 (step-up authentication).
table-returned.svg enrolled
XPath: /threedsecure/enrolled		 Char

1

The payment card's enrolment status:

  • Y - The customer's card is enrolled.
  • N - The customer's card is not enrolled.
  • U - Unable to determine if card is enrolled.
  • B - Merchant authentication rule is triggered to bypass authentication in this use case.
table-returned.svg errorcode
XPath: /error/code		 Numeric

1-5

 The error code should be used to determine if the request was successful or not.
  • If the error code is “0” then the transaction was successful.
  • If the error code is not “0” then the transaction was not successful.

Click here for a full list of errorcode and message values.
table-conditional.svg errordata
XPath: /error/data		 Alphanumeric

255

Additional information to help troubleshoot the error.

Only returned if there has been an error.
table-returned.svg errormessage
XPath: /error/message		 Alphanumeric

255

 This provides a brief explanation as to the cause of the error.

For successful transactions, this is returned as “Ok”.

Click here for a full list of errorcode and message values.
table-returned.svg issuercountryiso2a
XPath: /billing/payment/issuercountry		 Alpha

2

The country for the customer’s card issuer.
This will be in ISO2A format.

Click here for a full list of country codes.
table-returned.svg livestatus
XPath: /live		 Numeric

1
  • 0 – Transaction processed using a test account.
  • 1 – Transaction processed using a live account.
table-returned.svg maskedpan
XPath: /billing/payment/pan		 Alphanumeric including “#”

12-19

The maskedpan field represents the customer’s unique token number used to perform the transaction. The value of maskedpan field is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
table-returned.svg md
XPath: /threedsecure/md		 Alphanumeric

1024

This is a unique reference for the 3-D Secure transaction. It is returned if the card is enrolled in the card issuer’s 3-D Secure scheme, and must be included in the subsequent HTTPS POST to the ACS (step 4). The md field must remain unaltered throughout the life-cycle of a transaction, otherwise this may forfeit the liability shift.
table-returned.svg merchantcategorycode
XPath: /merchant/merchantcategorycode		 Alphanumeric

255

These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team.

Values returned depends on your account configuration.
table-returned.svg merchantcountryiso2a
XPath: /merchant/merchantcountryiso2a		 Alpha

2
table-returned.svg merchantname
XPath: /merchant/merchantname		 Alphanumeric

255
table-returned.svg merchantnumber
XPath: /merchant/merchantnumber		 Alphanumeric

32

 The merchant number that was used to process the transaction. Provided by the acquiring bank.
table-returned.svg operatorname
XPath: /merchant/operatorname		 Alphanumeirc

255

 The value of this field contains the name of the user that processed the request.
table-conditional.svg orderreference
XPath: /merchant/orderreference		 Alphanumeric including symbols

25

Your unique order reference that can be stored on the Trust Payments system.

This field is returned if submitted in the request.
table-returned.svg pareq
XPath: /threedsecure/pareq		 Alphanumeric

2048

The authentication request for the 3-D Secure transaction.
When sending the customer’s browser to the card issuer’s ACS (step 4), your system will need to include the pareq in the HTTPS POST.
table-returned.svg paymenttypedescription
XPath: /billing/payment/@type		 Alpha

20

 Payment method (e.g. “VISA” or “MASTERCARD”).
table-returned.svg requesttypedescription
XPath: /@type		 Alpha

20

 “THREEDQUERY” is returned in the response.
table-returned.svg settleduedate
XPath: /settlement/settleduedate		 Date YYYY-MM-DD

10

 The date on which the transaction will be settled, if the subsequent payment is processed through the TRU Connect gateway, unless overridden in the AUTH.
table-returned.svg settlestatus
XPath: /settlement/settlestatus		 Numeric

3

This is the assigned settlestatus value, in the event the subsequent payment is processed through the TRU Connect gateway, unless overridden in the AUTH. To learn more about settlestatus, click here.
table-returned.svg threedversion
XPath: /threedsecure/version		 Numeric

6

Version of 3-D Secure used to authenticate the payment. (e.g. “1.0.2”)
table-returned.svg transactionreference
XPath: /transactionreference		 Alphanumeric including hyphens

25

 A unique reference for the transaction assigned by Trust Payments. You will need this reference to perform a refund or update the transaction.
table-returned.svg transactionstartedtimestamp
XPath: /timestamp		 Date time YYYY-MM-DD hh:mm:ss

19

 The time the request was processed.
table-returned.svg xid
XPath: /threedsecure/xid		 Alphanumeric

255

The unique identifier for the transaction, assigned by the MPI (Merchant Plug-In).

 

             

 

Step 4. Challenge

To perform step-up authentication, you will need to create a form with action set to acsurl value, which was returned in the THREEDQUERY response. This form will need contain the following fields:

  • md - Unique reference for the 3-D Secure transaction (parsed from THREEDQUERY response).
  • pareq - The authentication request for the 3-D Secure transaction (parsed from THREEDQUERY response).
  • termurl - The URL to where the card issuer redirects the customer’s browser after they have been authenticated on the card issuer’s ACS (must be same value as submitted in THREEDQUERY request).

Once the form is submitted, the customer would then be redirected to a page hosted by the ACS, where they would be expected to perform step-up authentication, typically by entering a PIN and/or password previously agreed with their card issuer.

Following this, the customer's browser is redirected to the termurl defined in the form above. This redirect will include:

  • md - You will need to check this matches the unique value included in the form to the ACS, as described above.
  • pares - The value returned should not be treated as the final authentication result. You should log the value of this field alongside the md. You will receive the final authentication response as part of step 5 (3-D Result).

 

             

 

Step 5. THREEDRESULT

THREEDRESULT Request

The following is an example of a THREEDRESULT request submitted using the Webservices API:

Raw JSON Raw XML
{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "md": "Qzl3WVc1TVpXNW5kR2crUEcxbGMzTmhaMlZKWkQ1UVFWSmxjUzB4TWpnNU",
    "parenttransactionreference": "76-100-178",
    "pares": "eJztWMmyo0iy3fMVaVVLWRazBGk3r1kwCIGEEPOwYxIgJgmQGL6+ke5YWVldVd1t9jaPjQgPdw/7gv+939/b8AdZWCeQ==",
    "requesttypedescription": "THREEDRESULT",
    "sitereference": "test_site12345"
  }]
}

 

Field specification

Required Field Format Length Description
table-required.svg md
XPath: /operation/md		 Alphanumeric

1024

This is a unique reference for the 3-D Secure transaction, first returned in the THREEDQUERY response (step 3). The md field must remain unaltered throughout the life-cycle of a transaction, otherwise this may forfeit the liability shift.
table-required.svg parenttransactionreference
XPath: /operation/parenttransactionreference		 Alphanumeric
& hyphens

25

 Allows you to specify the transactionreference of a previous request. Key details are inherited from this request.
table-required.svg pares
XPath: /operation/pares		 Alphanumeric

2048

Must be the value returned in the pares field of the HTTPS POST from the card issuer’s ACS, otherwise this may forfeit the liability shift.
table-required.svg requesttypedescription
XPath: /@type		 Alpha

20

 You must submit “THREEDRESULT”, as shown in the request example.
table-required.svg sitereference
XPath: /operation/sitereference		 Alphanumeric

50

Identifies your site on the Trust Payments system.

If you do not know your site reference, please contact our Support Team.

 

THREEDRESULT Response

The following is an example of a THREEDRESULT response returned:

Raw JSON Raw XML
{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "accounttypedescription": "ECOM", 
    "baseamount": "23100", 
    "cavv": "dHJ1c3RwYXltZW50c2F1dGhlbnQ=", 
    "currencyiso3a": "GBP", 
    "eci": "02", 
    "enrolled": "Y", 
    "errorcode": "0", 
    "errormessage": "Ok", 
    "issuercountryiso2a": "US", 
    "livestatus": "0", 
    "maskedpan": "411111######0211", 
    "merchantcategorycode": "7001", 
    "merchantcountryiso2a": "GB", 
    "merchantname": "Test Merchant", 
    "merchantnumber": "000111100001111", 
    "operatorname": "webservices@example.com", 
    "parenttransactionreference": "76-100-178", 
    "paymenttypedescription": "VISA", 
    "requesttypedescription": "THREEDRESULT", 
    "settleduedate": "2022-03-11", 
    "status": "Y", 
    "threedversion": "2.2.0", 
    "transactionreference": "76-100-214", 
    "transactionstartedtimestamp": "2022-03-11 10:24:44",
    "xid": "VEw4TkFrakFYMmEreXdoZE5xZUU="
  }],
  "secrand":"zO9"
}

 

Field specification

Required Field Format Length Description
table-returned.svg accounttypedescription
XPath: /operation/accounttypedescription		 Alpha

20

"ECOM" (e-commerce) will be returned.
table-returned.svg baseamount
XPath: /billing/amount		 Numeric

3

The currency of the transaction.

Click here for a full list of available currencies.

table-returned.svg cavv
XPath: /threedsecure/cavv		 Alphanumeric

56

The unique Cardholder Authentication Verification Value (CAVV) associated with the transaction.
table-returned.svg currencyiso3a
XPath: /billing/amount/@currencycode		 Alpha

3

The currency of the transaction.

Click here for a full list of available currencies.

table-returned.svg eci
XPath: /threedsecure/eci		 Alphanumeric

2

The ECI (E-Commerce Indicator) security level associated with the transaction. Click here to learn more about possible ECI values.
table-returned.svg enrolled
XPath: /threedsecure/enrolled		 Char

1

Submit ‘Y’ to indicate that card is enrolled. See below for information on handling not-enrolled cards.
table-returned.svg errorcode
XPath: /error/code		 Numeric

1-5

The error code should be used to determine if the request was successful or not.
  • If the error code is “0” then the transaction was successful.
  • If the error code is not “0” then the transaction was not successful.

Click here for a full list of errorcode and message values.

table-conditional.svg errordata
XPath: /error/data		 Alphanumeric

255

Additional information to help troubleshoot the error.

Only returned if there has been an error.

table-returned.svg errormessage
XPath: /error/message		 Alphanumeric

255

This provides a brief explanation as to the cause of the error.

For successful transactions, this is returned as “Ok”.

Click here for a full list of errorcode and message values.

table-returned.svg issuercountryiso2a
XPath: /billing/payment/issuercountry		 Alpha

2

The country for the customer’s card issuer.
This will be in ISO2A format.

Click here for a full list of country codes.

table-returned.svg livestatus
XPath: /live		 Numeric

1

  • 0 – Transaction processed using a test account.
  • 1 – Transaction processed using a live account.
table-returned.svg maskedpan
XPath: /billing/payment/pan		 Alphanumeric including “#”

12-19

The maskedpan field represents the customer’s unique token number used to perform the transaction. The value of maskedpan field is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
table-returned.svg merchantcategorycode
XPath: /merchant/merchantcategorycode		 Alphanumeric

255

These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team.

Values returned depends on your account configuration.

table-returned.svg merchantcountryiso2a
XPath: /merchant/merchantcountryiso2a		 Alpha

2

table-returned.svg merchantname
XPath: /merchant/merchantname		 Alphanumeric

255

table-returned.svg merchantnumber
XPath: /merchant/merchantnumber		 Alphanumeric

32

The merchant number that was used to process the transaction. Provided by the acquiring bank.
table-returned.svg operatorname
XPath: /merchant/operatorname		 Alphanumeric

255

The value of this field contains the name of the user that processed the request.
table-returned.svg orderreference
XPath: /merchant/orderreference		 Alphanumeric including
symbols (25)

25

Your unique order reference that can be stored on the Trust Payments system.

This field is returned if submitted in the request.

table-returned.svg parenttransactionreference
XPath: /operation/parenttransactionreference		 Alphanumeric
& hyphens

25

Allows you to specify the transactionreference of a previous request. Key details are inherited from this request.
table-returned.svg paymenttypedescription
XPath: /billing/payment/@type		 Alpha

20

Payment method (e.g. “VISA” or “MASTERCARD”).
table-returned.svg requesttypedescription
XPath: /@type		 Alpha

20

“THREEDRESULT” is returned in the response.
table-returned.svg settleduedate
XPath: /settlement/settleduedate		 Date YYYY-MM-DD

10

The date on which the transaction will be settled, if the subsequent payment is processed through the TRU Connect gateway, unless overridden in the AUTH.
table-returned.svg status
XPath: /threedsecure/status		 Char

1

Indicates whether or not the customer was authenticated on the card issuer’s ACS:
  • Y – Customer authenticated. You can proceed to step 6 (Authorisation) and process a payment using the fields returned in this response.
  • A – Authentication attempted but could not be completed. You can proceed to step 6 (Authorisation) and process a payment using the fields returned in this response, but please note liability shift may not be available.
  • U – Unable to perform authentication. You can opt to process the payment but liability shift will not be in effect.
  • N - Unauthenticated. You can opt to process the payment but liability shift will not be in effect.
  • R - Authentication was rejected. You must not proceed with payment.
table-returned.svg threedversion
XPath: /threedsecure/version		 Numeric

6

Version of 3-D Secure used to authenticate the payment. (e.g. “2.1.0”)
table-returned.svg transactionreference
XPath: /transactionreference		 Alphanumeric including
hyphens

25

A unique reference for the transaction assigned by Trust Payments. You will need this reference to perform a refund or update the transaction.
table-returned.svg transactionstartedtimestamp
XPath: /timestamp		 Date time YYYY-MM-DD hh:mm:ss

19

The time the transaction was processed.
table-returned.svg xid
XPath: /threedsecure/xid		 Alphanumeric

255

The unique identifier for the transaction, assigned by the MPI (Merchant Plug-In).

 

             

 

Step 6. AUTH

Once the 3-D Secure process has completed, it is now time to process a transaction. Should you wish to proceed with the payment using the TRU Connect gateway, your server submits an AUTH request using Webservices API, including additional fields that you have received in the THREEDRESULT response.

Click here to learn more.

 

             

 

Testing

  When testing your 3DS API integration using our sandbox, please ensure you perform all test cases listed in the following supplement: Trust Payments 3DS Server Testing Resources

  We're here to help

If you need assistance during integration, please contact our Support Team.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Articles in this section