Payment Inquiry Request

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...."
                        }
            }
}