(c) PCI Pal 2020. The content on this page is subject to the Disclaimer Section (found on the Introduction page)
Secure Trading Gateway
This page details the inputs, secure inputs and outputs available for the Secure Trading Payment Gateway, how to complete each field, and an external link to the Secure Trading integration documentation.
PCI Pal must check any payment gateway integrations prior to going live. The documentation disclaimer (which applies throughout this guide) should be read before commencing any configuration of payment gateways.
Inputs
Input Fields
Required
Character Limits/
Required Input
Description
alias
Yes
n/a
unique value provided to the customer by Secure Trading
baseamount
Yes
13n
The amount in the final currency.
paymenttypedescription
Yes
20 char
Card Type - e.g. VISA
orderreference
Yes
255 an
Unique payment reference
sitereference
Yes
50 an
Unique merchant ID given to the merchant from SecureTrading
currencyiso3a
Yes
3 char
The final currency. E.G. USD, GBP, EUR
requesttypedescription
Yes
20 char
Request type - e.g. AUTH.
billingprefixname
No
25 char
Billing name Prefix (e.g. Miss)
billingfirstname
No
127 char
Billing first name
billingmiddlename
No
127 char
Billing Middle Name
billinglastname
No
127 char
Billing Last Name
billingsuffixname
No
25 char
Billing Suffix (e.g. Jr.)
billingstreet
No
127 char
Billing street
billingpremise
No
127 an
Billing address premise
billingtown
No
127 char
Billing address town/city
billingcounty
No
127 char
Billing address county
billingpostcode
No
25 an
Billing address postcode
billingcountryiso2a
No
2 char
Billing address country
billingtelephone
No
15 num
Billing telephone number
billingtelephonetype
No
1 char
The type of telephone number. The options available are:
H = Home
M = Mobile
W = Work
billingemail
No
255 char
Billing email address
customerprefixname
No
25 char
Customer name Prefix (e.g. Miss)
customerfirstname
No
127 char
Customer first name
customermiddlename
No
127 char
Customer Middle Name
customerlastname
No
127 char
Customer Last Name
customerstreet
No
127 char
Customer street
customerpremise
No
127 an
Customer address premise
customertown
No
127 char
Customer address town/city
customerpostcode
No
25 an
Customer address postcode
customertelephone
No
15 num
Customer telephone number
customertelephonetype
No
1 char
The type of telephone number. The options available are:
H = Home
M = Mobile
W = Work
parenttransactionreference
No
25an
Allows you to specify the transactionreference of a previous request.
dccoffered
No
1 num
This value represents whether the customer has chosen to pay using the customer’s currency or the merchant’s currency.
1 – Customer has chosen to pay in the customer’s currency.
2 – An error has occurred that has prevented the customer from paying in the customer’s currency (e.g. the CURRENCYRATE response returned an error), so they are completing the payment in the merchant’s currency instead.
3 – Customer has chosen to pay in the merchant’s currency.
dccconversionrate
No
1n.3n
The conversion rate used to calculate the amount in the customer’s currency.
dcccurrencyiso3a
No
3 char
The merchant’s currency. E.G. USD, GBP, EUR
dccbaseamount
No
13n
The amount in the merchant’s currency.
username
Yes
n/a
Unique API username given to the merchant from SecureTrading
password
Yes
n/a
Unique API password given to the merchant from SecureTrading
requestType
Yes
n/a
Request type - either AUTH or REFUND
initiationReason
No
1 char
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)
settleDueDate
No
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. This date is returned in the response.
settleStatus
No
3 num
A numeric value used to define the settlement instruction. If you do not submit a value here, the settlestatus defaults to “0”.
authMethod
No
5 an
Auth methods are used to specify how a transaction is to be processed by the card issuer
merchantEmail
No
255 an
Merchant email address
chargeDescription
No
25 an
This is a description of the payment that appears on the customer’s bank statement.
operatorName
No
255 an
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).
credentialsOnFile
No
1 num
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.
Secure Inputs
Input Fields
Required
Character Limits/
Required Input
Description
pan
Yes
19 chars
Secure input of the card number
expiryMonth
Yes
2 chars
Secure input of the card expiry - in the format MM
expiryYear
Yes
2 chars
Secure input of the card expiry - in the format YY
securitycode
Yes
3 or 4 chars
Secure input of the card CVV, either three or four digits long depending on the card
Outputs
Output Fields
Description
baseamount
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)
paymenttypedescription
Payment method (e.g. “VISA” or “MASTERCARD”)
issuer
The customer’s card issuer.
issuercountryiso2a
The country for the customer’s card issuer. This will be in ISO2A format.
merchantemail
The merchant’s email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
orderreference
Your unique order reference that can be stored on Secure Trading’s system.
chargedescription
This is a description of the payment that appears on the customer’s bank statement.
Only supported by certain acquiring banks.
Valid characters:
Uppercase/lowercase A-Z
Numbers 0-9
Spaces
Punctuation: + – _ . @ ( )
transactionstartedtimestamp
The time the transaction was processed.
parenttransactionreference
Allows you to specify the transactionreference of a previous request.
livestatus
“0” – Transaction processed on test site.
“1” – Transaction processed on live site.
dccenabled
Indicates if your account is configured for DCC:
1= Yes
0 = No
settleduedate
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
dcctype
Set to 'DCC' when DCC payments are enabled
dccratio
1 – Customer has chosen to pay in the customer’s currency.
2 – An error has occurred that has prevented the customer from paying in the customer’s currency (e.g. the CURRENCYRATE response returned an error), so they are completing the payment in the merchant’s currency instead.
3 – Customer has chosen to pay in the merchant’s currency.
dccbaseamount
The amount in the merchant’s currency.
errorcode
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.
tid
The terminal ID used to process the transaction. This is accredited to your merchant number when we setup your account in our systems.
merchantnumber
These are details associated with the account used to process the transaction
merchantcountryiso2a
These are details associated with the account used to process the transaction
transactionreference
A unique reference for the transaction assigned by Secure Trading. You will need this reference to perform a refund or update the transaction.
merchantname
These are details associated with the account used to process the transaction
accounttypedescription
For Mail Order or Telephone Order (MOTO) requests, the value should be “MOTO”
acquirerresponsecode
Used by your acquirer to indicate the outcome of the request.
requesttypedescription
Will return back as AUTH
securityresponsesecuritycode
The result of AVS and Security Code Checks.
authcode
The authorisation code provided by the issuing bank. This will differ depending on which bank you use.
errormessage
This is the corresponding message to the above code.
operatorname
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.
maskedpan
The customer’s card number. This is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
dccconversionrate
Conversion rate for DCC enabled payments
securityresponseaddress
The result of AVS and Security Code Checks.
securityresponsepostcode
The result of AVS and Security Code Checks.
issuercountryiso2a
2 digit ISO code for the customers issuers bank.
settlestatus
A numeric value used to define the settlement instruction. If you do not submit a value here, the settlestatus defaults to “0”.
requestreference
Unique request reference to the payment
secrand
Random string of characters, returned in the response of non-API-based libraries developed by Secure Trading.
We will require the API Username and API Password in order to generate the Basic Authentication Header value that gets sent in with every request.
Further information can be found by viewing the integration documentation:
