3DS API Field Specification

You must submit “THREEDLOOKUP” in this field.

You must submit "ECOM" (e-commerce) in this field.

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)

The currency of the transaction.

Click here for a full list of available currencies.

The expiry date printed on the card.

This is the long number printed on the front of the customer’s card.

Identifies your site on the Trust Payments system.

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

Submit one of the following supported values:

• "APP" - Payment using a mobile app.
• "WAP" - For browser-based payments.

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.

Submit one of the following supported values:

• "AMEX"
• "DELTA"
• "ELECTRON"
• "MAESTRO"
• "MASTERCARD"
• "MASTERCARDDEBIT"
• "PURCHASING"
• "VISA"

1

Indicates if transaction is flagged as debt repayment:

• 1 – Transaction is flagged as debt repayment.
• 0 – Transaction is not flagged as debt repayment.

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

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

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

One of the following values can be returned:

• "AMEX"
• "DELTA"
• "ELECTRON"
• "MAESTRO"
• "MASTERCARD"
• "MASTERCARDDEBIT"
• "PURCHASING"
• "VISA"

This field is returned during 3-D Secure version 2 authentication. This can be ignored, as you will define your own threednotificationurl to be used in step 2.

Version of 3-D Secure used to authenticate the payment. (e.g. “2.2.0”).

Additional information to help troubleshoot the error.

Only returned if there has been an error.

URL to which your 3D Server submits a HTTPS POST as part of upcoming step 2 (Method URL). This URL is provided by the ACS.

If threedmethodurl is not returned, but threedversion is returned with value 2.2.0 or higher, skip to step 3 (3-D Query).

You must submit “THREEDQUERY” in this field.

The exact content of the HTTP accept-header field as received from the cardholder’s user agent.

If you are using a Trust Payments (UK/FCA) acquiring account, submit one of the following values:

• "456896" - Visa
• "271708" – Mastercard
• "10000000232" - American Express

If you are using a Trust Payments (Malta) acquiring account, submit one of the following values:

• "408912" - Visa
• "529786" - Mastercard
• "10000000232" - American Express

Value representing the bit depth of the colour palette for displaying images, in bits per pixel.

Accepted values:

• 1
• 4
• 8
• 15
• 16
• 24
• 32
• 48

Whether or not the customer's browser can execute Java.

Accepted values: true, false.

Whether or not the customer's browser can execute JavaScript.

Accepted values: true, false.

Value representing the browser language as defined in IETF BCP47.

Total height of the customer's screen in pixels.

Required for Visa Secure Data Field Mandate.

Total width of the customer's screen in pixels.

Required for Visa Secure Data Field Mandate.

Time-zone offset in minutes between UTC and the customer's browser local time.

Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead.

e.g. If UTC -5 hours: 300 or +300

e.g. If UTC +5 hours: -300

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

challengewindowsize
XPath: /customer/challengewindowsize

Dimension of step-up authentication challenge pop-up window.

Accepted values:

• 01 - For 250x400
• 02 - For 390x400
• 03 - For 500x600
• 04 - For 600x400
• 05 - For full screen

The currency of the transaction.

Click here for a full list of available currencies.

The IP of the customer.

Required for Visa Secure Data Field Mandate.

Submit one of the following supported values:

• "AMEX"
• "DELTA"
• "ELECTRON"
• "MAESTRO"
• "MASTERCARD"
• "MASTERCARDDEBIT"
• "PURCHASING"
• "VISA"

Identifies your site on the Trust Payments system.

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

Indicates whether the 3DS Method successfully completed.

Accepted values:

• Y - Submit Y if step 2 (Method URL) was successfully completed.
• N - Submit N if threedmethodurl and threednotificationurl were returned in THREEDLOOKUP but step 2 (Method URL) was skipped.
• U - Submit U if threedmethodurl was not returned in THREEDLOOKUP.

Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

This is returned to you in the THREEDLOOKUP response (step 1).

255

The billing email address. This can then be used for correspondence with the customer. Maximum length of 255 (maximum of 64 characters before the”@” symbol).

Required for Visa Secure Data Field Mandate when billingtelephone is not provided.

127

The billing first name.

Required for Visa Secure Data Field Mandate.

127

The billing last name.

Required for Visa Secure Data Field Mandate.

20

• Numbers 0-9
• Spaces
• Special characters: + – ( )

Required for Visa Secure Data Field Mandate when billingemail is not provided.

25

127

25

25

127

127

127

The county entered for the billing address.

This is displayed as “State code (eg. NY)” on pages with "us_US" locale.

For US addresses, the state would be entered in this field.

Valid formats:

• Preferred: Two character state code, e.g. “NY”.
• Full state name (no abbreviations), e.g. “New York”.

25

2

1

• H = Home
• M = Mobile
• W = Work

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.

The information provided must match information used to register the account with Visa and Mastercard for 3-D Secure authentication.

4

Used to classify the type of goods and services offered by your business.

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.

