Payment Request

ProtocolVersion

3

3

"^([0-9.]*)$"

Packet protocol version. Set as 1.0.

MerchantId

5

12

"^([a-zA-Z0-9-_]*)$"

Each merchant (site) is assigned a unique merchant identifier that must be presented in each request.

PosID

1

32

"^([a-zA-Z0-9-_]*)$"

POS should indicate the name of the POS station. This value is not used by the gateway but is echoed back in the Payment response.

TransactionDateTime

25

25

"YYYY-MM-DDTHH:mm:ss+hh:mm"

Date and time of the transaction with time zone offset from GMT.

ClientTransactionReference

36

36

"^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}$"

POS must create a GUID for the transaction and present it in the request in this field.

Attempt

1

5

"^([0-9]*)$"

For the first Payment request for this payment, the POS must set the attempt to 1. If communications fail with the gateway before a response is received, the POS can reissue the same request using the same ClientTransactionReference value but with the Attempt field incremented by 1.

TransactionMode

1

1

"^[M]|[P]$"

Process this payment as a customer present or customer not present transaction. Valid values are the following:

M: Customer not present

P:  Customer present

TransactionType

1

1

"^[A]|[F]$"

This payment is a sale or refund transaction. Valid values are the following:

A: Sale

F: Refund

TransactionCurrency

3

3

"^([A-Z]*)$"

ISO alpha currency code of the payment.

e.g. EUR/GBP

TransactionAmount

10

10

"^([0-9]*)$"

Payment value in the lowest denomination of the above currency.

e.g. EUR12.99 would be presented in the request as 1299.

ReferenceData

0

32

"^([a-zA-Z0-9-_: ])*$"

This is a POS-defined optional reference value, such as an invoice number, that is stored with the transaction on the gateway and can be provided in end-of-day reports to the merchant.

TerminalName

8

8

"^([0-9]*)$"

Terminal identifier of the card terminal on which the payment must be processed.

AllowDcc

1

1

Boolean (“true”,”false”)

POS can indicate if the card presented by the customer is eligible for dynamic currency conversion (DCC) and then offer the customer a rate on the terminal. Merchant must be enabled for DCC on the gateway.

AllowCashback

3

3

Boolean (“true”,”false”)

POS can indicate if the card presented by the customer is eligible for cashback and then offer the customer a cashback option on the terminal.

Note: Cashback is currently not supported.

AllowGratuity

10

10

Boolean (“true”,”false”)

POS can indicate if gratuity should be offered on the terminal. Merchant must be enabled for gratuity on the gateway.

Note: Gratuity is currently not supported.

AllowCharityDonation

0

32

Boolean (“true”,”false”)

POS can indicate if donation acceptance should be offered on the terminal. Merchant must be enabled for donation acceptance on the gateway.

Note: Donation is currently not supported.

ResponseCode

1

1

"^[A]|[D|[R]$"

Upon receipt of the Payment response from gateway, this is the field to check what the outcome of the transaction is. Valid values are the following:

A: Transaction has been authorised.

D: Transaction has been declined.

R: Transaction has been referred.

Note: Referred transactions are not currently supported.

ResponseMessage

1

32

"^([a-zA-Z0-9-_: ])*$"

Verbose message such as 'AUTH CODE: xyz' for an authorised transaction or 'DECLINED' for a declined transaction. 

TransactionType

0

10

"^[A]|[F]$"

TransactionType in the Payment request will be echoed back in this field.

TransactionCurrency

0

3

"^([A-Z])*$"

TransactionCurrency in the Payment request will be echoed back in this field.

TransactionAmount

0

10

"^([0-9]*)$"

TransactionAmount in the Payment request will be echoed back in this field.

CashbackAmount

0

10

"^([0-9]*)$"

If cashback was offered and accepted on the terminal, this field will contain the cashback amount in the lowest denomination of the transaction currency.

GratuityAmount

0

10

"^([0-9]*)$"

If gratuity was offered and accepted on the terminal, this field will contain the gratuity amount in the lowest denomination of the transaction currency.

CharityDonationAmount

0

10

"^([0-9]*)$"

If donation was offered and accepted on the terminal, this field will contain the donation amount in the lowest denomination of the transaction currency.

TransactionMode

0

1

"^[M]|[P]$"

This field indicates how the transaction was processed. Valid values are the following:

M: Customer not present

