Method: HTTP POST
Format: JSON
Direction: POS (integrator) -> Gateway
The Cancel Payment request is primarily used by the POS in situations where the outcome of a Payment request is unknown. This may happen when the connection drops between the POS and gateway after a Payment request has been sent. The Cancel Payment request supports cancelling based on original the ClientTransactionReference or TransactionRRN of a payment. If the POS has the TransactionRRN, it has already received the Payment response and should use the Complete Payment request to cancel the transaction instead.
Request
The Cancel Payment request is constructed with the following sections:
CancelPaymentRequest
{
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 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 Cancel Payment request, it can reissue another Cancel Payment 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. |
|
OriginalTransactionAmount |
1 |
10 |
"^([0-9]*)$" |
This field must contain the original TransactionAmount submitted in the Payment request to be cancelled. |
|
OriginalTransactionDateTime |
25 |
25 |
"YYYY-MM-DDTHH:mm:ss+hh:mm" |
This field must contain the original TransactionDateTime submitted in the Payment request to be cancelled. |
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 Cancel Payment response is constructed with the following sections:
CancelPaymentResponse
{
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 Cancel 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 Cancel Payment request. |
|
Attempt |
1 |
5 |
"^([0-9]*)$" |
Attempt value echoed back from the Cancel Payment request. |
Detail Section
|
Field |
Min |
Max |
Format |
Description |
|---|---|---|---|---|
|
ResponseCode |
1 |
1 |
"^[C]$" |
This field contains the following value: C: Payment has been cancelled. |
|
ResponseMessage |
1 |
32 |
"^([a-zA-Z0-9-_: ])*$" |
Verbose message such as 'CANCELLED'. |
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. |
Cancel Payment Request Example
{
"CancelPaymentRequest":
{
"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":
{
"OriginalClientReference":"b92838d4-eaa3-4b75-bf31-343faa1ddb84",
"OriginalTransactionAmount":1000,
"OriginalTransactionDateTime":"2023-02-09T08:47:31+00:00"
},
"TargetTerminal":
{
"TerminalName":"90005504"
}
}
}Cancel Payment Response Example
{
"CancelPaymentResponse":
{
"Header":
{
"ProtocolVersion": 1.0,
"MerchantId": "PRCLIENT-CLOUDRETAIL-IRL",
"PosID": "90005504",
"ClientTransactionReference": "559b629a-c4b9-41dc-a890-961e2ae0d3a1",
"Attempt": 1
},
"Detail":
{
"ResponseCode": "C",
"ResponseMessage": "TRANSACTION CANCELLED"
},
"ReceiptData":
{
"CustomerReceipt": "MID: 7888585866 TID:90005504## KEEP THIS COPY FOR YOUR RECORDS...",
"MerchantReceipt": "MID: 7888585866 TID:90005504## KEEP THIS COPY FOR YOUR RECORDS..."
}
}
}