AUTH

The following documentation explains how to manually submit an AUTH request using our Webservices API.

If you are already processing e-commerce payments using our JavaScript Library (using 3-D Secure v2), you no longer need to manually perform the AUTH request described herein (as the JavaScript Library will automatically perform the authorisation).

 

Requirements

  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.

  All businesses within the EEA (European Economic Area) are mandated to use 3-D Secure when processing e-commerce transactions, as part of the PSD2 mandate.

To process an e-commerce transaction that is authenticated with 3-D Secure, you will need to utilise our JavaScript Library instead of the solution described below. Click here to get started.

The following content should only be utilised by merchants processing Mail or Telephone Order (MOTO) paymentsMerchant Initiated Transactions (MIT), or other workflows that are exempt from the PSD2 mandate.

  ECOM (e-Commerce) Maestro transactions require the implementation of 3-D Secure in order to be processed successfully.

To perform 3-D Secure, you will need to utilise our JavaScript Library. Click here to get started.

  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 AUTH and ACCOUNTCHECK requests.

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.

 

AUTH request

Example

To successfully process an AUTH request, you must follow the specification below:

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"],
"accounttypedescription": "ECOM",
"currencyiso3a": "GBP",
"baseamount": "1050",
"orderreference": "My_Order_123",
"billingfirstname": "Joe",
"billinglastname": "Bloggs",
"pan": "4111111111111111",
"expirydate": "12/2020",
"securitycode": "123"
}

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.

  When testing the AUTH request, ensure you submit your test sitereference. This ensures that transactions are processed to our test bank and no money will change hands. When you go live, you will need to swap out your test sitereference for your live sitereference.

Click here for test card numbers you can submit in AUTH requests while testing.

 

Field specification

Operation

The following fields relate to the type of request submitted:

  Field Format Description
table-required.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20)

The type of account to be used:

  • “ECOM” – E-commerce
  • “MOTO” – Mail or Telephone Order
  • “RECUR” – Recurring transactions
table-optional.png authmethod
XPath: /operation/authmethod
Alpha (11)

Auth methods are used to specify how a transaction is to be processed by the card issuer. Each authmethod has a different set of requirements. Click the following links to learn more:

table-conditional.png credentialsonfile
XPath: /operation/credentialsonfile
Numeric (1) The allowed values for this field are 0, 1 and 2.
  • “0” – Not eligible for CoF, or no intention of re-using credentials at a later time.
  • “1” – Transaction credentials flagged as available for future use.
  • “2” – Payment using previously-stored credentials.

This is required for transactions where the merchant is utilising Credentials on File (CoF). If the transaction is not eligible for CoF, or you do not wish to use credentials for future transactions, you can omit this field.

table-conditional.png initiationreason
XPath: /operation/initiationreason
Char (1)

This is required when processing a Merchant Initiated Transaction (MIT).

Allows you to assign a reason for a Merchant Initiated Transaction (MIT).

Do not submit when processing a Customer Initiated Transaction (CIT).

The allowed values for this field are “A”, “C”, “D”, “S” and “X”.

  • “A” – Reauthorisation
  • “C” – Unscheduled payment
  • “D” – Delayed Charges
  • “S” – Resubmission
  • “X” – No-show (for a hotel booking)

Click here for further information on the different initiationreason values.

Note: You must ensure the initiationreason submitted in the request correctly represents the reason for the new payment. Visa may introduce new values to this list in the future. Please refer to Visa’s own documentation for further information.

table-optional.png 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.png requesttypedescriptions
XPath: /@type
Alpha (20) You must submit “AUTH”, as shown in the request example.
table-required.png 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.

Payment

The following fields contain the customer’s payment details:

  Field Format Description
table-required.png 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.png currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3)

The currency of the transaction.

Click here for a full list of available currencies.

If the currency is submitted in a child request, it must be the same value as the parent transaction.