P:  Customer present

DataEntryMode

0

1

"^[D]|[C]|[S]|[K]$"

This field indicates how the transaction was processed with respect to the card presented. Valid values are the following:

D: Transaction was processed as a chip transaction.

C: Transaction was processed as a contactless transaction.

S: Transaction was processed as a swiped transaction.

K: Transaction was processed as a keyed transaction.   

CustomerVerification

0

1

"^[X|[S]|[F]|[N]|[P]$"

This field indicates how the customer was verified. Valid values are the following:

X: No verification

S: Signature

F: Offline Pin

N: Online Pin

P: Online Pin

B: Pin and Signature

TransactionRRN

0

32

"^([0-9]*)$"

This field contains a unique transaction identifier that the POS will use for payment completion.

AuthCode

0

8

"^([a-zA-Z0-9])*$"

If the payment was authorised, this field will contain the authorisation code.

MerchantNumber

0

15

"^([a-zA-Z0-9])*$"

This field contains the merchant's acquiring merchant number used for authorisation.

TerminalId

0

8

"^([0-9]*)$"

This field contains the terminal ID of the terminal used for processing the payment.

Cv2Response

0

1

"^[0]|[1]|[2]|[3]|[4]$"

This field indicates the outcome of any CV2 checking that may have been done for a customer not present transaction. Valid values are the following:

M: CV2 matched

N: CV2 not matched

C: CV2 not checked

<blank> : No CV2 result

AvsResponse

0

1

"^[M|[N]|[C]|[P]$"

This field indicates the outcome of any CV2 checking that may have been done for a customer not present transaction. Valid values are the following:

M: AVS detail matched

N: AVS detail not matched

C: AVS detail not checked

P: AVS partially match

<blank> : No AVS result

Cv2AvsMessage

0

32

"^([a-zA-Z0-9 ])*$"

If CV2/AVS processing was performed as part of a customer not present transaction, this field will contain a verbose message such as 'CV2 match only' or 'All data matched'.

ReferenceData

0

32

"^([a-zA-Z0-9-_: ])*$"

If reference data was provided in the Payment request, it will be echoed back in the Payment response in this field.

DccStatus

0

15

"^[0|[1]|[2]|[3]$"

This field contains the outcome of Dynamic currency conversion (DCC) processing. Valid values are the following:

0: Customer is not eligible for DCC.

1: Gateway is unable to offer DCC.

2: DCC offering is rejected by customer.

3: DCC offering is accepted by customer.

If DCC was accepted by the customer, the Payment response will contain a DccAcceptance section that will contain information related to DCC.

Scheme

0

16

"^([a-zA-Z ])*$"

This field contains the card scheme name of the card used when processing the payment.

e.g. 'visa' or 'debit mastercard'

First6Pan

0

6

"^([0-9]*)$"

This field contains the first 6 digits of the customer's card number.

Last4Pan

0

4

"^([0-9]*)$"

This field contains the last 4 digits of the customer's card.

DccGratuity

0

10

"^([0-9]*)$"

Gratuity amount in the lowest denomination of the currency specified by DccCurrencyCode.

DccAmount

1

10

"^([0-9]*)$"

Dcc amount in the lowest denomination of the currency specified by DccCurrencyCode.

DccCurrencyCode

3

3

"^([A-Z])*$"

Customer's currency in ISO alpha format.

e.g. 'USD'

DccCurrencyExponent

1

1

"^([0-9]*)$"

Currency exponent of the currency specified by DccCurrencyCode.

DccExchangeRate

1

10

"^([0-9.]*)$"

Exchange rate accepted by the customer.

e.g '1.2345'

CustomerReceipt

1

4096

"^([a-zA-Z0-9-_:# ])*$"

This field contains a constructed customer receipt with each line of the receipt separated by a '#' character. For receipt printing purposes, the POS should replace the '#' character with a linefeed / carriage return and send to the printer.

Receipts data are returned without a site name and address. The POS needs to prepend this information to the receipt data before printing.

MerchantReceipt

1

4096

"^([a-zA-Z0-9-_:# ])*$"

This field contains a constructed merchant receipt with each line of the receipt separated by a '#' character. For receipt printing purposes, the POS should replace the '#' character with a linefeed / carriage return and send to the printer.

Receipts data are returned without a site name and address. The POS needs to prepend this information to the receipt data before printing.