1. API for POS Developers
  2. User guides

Webservices API Guide for POS developers

​  Last updated: 

 

  Contact Trust Payments directly for approval before using this content in your integration.

 

First steps

  

 

  Configure your library

You will first need to configure your system to connect securely with Trust Payments. Please click the link below and follow the instructions provided to ensure your system can send a basic request to our gateway successfully. Once done, the instructions found below explain how to send requests to perform payment functions with your POS terminal.

  Open config instructions in a new tab

 

Process transaction

 

 

  AUTH Overview

To process a card transaction, you will need to submit an AUTH request and handle the response returned.

 

  1. Authorisation
    • You submit an AUTH request to the Trust Payments endpoint using our Webservices API.
    • The settle status is used to indicate the state of the transaction.
    • When a payment has been authorised by the acquiring bank, the settle status will normally be set to “0”.
    • Trust Payments returns an AUTH response that will show either a success or error response.
  2. Pending settlement
    • Following a successful authorisation, funds are reserved against the customer’s bank account until settlement.
    • During this time, you can perform queries and updates through our Webservices API, or MyST (our online transaction management portal).
    • Updates can only be performed when the settle status is “0” or “1”.
  3. Completion
    • Settlement typically occurs within 24 hours, but this can vary depending on the banks involved and payment method.
    • Once settled, the funds will be transferred to your bank account. This updates the settle status to “100”.
    • You can perform refunds by submitting a request using our Webservices API, or MyST (our online transaction management portal).
    • For some payment types, the transaction may have status “10”, meaning settlement is in progress but not yet complete.
  4. Handling errors
    • If a transaction is cancelled or a failure occurs at any point in the process, the settle status is set to “3”.
    • Further actions cannot be performed and the funds will be released back to the customer’s bank account.
    • If you look at the error code, you can learn the reason for any unexpected failures.

  Processing AUTH

AUTH Request

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

AUTH Request
{
  "alias":"webserv3",
  "version":"1.00",
  "request":[{
    "accounttypedescription":"POS",
    "baseamount":"1000",
    "carddataentrymode":"CONTACTLESS",
    "cardholderauthenticationmethod":"ONLINEPIN",
    "currencyiso3a":"GBP",
    "deviceencryptedtrack2data":"C8AC965B70FD1F590EAA44F2D55511A5B29D55A1B98F0C70",
    "deviceencryptedpin":"C9A8FEB60C5B26CD",
    "deviceencryptionkeytype":"AES-256",
    "deviceksn":"1234567822334A0000000001",
    "expirydate":"12/2028",
    "iccdata": "9F02060000000010009F03060000000000009F2608A1B2C3D4E5F6A1B28202A1B29F360200018A02A1B29F3403A1B2C39F2701A18410A1B2C3D4E5F6A1B2A1B2C3D4E5F6A1B29F3501A19F6E06A1B2C3D4E5F69F1E10313233343536373831323334353637389F1020A1B2C3D4E5F6A1B2A1B2C3D4E5F6A1B2A1B2C3D4E5F6A1B2A1B2C3D4E5F6A1B29110A1B2C3D4E5F6A1B2A1B2C3D4E5F6A1B2DF3114A1B2C3D4E5F6A1B2A1B2C3D4E5F6A1B2A1B2C3D49F5B14A1B2C3D4E5F6A1B2A1B2C3D4E5F6A1B2A1B2C3D47166A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1BA1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1BA1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1BA1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B7219A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A19F0901019F3303015ABC9F1A0208269505A1B2C3D4E59F5301A15F2A0208269A032212129C01009F370400010001",
    "orderreference":"My_Order_123",
    "requesttypedescriptions":"AUTH",
    "sitereference":"test_mikepos76455",
    "terminalcardcapturecapability":"2",
    "terminalcardoutputcapability": "3",
    "terminalid":"12345678",
    "terminalinputcapability":["CONTACTLESS","ICC"],
    "terminaloperatingenvironment":"2",
    "terminaloutputcapability":"B",
    "terminalpinentrycapability":"4"
  }]
}

 

Field specification

Required Field Format Length Description
X1-EN.png accounttypedescription Alpha Max 20

The type of account used to process the transaction. Submit "POS" when processing POS transactions.
X1-EN.png baseamount Numeric Max 13

The amount of the transaction in base units, with no commas or decimal points, so £10 is submitted as 1000.

If customer is requesting cashback, this baseamount is the total debited from the customer's card, including the value specified in the cashbackbaseamount field.
X1-EN.png carddataentrymode Alpha Max 18

Following values supported:

  • CONTACTLESS - Auto via contactless M/Chip.
  • ICC - Auto via ICC.
  • ICCUNRELIABLE - Data was chip read and potentially unreliable.
  • MAGSTRIPE - Auto via mag stripe.
  • MAGSTRIPEFAILEDICC - Auto via mag stripe - fallback if Auto via ICC failed.
  • MAGSTRIPEPARTIAL - Auto via mag stripe but mag stripe data not fully read/transmitted.

If facilitating an online PIN transaction, you can only submit CONTACTLESS, ICC or ICCUNRELIABLE.
X1-EN.png cardholderauthenticationmethod Alpha Max 15

Following values supported:

  • SIGNATURE - Signature. (Can only be submitted if carddataentrymode is "CONTACTLESS", "ICC", "ICCUNRELIABLE", "MAGSTRIPE", "MAGSTRIPEFAILEDICC" or "MAGSTRIPEPARTIAL")
  • MOBILEDEVICECVM - CVM performed by mobile device. (Can only be submitted if carddataentrymode is "CONTACTLESS")
  • NOCVM - Not authenticated. (Can only be submitted if carddataentrymode is "CONTACTLESS", "ICC", "ICCUNRELIABLE", "MAGSTRIPE", "MAGSTRIPEFAILEDICC" or "MAGSTRIPEPARTIAL")
  • ONLINEPIN - Online PIN. (can only be submitted if carddataentrymode is "CONTACTLESS", "ICC" or "ICCUNRELIABLE")
  • OFFLINEPIN - Offline PIN. (Can only be submitted if carddataentrymode is "ICC" or "ICCUNRELIABLE")
X1-EN.png currencyiso3a ISO3A 3

The currency of the transaction.

Click here for a full list of available currencies.
X1-EN.png requesttypedescriptions Alpha Max 20 You must submit “AUTH”, as shown in the request example.
X1-EN.png sitereference Alphanumeric
& underscore 		Max 50

Identifies your site on the Trust Payments system.

  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.

If you do not know your site reference, please contact our Support Team.
X1-EN.png terminalcardcapturecapability Numeric 1

Following values supported:

  • 0 - Unknown.
  • 1 - No card capture capability.
  • 2 - Has card capture capability.
X1-EN.png terminalcardoutputcapability Alphanumeric 1

Following values supported:

  • 0 - Unknown.
  • 1 - None.
  • 2 - Magnetic stripe write.
  • 3 - ICC.
  • S - Other