table-required.png expirydate
XPath: /billing/payment/expirydate
Date MM/YYYY The expiry date printed on the card.
table-required.png pan
XPath: /billing/payment/pan
Numeric (12-19) This is the long number printed on the front of the customer’s card.
table-optional.png paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) Payment method (e.g. “VISA” or “MASTERCARD”).
table-optional.png securitycode
XPath: /billing/payment/securitycode
Numeric (3-4) This is the three digit security code printed on the back of the card.

(For AMEX cards, this is a 4 digit code found on the front of the card)

This field is not strictly required by Trust Payments, but it is highly recommended for the processing of security code checks.

Additionally, some banks may decline the payment if the security code is not present.

Merchant

The following fields relate to your account configuration and allow you to configure custom unique references for your request:

  Field Format Description
table-optional.png chargedescription
XPath: /merchant/chargedescription
Alphanumeric including
symbols (25)

This is a description of the payment that appears on the customer’s bank statement.

Only supported by certain acquiring banks.

Specification of this field will depend on your acquiring bank.

Click here for further information.

 Valid characters:

  • Uppercase/lowercase A-Z
  • Numbers 0-9
  • Spaces
  • Punctuation: + – _ . @ ( )
table-optional.png merchantemail
XPath: /merchant/email
Email (255) The merchant’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
table-optional.png operatorname
XPath: /merchant/operatorname
Alphanumeric (255) The value of this field contains the name of the user that processed the request. By default, this is the Web Services username included in the request. This can be overridden with a custom value by passing through this field in the request (optional).
table-optional.png orderreference
XPath: /merchant/orderreference
Alphanumeric including
symbols (25)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.
Your unique order reference that can be stored on the Trust Payments system.

Note: This can be updated at a later time (only if transaction is pending settlement).

Billing

The following fields contain the customer’s billing details:

  Field Format Description
table-optional.png billingpremise
XPath: /billing/premise
Alphanumeric including
symbols (25)
The house number or first line of the customer’s billing address.
table-optional.png billingstreet
XPath: /billing/street
Alphanumeric including
symbols (127)
The street entered for the customer’s billing address.
table-optional.png billingtown
XPath: /billing/town
Alphanumeric including
symbols (127)
The town entered for the customer’s billing address.
table-optional.png billingcounty
XPath: /billing/county
Alphanumeric including
symbols (127)
The county entered for the customer’s billing address. For US addresses, the state would be entered in this field. Valid formats:
  • Preferred: Two character state code, e.g. “NY”.
  • Full state name, e.g. “New York”.
table-optional.png billingcountryiso2a
XPath: /billing/country
Alpha (2)

The country for the customer’s billing address. This will need to be in ISO2A format.

Click here for a full list of country codes.

table-optional.png billingpostcode
XPath: /billing/postcode
Alphanumeric (25)

The postcode entered for the customer’s billing address.

If the country provided is not United States, Great Britain or Canada, or if no country is provided, the postcode field is not validated.

table-optional.png billingemail
XPath: /billing/email
Email (255) The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
table-optional.png billingtelephonetype
XPath: /billing/telephone/@type
Char (1) The type of telephone number. The options available are:
  • H = Home
  • M = Mobile
  • W = Work
table-optional.png billingtelephone
XPath: /billing/telephone
Alphanumeric including
symbols (20)
The customer’s telephone number. Valid characters:
  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
table-optional.png billingprefixname
XPath: /billing/name/prefix
Alphanumeric including
symbols (25)
The prefix of the customer’s billing name (e.g. Mr, Miss, Dr).
table-conditional.png billingfirstname
XPath: /billing/name/first
Alphanumeric including
symbols (127)

The customer’s billing first name.

Required for gaming merchants.

table-optional.png billingmiddlename
XPath: /billing/name/middle
Alphanumeric including
symbols (127)
The customer’s billing middle name(s).
table-conditional.png billinglastname
XPath: /billing/name/last
Alphanumeric including
symbols (127)

The customer’s billing last name.

Required for gaming merchants.

table-optional.png billingsuffixname
XPath: /billing/name/suffix
Alphanumeric including
symbols (25)
The suffix of the customer’s billing name (e.g. Bsc).
Customer and delivery

