Method: HTTP POST
Format: JSON
Direction: POS (integrator) -> Gateway
After a payment has been authorised via the Payment request, the POS must issue a Complete Payment request to the gateway indicating whether it is accepting or rejecting the payment. The gateway will not settle an authorised transaction to the merchant's acquirer until the POS has issued a Complete Payment request. If the POS issues a Complete Payment request indicating rejection of the transaction, the gateway will process a reversal of the transaction to the acquirer.
The POS must send through the TransactionRRN (a unique transaction reference as returned in the Payment response) in any Complete Payment request whether the transaction is accepted or rejected.
Request
The Complete Payment request is constructed with the following sections:
CompletePaymentRequest { Header{…} Detail{…} TargetTerminal{…} }
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 will be 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 Complete Payment request, it can reissue another Complete Payment request but with a newly created ClientTransactionReference. |
Detail Section
Field |
Min |
Max |
Format |
Description |
---|---|---|---|---|
TransactionRRN |
1 |
32 |
"^([0-9]*)$" |
This is the unique transaction ID returned in the Payment response. |
ConfirmType |
1 |
1 |
"^[A]|[C]|[D]$" |
This field specifies if the POS wants to accept, reject, or decline the payment. Valid values are the following: A: Accept the payment (settle the transaction) C: Cancel (reverse) the payment D: Decline the payment Note: Decline payment is only appropriate in referral situations where the voice authorisation centre has verbally declined the payment. Referrals are currently not supported. |
VoiceAuthCode |
0 |
8 |
"^([a-zA-Z0-9])*$" |
If the payment was referred and a voice authorisation verbally authorises the payment, this field must contain the verbal authorisation code. Note: Referrals are currently not supported. |
OriginalTransactionAmount |
1 |
10 |
"^([0-9]*)$" |
This field must contain the original TransactionAmount submitted in the Payment request. |
OriginalTransactionDateTime |
25 |
25 |
"YYYY-MM-DDTHH:mm:ss+hh:mm" |
This field must contain the original TransactionDateTime submitted in the Payment request. |
TargetTerminal Section
Field |
Min |
Max |
Format |
Description |
---|---|---|---|---|
TerminalName |
8 |
8 |
"^([0-9]*)$" |
Terminal identifier of the card terminal on which the payment was originally performed. |
Response
The Complete Payment response is constructed with the following sections:
CompletePaymentResponse { Header{…} Detail{…} 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 Complete Payment 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 Complete Payment request. |
Detail Section
Field |
Min |
Max |
Format |
Description |
---|---|---|---|---|
ResponseCode |
1 |
1 |
"^[A]|[C] $" |
This field indicates the outcome of the Complete Payment request. Valid values are the following: A: Payment has been accepted (and will settle). C: Payment has been cancelled. |
ResponseMessage |
1 |
32 |
"^([a-zA-Z0-9-_: ])*$" |
Verbose message such as 'AUTH CODE: xyz' for an authorised transaction or 'CANCELLED' for a cancelled transaction. |
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. |
Complete Payment Request Example
{ "CompletePaymentRequest": { "Header": { "ProtocolVersion":1.0, "MerchantId":"PRCLIENT-CLOUDRETAIL-IRL", "PosID":"90005504", "ClientDateTime":"2023-02-09T08:48:11+00:00", "ClientTransactionReference":"559b629a-c4b9-41dc-a890-961e2ae0d3a1", "Attempt":1 }, "Detail": { "TransactionRRN":"107002427378", "ConfirmType":"A", "VoiceAuthCode":"", "OriginalTransactionAmount":1000, "OriginalTransactionDateTime":"2023-02-09T08:47:31+00:00" }, "TargetTerminal": { "TerminalName":"90005504" } } }
Complete Payment Response Example
{ "CompletePaymentResponse": { "Header": { "ProtocolVersion": 1.0, "MerchantId": "PRCLIENT-CLOUDRETAIL-IRL", "PosID": "90005504", "ClientTransactionReference": "559b629a-c4b9-41dc-a890-961e2ae0d3a1", "Attempt": 1 }, "Detail": { "ResponseCode": "A", "ResponseMessage": "AUTH CODE: 185" }, "ReceiptData": { "CustomerReceipt": "MID: 7888585866 TID:90005504## KEEP THIS COPY FOR YOUR RECORDS...", "MerchantReceipt": "MID: 7888585866 TID:90005504## KEEP THIS COPY FOR YOUR RECORDS..." } } }