The information provided must match information used to register the account with Visa and Mastercard for 3-D Secure authentication.

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.

The information provided must match information used to register the account with Visa and Mastercard for 3-D Secure authentication.

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.

The information provided must match information used to register the account with Visa and Mastercard for 3-D Secure authentication.

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

This field is returned if submitted in the request.

Fully qualified URL of 3DS Requestor website or customer care site. This data element provides additional information to the receiving 3-D Secure system if a problem arises and should provide contact information.

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.

The requestor id prefix "TRU93918", followed by “_”, and then the Merchant id (MID).
Example: "TRU93918_9991111111"

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.

The merchant id (MID) provided must match information used to register the account with Visa and Mastercard for 3-D Secure authentication.

In our testing environment, your system will need to submit the requestor id prefix "11111111" followed by "*", and then the Merchant id (MID).

Example: "11111111*9991111111"

In a live environment, this would be the acquirer's Visa Bank id (BID) followed by "*", and then the MID provided by the merchant's acquirer.

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.

The merchant id (MID) provided must match information used to register the account with Visa and Mastercard for 3-D Secure authentication.

Trust Payments assigned 3DS Requestor name for Mastercard, in the following format:

3DS Server name+"_"+Merchant name

e.g. "TrustPayments_Merchantname"

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.

The merchant name provided must match information used to register the account with Visa and Mastercard for 3-D Secure authentication.

Merchant name that you define.

e.g. "Test Merchant1 Ltd"

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.

The merchant name provided must match information used to register the account with Visa and Mastercard for 3-D Secure authentication.

1

Indicates if transaction is flagged as debt repayment:

• 1 – Transaction is flagged as debt repayment.
• 0 – Transaction is not flagged as debt repayment.

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.

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

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

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

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

Click here for a full list of country codes.

• 0 – Transaction processed using a test account.
• 1 – Transaction processed using a live account.

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.

This is the merchant category code (MCC) associated with the account as defined in the request.

Values returned depends on your account configuration.

This is the merchant country associated with the account as defined in the request.

Values returned depends on your account configuration.

This is the merchant name associated with the account as defined in the request.

Values returned depends on your account configuration.

This is the merchant number associated with the account as defined in the request.

Values returned depends on your account configuration.

One of the following values can be returned:

• "AMEX"
• "DELTA"
• "ELECTRON"
• "MAESTRO"
• "MASTERCARD"
• "MASTERCARDDEBIT"
• "PURCHASING"
• "VISA"

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.

• Y – Customer authenticated. The information necessary to process a transaction will be included in this response. You can proceed straight to step 5 to process the THREEDRESULT request.
• A – Authentication attempted but could not be completed. You can proceed straight to step 5 to process the THREEDRESULT request, but please note liability shift may not be available.
• U – Unable to perform authentication. Liability shift will not be in effect. If opt to continue, proceed to step 5 to process the THREEDRESULT request.
• N - Authentication was not successful. You must not proceed with payment.
• C – Challenge required for authentication. Proceed to step 4 and complete step-up authentication.
• R - Authentication was rejected. You must not proceed with payment.

Version of 3-D Secure used to authenticate the payment. (e.g. “2.2.0”)

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

Only returned in case of an error

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

Only returned in case of an error

Only returned if status is C (indicating challenge).

Customer's browser needs to be redirected to this URL as part of step 4 (step-up authentication).

Additional information to help troubleshoot the error.

Only returned if there has been an error.

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

This field is returned if submitted in the request.

Only returned if status is C (indicating challenge).

Contains info regarding the challenge user interface. To be passed to the ACS as part of step 4 (step-up authentication).

The value of the threedpayload is the creq required for step 4 (Challenge).

Identifies your site on the Trust Payments system.

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

The amount of the transaction in base units as submitted in the request, with no commas or decimal points, so £10 is submitted as 1000. (Max length may vary depending on your acquiring bank – Contact your bank for further info)

The currency of the transaction.

Click here for a full list of available currencies.

1

Indicates if transaction is flagged as debt repayment:

• 1 – Transaction is flagged as debt repayment.
• 0 – Transaction is not flagged as debt repayment.

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.

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

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

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

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

Click here for a full list of country codes.

• 0 – Transaction processed using a test account.
• 1 – Transaction processed using a live account.

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.

This is the merchant category code (MCC) associated with the account as defined in the request.

Values returned depends on your account configuration.

This is the merchant country associated with the account as defined in the request.

Values returned depends on your account configuration.

This is the merchant name associated with the account as defined in the request.

Values returned depends on your account configuration.

One of the following values can be returned:

• "AMEX"
• "DELTA"
• "ELECTRON"
• "MAESTRO"
• "MASTERCARD"
• "MASTERCARDDEBIT"
• "PURCHASING"
• "VISA"

• 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 - Authentication was not successful. You must not proceed with payment.
• R - Authentication was rejected. You must not proceed with payment.

Additional information to help troubleshoot the error.

Only returned if there has been an error.

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

This field is returned if submitted in the request.