X1-EN.png terminalid Numeric 8

POS terminal identifier.
X1-EN.png terminalinputcapability List of Strings  

Submit a list of the card data entry modes supported by this terminal from the following:

  • CONTACTLESS - Ability to accept contactless payments (both mobile and card).
  • ICC - Ability to accept contact Integrated Circuit Card payments (AKA "Chip and PIN").
  • KEYED - Ability to accept payments where card data is manually entered into the terminal.
  • MAGSTRIPE - Ability to accept swipe payments.
X1-EN.png terminaloperatingenvironment Numeric 1

Following values supported:

  • 0 - Unknown.
  • 1 - No terminal used.
  • 2 - On premises of card acceptor, attended.
  • 3 - Off premises of card acceptor, attended.
X1-EN.png terminaloutputcapability Char 1

Following values supported:

  • U - Unknown.
  • N - None.
  • P - Printing.
  • D - Display.
  • B - Printing and display.
X1-EN.png terminalpinentrycapability Alphanumeric 1

Following values supported:

  • U - Unknown.
  • N - Terminal does not have PIN entry capability.
  • X - Terminal has PIN entry capability but PIN pad is not currently operative.
  • O - Other.
  • 4 - Terminal has PIN entry capability, 4 digit pin.
  • 5 - Terminal has PIN entry capability, 5 digit pin.
  • 6 - Terminal has PIN entry capability, 6+ digit pin.
X2-EN.png cardsequencenumber Alphanumeric Max 3

The card sequence number is used to identify and differentiate between cards that share the same PAN.

This is submitted as a 2-digit value up to "99" (this can also be prefixed with a 0, e.g. "099").

Must be submitted if available.
X2-EN.png deviceencryptedpan Alphanumeric N/A

Encrypted PAN number.

Depending on the method of payment, you must submit ONE of the following fields:

  • deviceencryptedpan
  • deviceencryptedtrack2data (Recommended)
  • pan
  • track2data
X2-EN.png deviceencryptedpin Alphanumeric N/A

Encrypted PIN block.

Required when facilitating online PIN functionality.
X2-EN.png deviceencryptedtrack2data Alphanumeric N/A

Encrypted track 2 data.

Depending on the method of payment, you must submit ONE of the following fields:

  • deviceencryptedpan
  • deviceencryptedtrack2data (Recommended)
  • pan
  • track2data
X2-EN.png deviceencryptionkeytype Alphanumeric including hyphens N/A

Can be either: "2DES", "3DES", "AES-128", "AES-192", "AES-256".

We recommend always using the strongest encryption (in this case AES-256).

Required if fields deviceencryptedpan or deviceencryptedtrack2data are submitted.
X2-EN.png deviceksn Alphanumeric 20-24

Key Serial Number (KSN) of the transaction. This is provided by the encrypting device through the concatenation of a unique identifier with an internal encryption counter.

Required if fields deviceencryptedpan or deviceencryptedtrack2data are submitted.
X2-EN.png expirydate Date MM/YYYY Max 7

The expiry date printed on the card.

Required when submitting deviceencryptedpan or pan.
X2-EN.png iccdata EMV tag format 4

Supported values:

5F2A, 71, 72, 82, 84, 8A, 91, 95, 9A, 9C, 9F02, 9F03, 9F09, 9F10, 9F1A, 9F1E, 9F26, 9F27, 9F33, 9F34, 9F35, 9F36, 9F37, 9F3B, 9F53, 9F6E, DF31.

Required for ICC, CONTACTLESS, ICCUNRELIABLE.
X2-EN.png pan Numeric 12-19

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

Depending on the method of payment, you must submit ONE of the following fields:

  • deviceencryptedpan
  • deviceencryptedtrack2data (Recommended)
  • pan
  • track2data
X2-EN.png track2data ISO 7813 Max 40

Track 2 data - this is the information held on the chip or magnetic stripe of the customer's credit/debit card. Send this with start/end sentinel and LRC if present.

Depending on the method of payment, you must submit ONE of the following fields:

  • deviceencryptedpan
  • deviceencryptedtrack2data (Recommended)
  • pan
  • track2data
X3-EN.png billingpostcode Alphanumeric Max 25 The billing postcode or ZIP code. This must be a valid postcode/ZIP code for the billingcountryiso2a submitted.
X3-EN.png billingpremise Alphanumeric including
symbols 		Max 25 The house number or first line of the customer’s billing address.
X3-EN.png billingstreet Alphanumeric including
symbols 		Max 127 The street entered for the customer’s billing address.
X3-EN.png cashbackbaseamount Numeric Max 13

The cashback amount requested by the customer.
X3-EN.png chargedescription Alphanumeric including
symbols 		Max 25

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

 Valid characters:

  • Uppercase/lowercase A-Z
  • Numbers 0-9
  • Spaces
  • Punctuation: + – _ . @ ( )
X3-EN.png merchantemail Email Max 255 The merchant’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
X3-EN.png operatorname Alphanumeric Max 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).
X3-EN.png orderreference

Alphanumeric including
symbols

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

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.
X3-EN.png parenttransactionreference Alphanumeric
& hyphens 		Max 25 Allows you to specify the transactionreference of a previous request. Key details are inherited from this request.
X3-EN.png paymenttypedescription Alpha Max 20

Payment method (e.g. “VISA” or “MASTERCARD”).
X3-EN.png settleduedate Date YYYY-MM-DD 10 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.
X3-EN.png settlestatus Numeric Max 3 A numeric value used to define the settlement instruction. If you do not submit a value here, the settlestatus defaults to “0”.

Click to learn more about the settlement process.
AUTH Response

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

AUTH Response
{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "accounttypedescription": "POS",
    "acquirerresponsecode": "00",
    "acquirerresponsemessage": "Approved or completed Successfully",
    "authcode": "000005",
    "baseamount": "2000",
    "currencyiso3a": "GBP",
    "errorcode": "0",
    "errormessage": "Ok",
    "iccdataresponse": "8A023030",
    "issuer":"Test Issuer",
    "issuercountryiso2a": "GB",
    "livestatus": "0",
    "maskedpan": "411111######1111",
    "merchantcategorycode": "7001",
    "merchantcountryiso2a": "GB",
    "merchantname": "Test Merchant",
    "merchantnumber": "12345",
    "operatorname": "webservices@example.com",
    "orderreference": "MyOrder123",
    "paymenttypedescription": "VISA",
    "requesttypedescription": "AUTH",
    "retrievalreferencenumber": "300316080007",
    "securityresponseaddress": "0",
    "securityresponsepostcode": "0",
    "securityresponsesecuritycode": "0",
    "settleduedate": "2023-01-03",
    "settlestatus": "0",
    "stan": "080007",
    "transactionreference": "8-103-7",
    "transactionstartedtimestamp": "2023-01-03 16:36:53"
  }],
  "secrand":"zO9"
}

 