The following fields contain the customer’s delivery details:

  Field Format Description
table-optional.png customerpremise
XPath: /customer/premise
Alphanumeric including
symbols (25)
The customer’s house name or number.
table-optional.png customerstreet
XPath: /customer/street
Alphanumeric including
symbols (127)
The customer’s street name.
table-optional.png customertown
XPath: /customer/town
Alphanumeric including
symbols (127)
The customer’s town.
table-optional.png customercounty
XPath: /customer/county
Alphanumeric including
symbols (127)
The customer’s county. For US addresses, the state would be entered in this field. Valid formats:
  • Preferred: Two character state code, e.g. “NY”.
  • Full state name, e.g. “New York”.
table-conditional.png customercountryiso2a
XPath: /customer/country
Alpha (2)

The customer’s country. This will need to be in ISO2A format.

Click here for a full list of country codes.

Required if Merchant Category Code (MCC) is 6012 and payment type is VISA.

table-conditional.png customerpostcode
XPath: /customer/postcode
Alphanumeric (25)

The customer’s postcode or ZIP code.

If the country provided is not United States, Great Britain or Canada, or if no country is provided, the postcode field is not validated.

Required if Merchant Category Code (MCC) is 6012 and payment type is VISA.

table-optional.png customeremail
XPath: /customer/email
Email (255) The customer’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
table-optional.png customertelephonetype
XPath: /customer/telephone/@type
Char (1) The type of telephone number. The options available are:
  • H = Home
  • M = Mobile
  • W = Work
table-optional.png customertelephone
XPath: /customer/telephone
Alphanumeric including
symbols (20)
The customer’s telephone number. Valid characters:
  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
table-optional.png customerprefixname
XPath: /customer/name/prefix
Alphanumeric including
symbols (25)
The customer’s prefix name (e.g. Mr, Miss, Dr).
table-optional.png customerfirstname
XPath: /customer/name/first
Alphanumeric including
symbols (127)
The customer’s first name.
table-optional.png customermiddlename
XPath: /customer/name/middle
Alphanumeric including
symbols (127)
The customer’s middle name(s).
table-optional.png customerlastname
XPath: /customer/name/last
Alphanumeric including
symbols (127)
The customer’s last name.
table-optional.png customersuffixname
XPath: /customer/name/suffix
Alphanumeric including
symbols (25)
The customer’s suffix name (e.g. Bsc).
table-optional.png customerforwardedip
XPath: /customer/forwardedip
IP address (39) Customer forwarded IP address, as provided by a proxy server if available.
table-optional.png customerip
XPath: /customer/ip
IP address (39) The IP of the customer.
Settlement

The following fields contain the Settlement details:

  Field Format Description
table-optional.png settleduedate
XPath: /settlement/settleduedate
Date YYYY-MM-DD You can submit this field in the request to specify the date you would like your transaction to settle. This must be within 7 days of the authorisation date.
table-optional.png settlestatus
XPath: /settlement/settlestatus
Numeric (3) A numeric value used to define the settlement instruction. If you do not submit a value here, the settlestatus defaults to “0”.

Click here for a full list of settlestatus values.

 

AUTH response

The following is an example of an AUTH response indicating the request was processed successfully.

Python PHP Raw JSON Raw XML
{
u 'requestreference': u 'A0bxh87wt',
u 'version': u '1.00',
u 'responses': [{
u 'transactionstartedtimestamp': u '2016-12-07 11:32:44',
u 'livestatus': u '0',
u 'issuer': u 'Test Issuer',
u 'splitfinalnumber': u '1',
u 'dccenabled': u '0',
u 'settleduedate': u '2016-12-07',
u 'errorcode': u '0',
u 'orderreference': u 'My_Order_123',
u 'tid': u '27882788',
u 'merchantnumber': u '00000000',
u 'merchantcountryiso2a': u 'GB',
u 'transactionreference': u '23-9-80001',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'baseamount': u '1050',
u 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u '00',
u 'requesttypedescription': u 'AUTH',
u 'securityresponsesecuritycode': u '2',
u 'currencyiso3a': u 'GBP',
u 'authcode': u 'TEST36',
u 'errormessage': u 'Ok',
u 'operatorname': u 'webservices@example.com',
u 'securityresponsepostcode': u '0',
u 'maskedpan': u '411111######1111',
u 'securityresponseaddress': u '0',
u 'issuercountryiso2a': u 'US',
u 'settlestatus': u '0'
}]
}

 

