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
-
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
-
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.
-
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
-
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
-
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
-
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.
Step 1. THREEDLOOKUP
THREEDLOOKUP Request
The following is an example of a THREEDLOOKUP request submitted using the Webservices API:
{
"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"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="THREEDLOOKUP">
<billing>
<payment type"VISA">
<expirydate>01/2038</expirydate>
<pan>4111110000000211</pan>
</payment>
<amount currencycode="GBP">23100</amount>
</billing>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
<sitereference>test_site12345</sitereference>
</operation>
</request>
</requestblock>
Field specification
Required | Field | Format | Length | Description |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha |
20 |
Submit "ECOM" (e-commerce) in this field. |
|
applicationtype XPath: /operation/applicationtype |
Alpha |
3 |
Submit one of the following supported values:
|
|
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) | |
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha |
3 |
The currency of the transaction. |
|
expirydate XPath: /billing/payment/expirydate |
Date MM/YYYY |
7 |
The expiry date printed on the card. | |
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. |
|
pan XPath: /billing/payment/pan |
Numeric |
12-19 |
This is the long number printed on the front of the customer’s card. | |
paymenttypedescription XPath: /billing/payment/@type |
Alpha |
20 |
Payment method (e.g. “VISA” or “MASTERCARD”). | |
requesttypedescription XPath: /@type |
Alpha |
20 |
You must submit “THREEDLOOKUP”, as shown in the request example. | |
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:
{
"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"
}
<responseblock version="3.67">
<requestreference>A3579dkvx</requestreference>
<response type="THREEDLOOKUP">
<operation>
<cachetoken>XXXXX</cachetoken>
</operation>
<billing>
<payment type="VISA">
<pan>411111######0211</pan>
</payment>
</billing>
<error>
<message>Ok</message>
<code>0</code>
</error>
<timestamp>2022-03-11 10:24:33</timestamp>
</response>
<secrand>hYWFMkiiAZ0wKHFZ</secrand>
</responseblock>
Field specification
Required | Field | Format | Length | Description |
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. | |
errorcode XPath: /error/code |
Numeric |
1-5 |
The error code should be used to determine if the request was successful or not.
|
|
errordata XPath: /error/data |
Alphanumeric |
255 |
Additional information to help troubleshoot the error. Only returned if there has been an error. |
|
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”. |
|
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. |
|
paymenttypedescription XPath: /billing/payment/@type |
Alpha |
20 |
Payment method (e.g. “VISA” or “MASTERCARD”). | |
requesttypedescription XPath: /@type |
Alpha |
20 |
“THREEDLOOKUP” is returned in the response. | |
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:
{
"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"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="THREEDQUERY">
<acquirer>
<acquirerbin>111111</acquirerbin>
</acquirer>
<merchant>
<merchantnumber>00000000</merchantnumber>
<termurl>https://termurl.com</termurl>
</merchant>
<billing>
<payment type"VISA">
<expirydate>01/2038</expirydate>
<pan>4111110000000211</pan>
</payment>
<amount currencycode="GBP">23100</amount>
</billing>
<customer>
<useragent>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.93 Safari/537.36</useragent>
</customer>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
<cachetoken>XXXXX</cachetoken>
<sitereference>test_site12345</sitereference>
</operation>
<threedsecure>
<threedscompind>U</threedscompind>
</threedsecure>
</request>
</requestblock>
Field specification
Required | Field | Format | Length | Description |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha |
20 |
Submit "ECOM" (e-commerce) in this field. | |
acquirerbin XPath: /acquirer/acquirerbin |
Alphanumeric |
11 |
This value correlates to the Acquirer BIN as defined by each Payment System or DS. |
|
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) | |
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). |
|
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha |
3 |
The currency of the transaction. |
|
expirydate XPath: /billing/payment/expirydate |
Date MM/YYYY |
7 |
The expiry date printed on the card. | |
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. |
|
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. |
|
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. |
|
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. |
|
pan XPath: /billing/payment/pan |
Numeric |
12-19 |
This is the long number printed on the front of the customer’s card. | |
paymenttypedescription XPath: /billing/payment/@type |
Alpha |
20 |
Payment method (e.g. “VISA” or “MASTERCARD”). | |
requesttypedescription XPath: /@type |
Alpha |
20 |
You must submit “THREEDQUERY”, as shown in the request example. | |
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. |
|
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). |
|
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;
{
"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"
}
<responseblock version="3.67">
<requestreference>A3579dkvx</requestreference>
<response type="THREEDQUERY">
<merchant>
<merchantcategorycode>7001</merchantcategorycode>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<merchantname>Test Merchant</merchantname>
<merchantnumber>00000000</merchantnumber>
<operatorname>webservices@example.com</operatorname>
</merchant>
<billing>
<payment type="VISA">
<issuercountry>US</issuercountry>
<pan>411111######0211</pan>
</payment>
</billing>
<error>
<message>Ok</message>
<code>0</code>
</error>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
<threedsecure>
<acsurl>https://www.example.com</acsurl>
<enrolled>Y</enrolled>
<md>Qzl3WVc1TVpXNW5kR2crUEcxbGMzTmhaMlZKWkQ1UVFWSmxjUzB4TWpnNU</md>
<pareq>eJxVUltPgzAU/sf9kxGkJ0ybTp3T1Pm0fA4CYVNLpTrqfoq2zH/QHgGHBLQ==</pareq>
<version>1.0.2</version>
<xid>VEw4TkFrakFYMmEreXdoZE5xZUU=</xid>
</threedsecure>
<settlement>
<settleduedate>2022-03-11</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<live>0</live>
<transactionreference>76-100-178</transactionreference>
<timestamp>2022-03-11 10:24:33</timestamp>
</response>
<secrand>hYWFMkiiAZ0wKHFZ</secrand>
</responseblock>
Field specification
Required | Field | Format | Length | Description |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha |
20 |
"ECOM" (e-commerce) will be returned. | |
acquirerresponsecode XPath: /acquirerresponsecode |
Numeric |
255 |
Contains information regarding errors returned during the 3-D Secure process. Only returned in case of an error. |
|
acquirerresponsemessage XPath: /acquirerresponsemessage |
Alphanumeric |
255 |
||
acsurl XPath: /threedsecure/acsurl |
URL |
1024 |
Customer's browser needs to be redirected to this URL as part of step 4 (step-up authentication). |
|
enrolled XPath: /threedsecure/enrolled |
Char |
1 |
The payment card's enrolment status:
|
|
errorcode XPath: /error/code |
Numeric |
1-5 |
The error code should be used to determine if the request was successful or not.
|
|
errordata XPath: /error/data |
Alphanumeric |
255 |
Additional information to help troubleshoot the error. Only returned if there has been an error. |
|
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”. |
|
issuercountryiso2a XPath: /billing/payment/issuercountry |
Alpha |
2 |
The country for the customer’s card issuer. |
|
livestatus XPath: /live |
Numeric |
1 |
|
|
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. |
|
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. |
|
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. |
|
merchantcountryiso2a XPath: /merchant/merchantcountryiso2a |
Alpha |
2 |
||
merchantname XPath: /merchant/merchantname |
Alphanumeric |
255 |
||
merchantnumber XPath: /merchant/merchantnumber |
Alphanumeric |
32 |
The merchant number that was used to process the transaction. Provided by the acquiring bank. | |
operatorname XPath: /merchant/operatorname |
Alphanumeirc |
255 |
The value of this field contains the name of the user that processed the request. | |
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. |
|
pareq XPath: /threedsecure/pareq |
Alphanumeric |
2048 |
The authentication request for the 3-D Secure transaction. |
|
paymenttypedescription XPath: /billing/payment/@type |
Alpha |
20 |
Payment method (e.g. “VISA” or “MASTERCARD”). | |
requesttypedescription XPath: /@type |
Alpha |
20 |
“THREEDQUERY” is returned in the response. | |
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. | |
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. |
|
threedversion XPath: /threedsecure/version |
Numeric |
6 |
Version of 3-D Secure used to authenticate the payment. (e.g. “1.0.2”) |
|
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. | |
transactionstartedtimestamp XPath: /timestamp |
Date time YYYY-MM-DD hh:mm:ss |
19 |
The time the request was processed. | |
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:
{
"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"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="THREEDRESULT">
<operation>
<md>Qzl3WVc1TVpXNW5kR2crUEcxbGMzTmhaMlZKWkQ1UVFWSmxjUzB4TWpnNU</md>
<parenttransactionreference>76-100-178</parenttransactionreference>
<pares>eJztWMmyo0iy3fMVaVVLWRazBGk3r1kwCIGEEPOwYxIgJgmQGL6+ke5YWVldVd1t9jaPjQgPdw/7gv+939/b8AdZWCeQ==</pares>
<sitereference>test_site12345</sitereference>
</operation>
</request>
</requestblock>
Field specification
Required | Field | Format | Length | Description |
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. |
|
parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens |
25 |
Allows you to specify the transactionreference of a previous request. Key details are inherited from this request. | |
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. |
|
requesttypedescription XPath: /@type |
Alpha |
20 |
You must submit “THREEDRESULT”, as shown in the request example. | |
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:
{
"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"
}
<responseblock version="3.67">
<requestreference>A3579dkvx</requestreference>
<response type="THREEDRESULT">
<merchant>
<merchantcategorycode>7001</merchantcategorycode>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<merchantname>Test Merchant</merchantname>
<merchantnumber>000111100001111</merchantnumber>
<operatorname>webservices@example.com</operatorname>
</merchant>
<billing>
<amount currencycode="GBP">23100</amount>
<payment type="VISA">
<issuercountry>US</issuercountry>
<pan>411111######0211</pan>
</payment>
</billing>
<threedsecure>
<cavv>dHJ1c3RwYXltZW50c2F1dGhlbnQ=</cavv>
<eci>02</eci>
<enrolled>Y</enrolled>
<status>Y</status>
<version>2.2.0</version>
<xid>VEw4TkFrakFYMmEreXdoZE5xZUU=</xid>
</threedsecure>
<settlement>
<settleduedate>2022-03-11</settleduedate>
</settlement>
<error>
<message>Ok</message>
<code>0</code>
</error>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
<parenttransactionreference>76-100-178</parenttransactionreference>
</operation>
<live>0</live>
<transactionreference>76-100-214</transactionreference>
<timestamp>2022-03-11 10:24:44</timestamp>
</response>
<secrand>hYWFMkiiAZ0wKHFZ</secrand>
</responseblock>
Field specification
Required | Field | Format | Length | Description |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha |
20 |
"ECOM" (e-commerce) will be returned. | |
baseamount XPath: /billing/amount |
Numeric |
3 |
The currency of the transaction. |
|
cavv XPath: /threedsecure/cavv |
Alphanumeric |
56 |
The unique Cardholder Authentication Verification Value (CAVV) associated with the transaction. | |
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha |
3 |
The currency of the transaction. |
|
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. | |
enrolled XPath: /threedsecure/enrolled |
Char |
1 |
Submit ‘Y’ to indicate that card is enrolled. See below for information on handling not-enrolled cards. | |
errorcode XPath: /error/code |
Numeric |
1-5 |
The error code should be used to determine if the request was successful or not.
|
|
errordata XPath: /error/data |
Alphanumeric |
255 |
Additional information to help troubleshoot the error. Only returned if there has been an error. |
|
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”. |
|
issuercountryiso2a XPath: /billing/payment/issuercountry |
Alpha |
2 |
The country for the customer’s card issuer. |
|
livestatus XPath: /live |
Numeric |
1 |
|
|
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. |
|
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. |
|
merchantcountryiso2a XPath: /merchant/merchantcountryiso2a |
Alpha |
2 |
||
merchantname XPath: /merchant/merchantname |
Alphanumeric |
255 |
||
merchantnumber XPath: /merchant/merchantnumber |
Alphanumeric |
32 |
The merchant number that was used to process the transaction. Provided by the acquiring bank. | |
operatorname XPath: /merchant/operatorname |
Alphanumeric |
255 |
The value of this field contains the name of the user that processed the request. | |
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. |
|
parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens |
25 |
Allows you to specify the transactionreference of a previous request. Key details are inherited from this request. | |
paymenttypedescription XPath: /billing/payment/@type |
Alpha |
20 |
Payment method (e.g. “VISA” or “MASTERCARD”). | |
requesttypedescription XPath: /@type |
Alpha |
20 |
“THREEDRESULT” is returned in the response. | |
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. | |
status XPath: /threedsecure/status |
Char |
1 |
Indicates whether or not the customer was authenticated on the card issuer’s ACS:
|
|
threedversion XPath: /threedsecure/version |
Numeric |
6 |
Version of 3-D Secure used to authenticate the payment. (e.g. “2.1.0”) | |
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. | |
transactionstartedtimestamp XPath: /timestamp |
Date time YYYY-MM-DD hh:mm:ss |
19 |
The time the transaction was processed. | |
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.
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.