Field specification

Required Field Format Length Description
X4-EN.png accounttypedescription Alpha Max 20 The type of account used to process the transaction. Expect "POS" to be returned when performing POS transactions.
X4-EN.png baseamount Numeric Max 13

The amount of the transaction in base units, with no commas or decimal points, so £10 is submitted as 1000.

  Mastercard can decline cashback requests. If this happens, the cashbackbaseamount field is returned with value "0" and this amount is also subtracted from the total baseamount returned.
X4-EN.png currencyiso3a ISO3A 3

The currency of the transaction.

Click here for a full list of available currencies.
X4-EN.png errorcode 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.
X4-EN.png errormessage Alphanumeric Max 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.
X4-EN.png issuer Alphanumeric Max 255 The customer’s card issuer.
X4-EN.png issuercountryiso2a ISO2A 2

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

Click here for a full list of country codes.
X4-EN.png livestatus Numeric 1
  • 0 – Transaction processed using a test account.
  • 1 – Transaction processed using a live account.
X4-EN.png maskedpan Alphanumeric including “#” 12-19 The maskedpan field represents the customer’s card number. The value of maskedpan field is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
X4-EN.png merchantnumber Alphanumeric Max 32 The merchant number that was used to process the transaction. Provided by the acquiring bank.
X4-EN.png operatorname Alphanumeric Max 255 The value of this field contains the name of the user that processed the request.
X4-EN.png paymenttypedescription Alpha Max 20 Payment method (e.g. “VISA” or “MASTERCARD”).
X4-EN.png requesttypedescription Alpha Max 20 “AUTH” is returned in the response.
X4-EN.png securityresponseaddress Numeric 1 The result of AVS and Security Code Checks.

Click here to learn more.
X4-EN.png securityresponsepostcode Numeric 1 The result of AVS and Security Code Checks.

Click here to learn more.
X4-EN.png securityresponsesecuritycode Numeric 1 The result of AVS and Security Code Checks.

Click here to learn more.
X4-EN.png settleduedate Date YYYY-MM-DD 10 The date on which the transaction will be settled.
X4-EN.png settlestatus Numeric Max 3

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

Click here for a full list of settlestatus values.
X4-EN.png transactionreference Alphanumeric including
hyphens 		Max 25 A unique reference for the transaction assigned by Trust Payments. You will need this reference to perform a refund or update the transaction.
X4-EN.png transactionstartedtimestamp Date time YYYY-MM-DD hh:mm:ss 19 The time the transaction was processed.
X2-EN.png acquirerresponsecode Alphanumeric Max 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.
X2-EN.png acquirerresponsemessage Alphanumeric Max 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.
X2-EN.png authcode Alphanumeric Max 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.
X2-EN.png cashbackbaseamount Numeric Max 13

The cashback amount requested by the customer.

  Mastercard can decline cashback requests. If this happens, cashbackbaseamount is returned with value "0".

This field is returned if available.
X2-EN.png chargedescription Alphanumeric including symbols Max 25

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

 Valid characters:

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

This field is returned if sent to the acquiring bank.
X2-EN.png errordata Alphanumeric Max 255

Additional information to help troubleshoot the error.

Only returned if there has been an error.
X2-EN.png iccdataresponse EMV tag format Max 4

ICC data response returned from customer's card issuer.

Only returned for ICC, CONTACTLESS, ICCUNRELIABLE.
X2-EN.png merchantcategorycode Alphanumeric Max 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.
X2-EN.png merchantcity Alphanumeric Max 127

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.
X2-EN.png merchantcountryiso2a ISO2A 2

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.
X2-EN.png merchantname Alphanumeric Max 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.
X2-EN.png merchantstatecode Alphanumeric Max 127

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.
X2-EN.png merchantzipcode Alphanumeric Max 10

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.
X2-EN.png orderreference Alphanumeric including
symbols 		Max 255

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.
X2-EN.png retrievalreferencenumber Alphanumeric Max 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.
X2-EN.png stan ISO 8583 Undefined

The STAN (System Trace Audit Number) associated with the transaction. This follows the ISO 8583 standard.

This field is returned if available.
X2-EN.png tid Alphanumeric Max 255

The terminal ID used to process the transaction. This is accredited to your merchant number when we setup your account in our systems.

Whether this field is returned varies depending on your acquiring bank. Please contact our Support Team if you need assistance.

 

Refund transaction

 

 

  REFUND Overview

To refund a processed transaction, you will need to submit a REFUND request and handle the response returned.

 

  1. Merchant/partner submits REFUND request.
  2. Trust Payments validates the request and contacts the bank.
  3. Trust Payments processes the refund with the relevant acquirer.
  4. Trust Payments receives results of the request and passes this back to merchant/partner.
  5. Merchant/partner receives and interprets this response.

  Processing REFUND

REFUND Request
REFUND using parent REFUND using online PIN 
{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "parenttransactionreference":"1-2-345678",
    "requesttypedescriptions":"REFUND",
    "sitereference":"test_site12345"
  }]
}

 

Field specification

Required Field Format Length Description
X1-EN.png requesttypedescriptions Alpha Max 20 The request type required is “REFUND”.
X1-EN.png sitereference Alphanumeric
& underscore 		Max 50

A unique reference that identifies your account. You receive this when you first sign up with us.

The site reference submitted in the REFUND request must be the same as the site reference used to process the parent AUTH request.
X2-EN.png accounttypedescription Alpha Max 20

The type of account used to process the transaction. Submit "POS" when processing POS transactions.

This field is required unless the parenttransactionreference is submitted to inherit data from the transaction being refunded instead.
X2-EN.png baseamount Numeric Max 13

The refund amount in base units, with no commas or decimal points, so £10 is submitted as 1000.

This amount cannot be greater than the final amount settled into your bank account.

This field is required unless the parenttransactionreference is submitted to inherit data from the transaction being refunded instead.

If parenttransactionreference is submitted, the full baseamount is inherited from the parent (including any cashback specified in the original transaction), unless overridden by submitting a lower value in the baseamount field.
X2-EN.png carddataentrymode Alpha Max 18

Following values supported:

  • CONTACTLESS - Auto via contactless M/Chip.
  • ICC - Auto via ICC.
  • ICCUNRELIABLE - Data was chip read and potentially unreliable.
  • MAGSTRIPE - Auto via mag stripe.
  • MAGSTRIPEFAILEDICC - Auto via mag stripe - fallback if Auto via ICC failed.
  • MAGSTRIPEPARTIAL - Auto via mag stripe but mag stripe data not fully read/transmitted.

If facilitating an online PIN transaction, you can only submit CONTACTLESS, ICC or ICCUNRELIABLE.

This field is required unless the parenttransactionreference is submitted to inherit data from the transaction being refunded instead.
X2-EN.png cardholderauthenticationmethod Alpha Max 15

Following values supported:

  • SIGNATURE - Signature. (Can only be submitted if carddataentrymode is "CONTACTLESS", "ICC", "ICCUNRELIABLE", "MAGSTRIPE", "MAGSTRIPEFAILEDICC" or "MAGSTRIPEPARTIAL")
  • MOBILEDEVICECVM - CVM performed by mobile device. (Can only be submitted if carddataentrymode is "CONTACTLESS")
  • NOCVM - Not authenticated. (Can only be submitted if carddataentrymode is "CONTACTLESS", "ICC", "ICCUNRELIABLE", "MAGSTRIPE", "MAGSTRIPEFAILEDICC" or "MAGSTRIPEPARTIAL")
  • ONLINEPIN - Online PIN. (can only be submitted if carddataentrymode is "CONTACTLESS", "ICC" or "ICCUNRELIABLE")
  • OFFLINEPIN - Offline PIN. (Can only be submitted if carddataentrymode is "ICC" or "ICCUNRELIABLE")

This field is required unless the parenttransactionreference is submitted to inherit data from the transaction being refunded instead.
X2-EN.png cardsequencenumber Alphanumeric Max 3

The card sequence number is used to identify and differentiate between cards that share the same PAN.

This is submitted as a 2-digit value up to "99" (this can also be prefixed with a 0, e.g. "099").

This field must be submitted if available, unless the parenttransactionreference is submitted, then the data will be inherited from the transaction being refunded instead.
X2-EN.png currencyiso3a ISO3A 3

The currency of the refund.

Click here for a full list of available currencies.

This field is required unless the parenttransactionreference is submitted to inherit data from the transaction being refunded instead.
X2-EN.png deviceencryptedpan Alphanumeric N/A

Encrypted PAN number.

If parenttransactionreference is submitted, then the data will be inherited from the transaction being refunded. If not submitted, you must instead submit ONE of the following fields:

  • deviceencryptedpan
  • deviceencryptedtrack2data (Recommended)
  • pan
  • track2data
X2-EN.png deviceencryptedpin Alphanumeric N/A

Encrypted PIN block.

Required when facilitating online PIN functionality.
X2-EN.png deviceencryptedtrack2data Alphanumeric N/A

Encrypted track 2 data.

If parenttransactionreference is submitted, then the data will be inherited from the transaction being refunded. If not submitted, you must instead submit ONE of the following fields:

  • deviceencryptedpan
  • deviceencryptedtrack2data (Recommended)
  • pan
  • track2data
X2-EN.png deviceencryptionkeytype Alphanumeric including hyphens N/A

Can be either: "2DES", "3DES", "AES-128", "AES-192", "AES-256".

We recommend always using the strongest encryption (in this case AES-256).

Required if fields deviceencryptedpan or deviceencryptedtrack2data are submitted.
X2-EN.png deviceksn Alphanumeric 20-24

Key Serial Number (KSN) of the transaction. This is provided by the encrypting device through the concatenation of a unique identifier with an internal encryption counter.

Required if fields deviceencryptedpan or deviceencryptedtrack2data are submitted.
X2-EN.png expirydate Date MM/YYYY Max 7

This field is used to process a refund with an updated expiry date.

Required when submitting deviceencryptedpan.
X2-EN.png iccdata EMV tag format 4

Supported values:

5F2A, 71, 72, 82, 84, 8A, 91, 95, 9A, 9C, 9F02, 9F03, 9F09, 9F10, 9F1A, 9F1E, 9F26, 9F27, 9F33, 9F34, 9F35, 9F36, 9F37, 9F3B, 9F53, 9F6E, DF31.

Required for ICC, CONTACTLESS, and ICCUNRELIABLE, unless the parenttransactionreference is submitted to inherit data from the transaction being refunded instead.
X2-EN.png pan Numeric 12-19

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

If parenttransactionreference is submitted, then the data will be inherited from the transaction being refunded. If not submitted, you must instead submit ONE of the following fields:

  • deviceencryptedpan
  • deviceencryptedtrack2data (Recommended)
  • pan
  • track2data
X2-EN.png parenttransactionreference Alphanumeric
& hyphens 		Max 25

This field must contain the transaction reference of the AUTH request that you would like to refund.

Either parenttransactionreference is required to inherit data from the transaction being refunded, or the following fields must be submitted instead:

  • accounttypedescription
  • baseamount
  • carddataentrymode
  • cardholderauthenticationmethod
  • cardsequencenumber
  • currencyiso3a
  • Only ONE of the following: deviceencryptedpan, deviceencryptedtrack2data, pan or track2data
  • deviceencryptedpin
  • deviceencryptionkeytype
  • deviceksn
  • expirydate (Only required if deviceencryptedpan or pan is submitted)
  • iccdata (Only required for ICC, CONTACTLESS, and ICCUNRELIABLE)
  • terminalcardcapturecapability
  • terminalcardoutputcapability
  • terminalid
  • terminalinputcapability
  • terminaloperatingenvironment
  • terminaloutputcapability
  • terminalpinentrycapability
  • track2data

  If you are submitting the parenttransactionreference to perform the refund, please be aware that by default the full baseamount will be refunded (including the cashbackbaseamount, if applicable). You can override this behaviour by submitting a lower baseamount in the request.
X2-EN.png terminalcardcapturecapability Numeric 1

Following values supported:

  • 0 - Unknown.
  • 1 - No card capture capability.
  • 2 - Has card capture capability.

This field is required unless the parenttransactionreference is submitted to inherit data from the transaction being refunded instead.
X2-EN.png terminalcardoutputcapability Alphanumeric 1

Following values supported:

  • 0 - Unknown.
  • 1 - None.
  • 2 - Magnetic stripe write.
  • 3 - ICC.
  • S - Other

This field is required unless the parenttransactionreference is submitted to inherit data from the transaction being refunded instead.
X2-EN.png terminalid Numeric 8

POS terminal identifier.

This field is required unless the parenttransactionreference is submitted to inherit data from the transaction being refunded instead.
X2-EN.png terminalinputcapability List of Strings  

Submit a list of the card data entry modes supported by this terminal from the following:

  • CONTACTLESS - Ability to accept contactless payments (both mobile and card).
  • ICC - Ability to accept contact Integrated Circuit Card payments (AKA "Chip and PIN").
  • KEYED - Ability to accept payments where card data is manually entered into the terminal.
  • MAGSTRIPE - Ability to accept swipe payments.

This field is required unless the parenttransactionreference is submitted to inherit data from the transaction being refunded instead.
X2-EN.png terminaloperatingenvironment Numeric 1

Following values supported:

  • 0 - Unknown.
  • 1 - No terminal used.
  • 2 - On premises of card acceptor, attended.
  • 3 - Off premises of card acceptor, attended.

This field is required unless the parenttransactionreference is submitted to inherit data from the transaction being refunded instead.
X2-EN.png terminaloutputcapability Char 1