When you receive an AUTH response, you must check the field values, to ensure the request was processed successfully.

Click here for recommended checks to perform.

 

Operation

The following fields relate to the type of request submitted:

  Field Format Description
table-returned.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) The type of account to be used:
  • “ECOM” – E-commerce.
  • “MOTO” – Mail or Telephone Order
  • “RECUR” – Recurring transactions
table-conditional.png authmethod
XPath: /operation/authmethod
Alpha (11)

Auth methods are used to specify how a transaction is to be processed by the card issuer. Each authmethod has a different set of requirements. Click the following links to learn more:

This field is returned if submitted in the request.

table-conditional.png credentialsonfile
XPath: /operation/credentialsonfile
Numeric (1) The allowed values for this field are 0, 1 and 2.
  • “0” – Not eligible for CoF, or no intention of re-using credentials at a later time.
  • “1” – Transaction credentials flagged as available for future use.
  • “2” – Payment using previously-stored credentials.

This field is returned if submitted in the request.

table-conditional.png parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)

The transactionreference of a previous request, from which key details have been inherited.

This field is returned if submitted in the request.

table-returned.png requesttypedescription
XPath: /@type
Alpha (20) “AUTH” is returned in the response.
Billing

The following fields contain the customer’s billing details:

  Field Format Description
table-returned.png 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-returned.png currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3)

The currency of the transaction.

Click here for a full list of available currencies.

table-returned.png dccenabled
XPath: /billing/dcc/@enabled
Numeric (1) Indicates if your account is configured for DCC:
1= Yes
0 = No
table-returned.png issuer
XPath: /billing/payment/issuer
Alphanumeric (255) The customer’s card issuer.
table-returned.png 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.png maskedpan
XPath: /billing/payment/pan
Alphanumeric including “#” (12-19) If tokenisedpayment is not returned:
The maskedpan field represents the customer’s card number.If tokenisedpayment is returned with value 1:

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.png paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) Payment method (e.g. “VISA” or “MASTERCARD”).
table-conditional.png tokenisedpayment
XPath: /billing/payment/pan/@tokenised
Numeric (1)

If this field is returned with value 1, this indicates the transaction was processed using a token.

This field is returned if payment was performed using a token.

table-conditional.png tokentype
XPath: /billing/payment/pan/@tokentype
Alphanumeric (50)

Used to identify the type of token used for this payment (e.g. “VISATOKEN”).

This field is returned if payment was performed using a token.

table-conditional.png walletdisplayname
XPath: /billing/payment/wallet/displayname
Alphanumeric (255)

This normally contains the last four digits of the customer’s card number (e.g. “1111”).

This field is returned if payment was performed using a wallet.

table-conditional.png walletsource
XPath: /billing/payment/wallet/source
Alphanumeric (20)

Used to identify the type of wallet used for this payment (e.g. “APPLEPAY”).

This field is returned if payment was performed using a wallet.

Merchant

The following fields relate to your account configuration:

  Field Format Description
table-conditional.png chargedescription
XPath: /merchant/chargedescription
Alphanumeric including
symbols (25)

This is a description of the payment that appears on the customer’s bank statement.

Only supported by certain acquiring banks.

Specification of this field will depend on your acquiring bank.

Click here for further information.

 Valid characters:

  • Uppercase/lowercase A-Z
  • Numbers 0-9
  • Spaces
  • Punctuation: + – _ . @ ( )

This field is returned if sent to the acquiring bank.

