Method: HTTP POST
Format: JSON
Direction: POS (integrator) -> Gateway
The Payment Inquiry request is used to retrieve payment detail for a previously processed payment. The POS has to specify the original CliientTransactionReference or TransactionRNN of the original payment.
Request
The Payment Inquiry request is constructed with the following sections:
PaymentInquiryRequest { Header{…} Detail{…} }
Header Section
Field |
Min |
Max |
Format |
Description |
---|---|---|---|---|
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. |
ClientDateTime |
25 |
25 |
"YYYY-MM-DDTHH:mm:ss+hh:mm" |
Date and time of the POS 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]*)$" |
This field should always be set to '1'. If the POS does not receive a response to a Payment Inquiry request, it can reissue another Payment Inquiry request but with a newly created ClientTransactionReference. |
Detail Section
Field |
Min |
Max |
Format |
Description |
---|---|---|---|---|
OriginalClientReference |
0 |
36 |
"^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}$" |
This is the unique client transaction reference of the payment being requested. If not specified, the TransactionRRN must be specified. |
TransactionRRN |
0 |
321 |
"^([0-9]*)$" |
This is the unique transaction identifier of the payment being requested. If not specified, the OriginalClientReference must be specified. |
DuplicateReceipt |
0 |
5 |
Boolean (“true”,”false”) |
The POS can use this field to indicate that the gateway should construct and return a duplicate receipt, i.e. the gateway should indicate at the end of a returned receipt that this is a duplicate receipt. |
Response
The Payment Inquiry response is constructed with the following sections:
PaymentInquiryResponse { Header{…} Detail{…} DccAcceptance{…} ReceiptData{…} }
Header Section
Field |
Min |
Max |
Format |
Description |
---|---|---|---|---|
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 ID echoed back from the Payment Inquiry request. |
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}$" |
ClientTransactionReference echoed back from the Payment Inquiry request. |
ClientDateTime |
25 |
25 |
"YYYY-MM-DDTHH:mm:ss+hh:mm" |
Date and time of the Payment request with time zone offset from GMT. |
Attempt |
1 |
5 |
"^([0-9]*)$" |
Attempt value echoed back from the Payment Inquiry request. |
Detail Section
Field |
Min |
Max |
Format |
Description |
---|---|---|---|---|
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. |
DccAcceptance Section
Field |
Min |
Max |
Format |
Description |
---|---|---|---|---|
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' |
ReceiptData Section
Field |
Min |
Max |
Format |
Description |
---|---|---|---|---|
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. |
Payment Inquiry Request Example
{ "PaymentInquiryRequest": { "Header": { "ProtocolVersion":1.0, "MerchantId":"PRCLIENT-CLOUDRETAIL-IRL", "PosID":"90005504", "ClientDateTime":"2023-02-09T09:26:39+00:00", "ClientTransactionReference":"8f44bc0c-f200-400a-9cfa-b2f0f44e2e42", "Attempt":1 }, "Detail": { "TransactionRRN":"107002508813" } } }
Payment Inquiry Response Example
{ "PaymentInquiryResponse": { "Header": { "ProtocolVersion":1.0, "MerchantId":"PRCLIENT-CLOUDRETAIL-IRL", "PosID":"90005504", "ClientDateTime":"2023-02-09T09:26:39+00:00", "ClientTransactionReference":"8f44bc0c-f200-400a-9cfa-b2f0f44e2e42", "Attempt":1 }, "Detail": { "ResponseCode": "A", "ResponseMessage": "AUTH CODE: 209", "TransactionType": "A", "TransactionCurrency": "EUR", "TransactionAmount": 1000, "CashbackAmount": 0, "GratuityAmount": 150, "CharityDonationAmount": 0, "AuthCode": "209", "TransactionMode": "P", "DataEntryMode": "S", "CustomerVerification": "S", "TransactionRRN": "107002508813", "AuthCode": "209", "MerchantNumber": "7888585866", "TerminalId": "90005504", "Cv2Response": "", "AvsResponse": "", "Cv2AvsMessage": "", "ReferenceData": "", "DccStatus": 3, "Scheme": "visa", "First6Pan": "444444", "Last4Pan": "1234" }, "DccAcceptance": { "DccGratuityAmount": 264, "DccAmount": 1759, "DccCurrencyCode": "JPY", "DccCurrencyExponent": 0, "DccExchangeRate": 175.9543 }, "ReceiptData": { "CustomerReceipt": "MID: 7888585866 TID:90005504## KEEP THIS COPY FOR YOUR RECOR....", "MerchantReceipt": "MID: 7888585866 TID:90005504## KEEP THIS COPY FOR YOUR RECOR...." } } }