Following values supported:

  • U - Unknown.
  • N - None.
  • P - Printing.
  • D - Display.
  • B - Printing and display.

This field is required unless the parenttransactionreference is submitted to inherit data from the transaction being refunded instead.
X2-EN.png terminalpinentrycapability Alphanumeric 1

Following values supported:

  • U - Unknown.
  • N - Terminal does not have PIN entry capability.
  • X - Terminal has PIN entry capability but PIN pad is not currently operative.
  • O - Other.
  • 4 - Terminal has PIN entry capability, 4 digit pin.
  • 5 - Terminal has PIN entry capability, 5 digit pin.
  • 6 - Terminal has PIN entry capability, 6+ digit pin.

This field is required unless the parenttransactionreference is submitted to inherit data from the transaction being refunded instead.
X2-EN.png track2data ISO 7813 Max 40

Track 2 data - this is the information held on the chip or magnetic stripe of the customer's credit/debit card. Send this with start/end sentinel and LRC if present.

If parenttransactionreference is submitted, then the data will be inherited from the transaction being refunded. If not submitted, you must instead submit ONE of the following fields:

  • deviceencryptedpan
  • deviceencryptedtrack2data (Recommended)
  • pan
  • track2data
X3-EN.png chargedescription Alphanumeric including
symbols 		Max 25

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

 Valid characters:

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

Alphanumeric including
symbols

 Max 25

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

If this is not submitted, it is inherited from the parent AUTH request.
X3-EN.png paymenttypedescription Alpha Max 20

Payment method (e.g. “VISA” or “MASTERCARD”).
REFUND Response
REFUND Response
{
  "requestreference":"W23-22rd4301",
  "version":"1.00",
  "response":[{
    "accounttypedescription":"POS",
    "acquirerresponsecode":"00",
    "acquirerresponsemessage": "Approved or completed Successfully",
    "authcode":"TEST REFUND ACCEPTED",
    "baseamount":"2000",
    "currencyiso3a":"GBP",
    "errorcode":"0",
    "errormessage":"Ok",
    "issuer":"SecureTrading Test Issuer1",
    "issuercountryiso2a":"US",
    "livestatus":"0",
    "maskedpan":"411111######1111",
    "merchantcategorycode": "7001",
    "merchantcountryiso2a":"GB",
    "merchantname":"Test Merchant",
    "merchantnumber":"00000000",
    "operatorname":"webservices@example.com",
    "orderreference":"My_Order_123",
    "parenttransactionreference":"1-2-345678",
    "paymenttypedescription":"VISA",
    "requesttypedescription":"REFUND",
    "securityresponseaddress":"0",
    "securityresponsepostcode":"0",
    "securityresponsesecuritycode":"0",
    "settleduedate":"2016-12-07",
    "settlestatus":"0",
    "transactionreference":"1-2-345679",
    "transactionstartedtimestamp":"2016-12-07 15:31:48"
  }],
  "secrand":"SNQVg"
}

 

Field specification

Required Field Format Length Description
X4-EN.png accounttypedescription Alpha Max 20 The type of account used to process the refund. Expect "POS" to be returned when performing POS transactions.
X4-EN.png baseamount Numeric Max 13 The amount of the refund in base units, with no commas or decimal points, so £10 is submitted as 1000.
X4-EN.png currencyiso3a ISO3A Max 3

The currency of the refund.

Click here for a full list of available currencies.
X4-EN.png errorcode Numeric 1-5 The error code should be used to determine if the refund was successful or not.
  • If the error code is “0” then the refund was successful.
  • If the error code is not “0” then the refund was not successful.

Click here for a full list of errorcode and message values.
X4-EN.png errormessage Alphanumeric Max 255 This provides a brief explanation as to the cause of the error.

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

Click here for a full list of errorcode and message values.
X4-EN.png issuer Alphanumeric Max 255 The customer’s card issuer.
X4-EN.png issuercountryiso2a ISO2A 2

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

Click here for a full list of country codes.
X4-EN.png livestatus Numeric 1
  • 0 – Refund processed using a test account.
  • 1 – Refund processed using a live account.
X4-EN.png maskedpan Alphanumeric including "#" 12-19 The maskedpan field represents the customer’s card number. The value of maskedpan field is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
X4-EN.png merchantnumber Alphanumeric Max 32 The merchant number that was used to process the refund. Provided by the acquiring bank.
X4-EN.png operatorname Alphanumeric Max 255 The value of this field contains the name of the user that processed the refund.
X4-EN.png paymenttypedescription Alpha Max 20 Payment method (e.g. “VISA” or “MASTERCARD”).
X4-EN.png requesttypedescription Alpha Max 20 “REFUND” is returned in the response.
X4-EN.png securityresponseaddress Numeric 1 The result of AVS and Security Code Checks.

Click here to learn more.
X4-EN.png securityresponsepostcode Numeric 1 The result of AVS and Security Code Checks.

Click here to learn more.
X4-EN.png securityresponsesecuritycode Numeric 1 The result of AVS and Security Code Checks.

Click here to learn more.
X4-EN.png settleduedate Date YYYY-MM-DD 10 The date on which the refund will be settled.
X4-EN.png settlestatus Numeric Max 3

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

Click here for a full list of settlestatus values.
X4-EN.png transactionreference Alphanumeric including hyphens Max 25 A unique reference for the refund assigned by Trust Payments. You will need this reference to update the refund.
X4-EN.png transactionstartedtimestamp Date time YYYY-MM-DD hh:mm:ss Max 19 The time the refund was processed.
X2-EN.png acquirerresponsecode Alphanumeric Max 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.
X2-EN.png acquirerresponsemessage Alphanumeric Max 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.
X2-EN.png authcode Alphanumeric Max 255

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

Only returned if the refund is authorised.
X2-EN.png cashbackbaseamount Numeric Max 13

The cashback amount requested by the customer.

This field is returned if available.
X2-EN.png errordata Alphanumeric Max 255

Additional information to help troubleshoot the error.

Only returned if there has been an error.
X2-EN.png merchantcategorycode Alphanumeric Max 255

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

Values returned depends on your account configuration.
X2-EN.png merchantcity Alphanumeric Max 127

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

Values returned depends on your account configuration.
X2-EN.png merchantcountryiso2a ISO2A Max 2

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

Values returned depends on your account configuration.
X2-EN.png merchantname Alphanumeric Max 255

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

Values returned depends on your account configuration.
X2-EN.png merchantstatecode Alphanumeric Max 127

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

Values returned depends on your account configuration.
X2-EN.png merchantzipcode Alphanumeric Max 10

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

Values returned depends on your account configuration.
X2-EN.png orderreference Alphanumeric including symbols Max 255

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

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

This field is returned if submitted in the request.
X2-EN.png parenttransactionreference Alphanumeric including hyphens Max 25

The transactionreference of the transaction being refunded, from which key details have been inherited.