table-returned.png merchantnumber
XPath: /merchant/merchantnumber
Alphanumeric (32) The merchant number that was used to process the transaction. Provided by the acquiring bank.
table-conditional.png 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.

merchantcity
XPath: /merchant/merchantcity
Alphanumeric (127)
merchantcountryiso2a
XPath: /merchant/merchantcountryiso2a
Alpha (2)
merchantname
XPath: /merchant/merchantname
Alphanumeric (255)
merchantstatecode
XPath: /merchant/merchantstatecode
Alphanumeric (127)
merchantzipcode
XPath: /merchant/merchantzipcode
Alphanumeric (10)
table-returned.png operatorname
XPath: /merchant/operatorname
Alphanumeric (255) The value of this field contains the name of the user that processed the request.
table-conditional.png orderreference
XPath: /merchant/orderreference
Alphanumeric including
symbols (25)

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

Note: This can be updated at a later time (only if transaction is pending settlement).

This field is returned if submitted in the request.

table-returned.png tid
XPath: /merchant/tid
Alphanumeric (255) The terminal ID used to process the transaction. This is accredited to your merchant number when we setup your account in our systems.
Settlement

The following fields contain the Settlement details:

  Field Format Description
table-returned.png settleduedate
XPath: /settlement/settleduedate
Date YYYY-MM-DD The date on which the transaction will be settled.
table-returned.png settlestatus
XPath: /settlement/settlestatus
Numeric (3)

A numeric value used to indicate the progress of settlement regarding this transaction.

Click here for a full list of settlestatus values.

Transaction status

In addition to the response object, two additional fields are also returned in the response:

  Field Format Description
table-conditional.png acquireradvicecode
XPath: /acquireradvicecode
 Numeric (1) A numeric value returned following a repeat payment request, indicating if further payments can be processed.

Mapping:

  • 0 – No action required.
  • 1 – New account information available.
  • 2 – Cannot approve at this time.
  • 4 – Do not process further recurring transactions.
  • 8 – Payment blocked by card scheme.

This will vary depending on your acquiring bank. Please contact your bank for further information.

table-conditional.png acquirerresponsecode
XPath: /acquirerresponsecode
Alphanumeric (255)

Used by your acquirer to indicate the outcome of the request.

This will vary depending on your acquiring bank. Please contact your bank for further information.

table-conditional.png acquirerresponsemessage
XPath: /acquirerresponsemessage
Alphanumeric (255)
table-conditional.png authcode
XPath: /authcode
Alphanumeric (255)

The authorisation code provided by the issuing bank. This will differ depending on which bank you use.

Only returned if the transaction is authorised.

table-returned.png 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.png errordata
XPath: /error/data
Alphanumeric (255)

Additional information to help troubleshoot the error.

Only returned if there has been an error.

table-returned.png 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.png livestatus
XPath: /live
Numeric (1)
  • 0 – Transaction processed using a test account.
  • 1 – Transaction processed using a live account.
table-conditional.png retrievalreferencenumber
XPath: /other/retrievalreferencenumber
Alphanumeric (255)

An ISO term. This is used to reference the source transaction.

This will vary depending on your acquiring bank. Please contact your bank for further information.

table-returned.png securityresponseaddress
XPath: /security/address
Numeric (1) The result of AVS and Security Code Checks.

Click here to learn more.

table-returned.png securityresponsepostcode
XPath: /security/postcode
Numeric (1)
table-returned.png securityresponsesecuritycode
XPath: /security/securitycode
Numeric (1)
table-returned.png 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.png transactionstartedtimestamp
XPath: /timestamp
Date time YYYY-MM-DD hh:mm:ss The time the transaction was processed.

 

In addition to the response object, two additional fields are also returned in the response:

  Field Format Description
table-returned.png requestreference Alphanumeric (25) This is an internal field generated by Trust Payments. It must not be validated. If problems are experienced with the request this field may be requested by Trust Payments support to aid in determining the cause.
table-returned.png secrand Alphanumeric (16) Random string of characters, returned in the response of non-API-based libraries developed by Trust Payments.
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request