This field is returned if submitted in the request.
X2-EN.png retrievalreferencenumber Alphanumeric Max 255

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

This will vary depending on your acquiring bank. Please contact your bank for further information.
X2-EN.png tid Alphanumeric Max 255

The terminal ID used to process the refund. This is accredited to your merchant number when we setup your account in our systems.

Whether this field is returned varies depending on your acquiring bank. Please contact our Support Team if you need assistance.

 

Update transaction

 

 

  TRANSACTIONUPDATE Overview

To perform updates on a processed transaction, you will need to submit a TRANSACTIONUPDATE request and handle the response returned. The TRANSACTIONUPDATE request consists of filters and updates.

 

  1. Filters
    • Think of filters as search criteria. Trust Payments will use these to find the transaction to update, perform the updates if possible and return a response as confirmation.
    • For example, a filter with transactionreference “1-2-345” would find and update the transaction matching this reference.
  2. Updates
    • There are a number of fields that can be updated, as described in the spec below.
    • For example, a pending transaction can be cancelled by updating the settlestatus to "3", following which reserved funds in the customer's account are automatically reversed.
    • The settlebaseamount can also be updated in order to settle a lower payment amount than was originally authorised.

  Processing TRANSACTIONUPDATE

TRANSACTIONUPDATE Request

The following are examples of TRANSACTIONUPDATE requests:

Issuer script Suspend Re-enable Cancel Partial settle 
{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "requesttypedescriptions":["TRANSACTIONUPDATE"],
    "filter":{
      "sitereference":[{"value":"test_site12345"}],
      "transactionreference":[{"value":"1-2-3"}]
    },
    "updates":{"issuerscriptresults":"8A023030A1"}
  }]
}

 

Filters field specification

Required Field Format Length Description
X1-EN.png sitereference Alphanumeric including underscore Max 50 The unique reference for the Trust Payments site associated with the transaction you would like to update.
X1-EN.png transactionreference Alphanumeric including hyphens Max 25 The unique Trust Payments reference for the transaction you would like to update.

 

Updates field specification

The following fields can be updated when performing updates on AUTH and REFUND requests.

Required Field Format Length Description
X3-EN.png issuerscriptresults Hexadecimal (0-9, A-F) 10

Only supported when updating AUTH with a response that contained iccdataresponse.

Commands sent by the customer's card issuer (known as "issuer scripts") can be extracted from the iccdataresponse. Once the terminal has executed these commands against the card, the results can be submitted as an update to the transaction using the issuerscriptresults field.

It is best practice that you perform this step after processing an AUTH request so our records are kept up-to-date.
X3-EN.png orderreference Alphanumeric including
symbols 		Max 25 Update the unique order reference that can be stored on the Trust Payments system.
X3-EN.png settlebaseamount Numeric Max 13 The amount of the transaction in base units, with no commas or decimal points, so £10.50 would be 1050. This value must be above zero and less than or equal to the original authorisation amount.
X3-EN.png settleduedate Date YYYY-MM-DD Max 10 Date the transaction will be settled. If today or earlier, the transaction will settle when Settlement is next run (providing not suspended or cancelled).
X3-EN.png settlestatus Numeric Max 3 This value relates to the status of the transaction.
TRANSACTIONUPDATE Response

Please find below an example of a TRANSACTIONUPDATE response that was returned following a successful transaction update.

TRANSACTIONUPDATE response
{
  "requestreference":"W23-tkrxwkc6",
  "version":"1.00",
  "response":[{
    "errorcode":"0",
    "errormessage":"Ok",
    "requesttypedescription":"TRANSACTIONUPDATE",
    "transactionstartedtimestamp":"2019-12-17 10:58:20"
  }],
  "secrand":"SptlJutnBnQ"
}

Ensure the Error Code is “0”. This indicates the TRANSACTIONUPDATE request was processed successfully. If the error code is not “0”, the request may not have been processed as expected.

 

Field specification

Required Field Format Length Description
X4-EN.png errorcode Numeric Max 5 The error code should be used to determine if the update was successful or not.
  • If the error code is “0” then the update was successful.
  • The error code "20004" (Missing parent) can sometimes be returned if you attempt an update too soon after processing the initial request. If this happens, wait a few seconds and retry.
  • If the error code is not “0” then the update was not successful.

Click here for a full list of errorcode and message values.
X4-EN.png errormessage Alphanumeric Max 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.
X4-EN.png requesttypedescription Alpha Max 20 “TRANSACTIONUPDATE” is returned in the response.
X4-EN.png transactionstartedtimestamp Date time YYYY-MM-DD hh:mm:ss 19 The time the update was processed.
X2-EN.png errordata Alphanumeric Max 255

Additional information to help troubleshoot the error.

Only returned if there has been an error.

 

Query transaction

 

 

  TRANSACTIONQUERY Overview

To view details and check the status regarding a processed transaction, you will need to submit a TRANSACTIONQUERY request and handle the response returned.

 

  1. Filters
    • The TRANSACTIONQUERY request consists primarily of filters. Think of filters as search criteria; the response returned will contain information meeting the specified filters.
    • For example, a filter with transactionreference “1-2-345” would return stored details for said transaction.
  2. Advanced searching
    • If a query matches multiple requests, all of these will be returned in a single response. If you want to avoid this outcome, we recommend being as specific as reasonably possible in your request, by submitting as many filters as required.
    • For example, specifying a starttimestamp and endtimestamp will return details of all requests processed on your account between the specified times.
    • You can also submit multiple values for each given filter. e.g. You can submit a filter for transactionreference values “23-9-1” and “23-9-2”, and any requests matching these values will be returned in the response. (We include an example of this case below)

  Processing TRANSACTIONQUERY

TRANSACTIONQUERY Request

For the TRANSACTIONQUERY request to be processed successfully, you need to submit at least one valid filter.

 

TRANSACTIONQUERY Request
{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "requesttypedescriptions":["TRANSACTIONQUERY"],
    "filter":{
      "sitereference":[{"value":"test_site12345"}],
      "transactionreference":[{"value":"23-9-1"},{"value":"23-9-2"}]
    }
  }]
}

 

Field specification

The following table lists all fields that you can include in the filter when processing a TRANSACTIONQUERY request.

  Although none of the following filter fields are required, at least one filter must be submitted for the request to be processed successfully. For this reason, most of the fields have been marked below as conditional.

An exception to this behaviour is the sitereference filter, which cannot be submitted on its own; it must be accompanied by at least one other filter. This restriction is enforced to reduce load on our servers.

Required Field Format Length Description
X2-EN.png accounttypedescription Alpha Max 20 The type of account used to process the request. Submit "POS" to filter POS transactions.
X2-EN.png billingpostcode Alphanumeric including symbols Max 25 The billing postcode or ZIP code. This must be a valid postcode/ZIP code for the billingcountryiso2a submitted.
X2-EN.png billingpremise Alphanumeric including symbols Max 20 The number or name of the premise of the customer’s billing address.
X2-EN.png billingstreet Alphanumeric including symbols Max 20 The street name of the customer’s billing address.
X2-EN.png currencyiso3a ISO3A 3

The transaction currency.

Click here for a full list of currency codes.
X2-EN.png endtimestamp Date Time YYYY-MM-DD HH:MM:SS Max 19 Only requests processed before the timestamp specified will be returned.

(Unlike with other filters, you can only submit one endtimestamp in a request)
X2-EN.png orderreference Alphanumeric including symbols Max 25 Unique reference number you supply for the request.
X2-EN.png pan Numeric 12-19 This is the card number printed on the front of the customer’s card.
X2-EN.png parenttransactionreference Alphanumeric including hyphens Max 25 Unique reference of the parent request.
X2-EN.png paymenttypedescription Alpha Max 20 The customer’s card type (e.g. “VISA” or “MASTERCARD”).
X2-EN.png requesttypedescription Alpha Max 20

The request type associated with transaction. For example, “AUTH” or “REFUND”.

Click here for a full list of request types.
X2-EN.png starttimestamp Date Time YYYY-MM-DD HH:MM:SS Max 19 Only requests processed after the timestamp specified will be returned.

(Unlike with other filters, you can only submit one starttimestamp in a request)
X2-EN.png transactionreference Alphanumeric including hyphens Max 25 The unique reference associated with the transaction, assigned by Trust Payments.
X3-EN.png sitereference Alpha Max 50

The site reference that processed the transaction.

The sitereference filter must be submitted with at least one other filter, otherwise an error will be returned.
TRANSACTIONQUERY Response

Once you have successfully submitted a TRANSACTIONQUERY request, you will be returned a response that is divided into separate records.

Each record will contain a varying number of response fields, which depend on the request type indicated in the record. For example, if the record has a requesttypedescription of “AUTH“, then you would need to refer to the field specification in the Authorisation.

Additionally, the response contains a field called found, which indicates the number of records that match the filters specified in the request. If found has a value of  “0”, no records have been found using your specified filters.

For example, here is a simplified example of the structure of the response, consisting of 2 records (both are type “AUTH”):

TRANSACTIONQUERY response
{"requestreference":"W72-pg3q2he9",
  "version":"1.00",
  "response":[{
    "errorcode":"0",
    "errormessage":"Ok",
    "found":"2",
    "records":[{
      "accounttypedescription":"POS",
      "acquirerresponsecode":"00",
      "acquirerresponsemessage": "Approved or completed Successfully",
      "authcode":"TEST22",
      "baseamount":"1050",
      "currencyiso3a":"GBP",
      "errorcode":"0",
      "errormessage":"Ok",
      "expirydate":"10\/2022",
      "fraudrating":"0",
      "interface":"PASS-JSON-JSON",
      "issuer":"Test Issuer",
      "issuercountryiso2a":"GB",
      "livestatus":"0",
      "maskedpan":"411111######1111",
      "merchantcategorycode": "7001",
      "merchantcountryiso2a":"GB",
      "merchantname":"Test Merchant",
      "operatorname":"webservices@example.com",
      "orderreference":"My_Order_123",
      "paymenttypedescription":"VISA",
      "requesttypedescription":"AUTH",
      "retrievalreferencenumber": "300316080007",
      "securityresponseaddress":"0",
      "securityresponsepostcode":"0",
      "securityresponsesecuritycode":"2",
      "settlebaseamount":"1050",
      "settleduedate":"2019-12-17",
      "settlestatus":"0",
      "sitereference":"test_site12345",
      "terminalid":"12345678",
      "transactionreference":"23-9-1",
      "transactionstartedtimestamp":"2019-12-17 09:35:03"
    },
    {
      "accounttypedescription":"POS",
      "acquirerresponsecode":"00",
      "acquirerresponsemessage": "Approved or completed Successfully",
      "authcode":"TEST03",
      "baseamount":"1050",
      "currencyiso3a":"GBP",
      "errorcode":"0",
      "errormessage":"Ok",
      "expirydate":"10\/2022",
      "fraudrating":"0",
      "interface":"PASS-JSON-JSON",
      "issuer":"SecureTrading Test Issuer1",
      "issuercountryiso2a":"US",
      "livestatus":"0",
      "maskedpan":"411111######1111",
      "merchantcategorycode": "7001",
      "merchantcountryiso2a":"GB",
      "merchantname":"Test Merchant",
      "operatorname":"webservices@example.com",
      "orderreference":"My_Order_123",
      "paymenttypedescription":"VISA",
      "requesttypedescription":"AUTH",
      "retrievalreferencenumber": "300316080007",
      "securityresponseaddress":"0",
      "securityresponsepostcode":"0",
      "securityresponsesecuritycode":"2",
      "settlebaseamount":"1050",
      "settleduedate":"2019-12-17",
      "settlestatus":"0",
      "sitereference":"test_site12345",
      "terminalid":"12345678",
      "transactionreference":"23-9-2",
      "transactionstartedtimestamp":"2019-12-17 09:35:10"
    }],
    "requesttypedescription":"TRANSACTIONQUERY",
    "transactionstartedtimestamp":"2019-12-17 09:36:21"
  }],
  "secrand":"uISZfw8wKWR"
}

  A maximum of 500 records can be returned per response.

The found field will never return a value higher than 500, even if more than 500 requests meet the specified criteria.

 

Understanding errors

Please ensure you understand the Error Codes returned in the response:

  • At the highest level of the response, along with transactionstartedtimestamp and found, there is an errorcode. This indicates whether or not the TRANSACTIONQUERY request was successful. If the error code here is not “0”, the TRANSACTIONQUERY request was not successful. You must address the problem and try again.
  • In addition to this, each record will contain their own errorcode. This indicates whether or not the request represented in the record was successful.
  • For a full list of error codes used by Trust Payments, click here.

 

Field specification

The following table lists all fields that can be returned in a given record.

  Fields are only returned if the data is available for the request queried.
This can vary depending on request type.

Required Field Format Length Description
X4-EN.png accounttypedescription Alpha Max 20 The type of account used to process the request queried. Expect "POS" to be returned when querying POS transactions.
X4-EN.png baseamount Numeric Max 13

The amount of the transaction queried in base units, with no commas or decimal points, so £10 is submitted as 1000.

  Mastercard can decline cashback requests. If this happens, the cashbackbaseamount field is returned with value "0" and this amount is also subtracted from the total baseamount returned.
X4-EN.png currencyiso3a ISO3A 3

The currency of the transaction queried.

Click here for a full list of available currencies.
X4-EN.png errorcode Numeric Max 5 The error code should be used to determine whether the request(s) being queried was successful.
  • 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.
X4-EN.png errormessage Alphanumeric Max 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.
X4-EN.png interface Alphanumeric including symbols Max 50

Represents the interface through which the queried request was processed. The following are common examples:

  • "JWT-JWT-JWT" - JavaScript Library or Mobile SDK.
  • "MYST" - MyST (e.g. Refund, Virtual terminal or Payout terminal).
  • "PASS-JSON-JSON" - Webservices API using JSON markup.
  • "PASS-XML-XML" - Webservices API using XML markup.
X4-EN.png livestatus Numeric 1
  • 0 – The queried transaction was processed using a test account.
  • 1 – The queried transaction was processed using a live account.
X4-EN.png

maskedpan

 Alphanumeric including “#” 12-19

The maskedpan field represents the customer’s card number. The value of maskedpan field is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
X4-EN.png operatorname Alphanumeric Max 255 The value of this field contains the name of the user that processed the request.
X4-EN.png paymenttypedescription Alpha Max 20 Payment method (e.g. “VISA” or “MASTERCARD”).
X4-EN.png requesttypedescription Alpha Max 20 The type of request returned in the record.
X4-EN.png settlebaseamount Numeric Max 13

The value of amount to be settled. The amount settled can be updated to be lower than the amount initially authorised using a TRANSACTIONUPDATE request.

X4-EN.png settleduedate Date YYYY-MM-DD Max 10 The date on which the queried transaction will be settled.
X4-EN.png settlestatus Numeric Max 3

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

Click here for a full list of settlestatus values.
X4-EN.png sitereference Alphanumeric
& underscore 		Max 50

The site reference through which the queried request was processed.
X4-EN.png terminalid Alphanumeric 8 POS terminal identifier.
X4-EN.png transactionreference Alphanumeric including
hyphens 		Max 25 A unique reference for the queried transaction assigned by Trust Payments. You will need this reference to perform a refund or update the transaction.
X4-EN.png transactionstartedtimestamp  Date time YYYY-MM-DD hh:mm:ss Max 19 The time the queried transaction was processed.
X2-EN.png

acquirerresponsecode

 Alphanumeric Max 255

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

Whether these fields are returned vary depending on your acquiring bank. Please contact our Support Team if you need assistance.
X2-EN.png

acquirerresponsemessage

 Alphanumeric Max 255
X2-EN.png authcode Alphanumeric Max 255

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

Only returned if the queried transaction was authorised.
X2-EN.png billingpostcode Alphanumeric Max 25

The postcode entered for the customer’s billing address.

This field is returned if available.
X2-EN.png billingpremise Alphanumeric including
symbols 		Max 25

The house number or first line of the customer’s billing address.

This field is returned if available.
X2-EN.png billingstreet Alphanumeric including
symbols 		Max 127

The street entered for the customer’s billing address.

This field is returned if available.
X2-EN.png cashbackbaseamount Numeric Max 13

The cashback amount requested by the customer.

  Mastercard can decline cashback requests. If this happens, cashbackbaseamount is shown with value "0".

This field is returned if available.
X2-EN.png chargedescription Alphanumeric including
symbols 		Max 25

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

This field is returned if available.
X2-EN.png errordata Alphanumeric Max 255

Additional information to help troubleshoot the error.

Only returned if there has been an error.
X2-EN.png expirydate Date MM/YYYY Max 7

The expiry date printed on the card.

Only returned for card transactions.
X2-EN.png fraudrating Numeric Max 2

This field pertains to our internal fraud checks, as documented in this article. This value represents the queried transaction's currently-assigned fraud rating.

This feature is opt in. If not enabled on your site reference, 0 will always be returned.

If you have opted in:

  • -1 indicates checks are pending.
  • The higher the fraud rating, the greater the number of suspicious characteristics that have been identified by our fraud system.
  • By default, we will notify you of transactions that have a fraud rating of 2 or higher.
  • By default, we will suspend all transactions that have a fraud rating of 5 or higher.

Click here to learn more.

Only returned for card transactions.
X2-EN.png issuer Alphanumeric Max 255

The customer’s card issuer.

Only returned for card transactions.
X2-EN.png issuercountryiso2a ISO2A 2

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

Click here for a full list of country codes.

Only returned for card transactions.
X2-EN.png merchantcategorycode Alphanumeric Max 255

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

Values returned depends on your account configuration.
X2-EN.png merchantcity Alphanumeric Max 127

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

Values returned depends on your account configuration.
X2-EN.png merchantcountryiso2a ISO2A 2

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

Values returned depends on your account configuration.
X2-EN.png merchantname Alphanumeric Max 255

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

Values returned depends on your account configuration.
X2-EN.png merchantstatecode Alphanumeric Max 127

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

Values returned depends on your account configuration.
X2-EN.png merchantzipcode Alphanumeric Max 10

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

Values returned depends on your account configuration.
X2-EN.png orderreference Alphanumeric including
symbols 		Max 25

The unique order reference for the request queried that is stored on the Trust Payments system.

This field is returned if available.
X2-EN.png parenttransactionreference Alphanumeric
& hyphens 		Max 25

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

This field is returned if available.
X2-EN.png retrievalreferencenumber Alphanumeric Max 255

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

This field is returned if available. This will vary depending on your acquiring bank. Please contact your bank for further information.
X2-EN.png securityresponseaddress Numeric 1

The result of AVS and Security Code Checks. These contain one of the following values:

  • 0 - Acquirer not provided with info required to perform this check.
  • 1 - Acquirer unable to perform checks on info provided.
  • 2 - Info provided by customer matches that found on card issuer's records.
  • 4 - Info provided by customer does NOT match that found on card issuer's records.

Click here to learn more.

These fields are returned if available.
X2-EN.png securityresponsepostcode Numeric 1
X2-EN.png securityresponsesecuritycode Numeric 1
X2-EN.png settledtimestamp Date time YYYY-MM-DD hh:mm:ss Max 19

The date and time the queried transaction was settled.

Only returned if transaction if transaction has been settled.
X2-EN.png stan ISO 8583 Undefined

The STAN (System Trace Audit Number) associated with the transaction. This follows the ISO 8583 standard.

This field is returned if available.
X2-EN.png tid Alphanumeric Max 255

The terminal ID used to process the queried transaction. This is accredited to your merchant number when we setup your account in our systems.

Whether this field is returned varies depending on your acquiring bank. Please contact our Support Team if you need assistance.
X2-EN.png updatereason Alphanumeric Max 255

The most recent party to perform an update on the transaction returned. If the transaction was never updated after the initial request was sent, this field will not be populated. Common examples:

  • The username of user that performed the update.
  • "rulemanager" - Transaction was updated by our Rule manager.
  • "securitypolicy" - Transaction was updated as per the security policy on your account.
  • "settle" - Transaction was updated by our settlement engine.
  • "duplicate" - Transaction was deemed a duplicate and suspended by our duplicate checks.

This field is returned if available.
Was this article helpful?
0 out of 0 found this helpful
Avatar
Michael Buckley

 

Further reading on this topic