Cancel an in-progress transaction

Sometimes your shoppers change their mind in mid-purchase, or store staff realize they have made a mistake while the shopper is using the terminal.

You can then send a request to abort the in-progress transaction. When this request is received before the transaction is approved on the terminal, the payment is cancelled.

Here we explain how you can cancel in-progress transactions from:

• Your POS app by sending a Terminal API abort request.
• The terminal.

Requirements

Before you begin, take into account the following requirements.

Cancel from your POS app

While a payment request is in progress, you can cancel it by making an abort request from your POS app.

If you cancel before the shopper presents the card, the payment prompt disappears from the terminal display.
You can also cancel after the shopper presents the card, as long as the payment is not completed yet. For example, after presenting the card but before entering the PIN. The terminal then shows Cancelled.

1. Make a Terminal API abort request, specifying:

   • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Abort.

     Parameter	Required	Description
     ProtocolVersion		3.0
     MessageClass		Service
     MessageCategory		Abort
     MessageType		Request
     ServiceID		Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
     SaleID		Your unique ID for the POS system component to send this request from.
     POIID		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

   • The AbortRequest object with:

     Parameter	Required	Description
     AbortReason		MerchantAbort
     MessageReference		An object with: MessageCategory: Payment SaleID: your unique ID of the POS system component that made the payment request. ServiceID: The ServiceID of the transaction request being cancelled.

   The example shows how to cancel an in-progress payment with a ServiceID of 21796.

2. Check the responses:

   • A successful abort request returns a response with a 200 OK HTTP status code and no body.

   • The payment request returns a response containing:

     • Result: Failure
     • ErrorCondition: Aborted

3. To double-check the payment was indeed cancelled, make a transaction status request, including:

   • The TransactionStatusRequest.MessageReference object with:

     Parameter	Required	Description
     SaleID		The SaleID of the POS system component that made the payment you tried to cancel.
     ServiceID		The ServiceID of the payment you tried to cancel.
     MessageCategory		Set to Payment.

   The example shows how to check the transaction status of a payment with ServiceID 21796, which you tried to cancel.

4. Check the response: If the payment was cancelled, the TransactionStatusResponse has a RepeatedResponseMessageBody with an ErrorCondition of Aborted.

Cancel when you do not know the ServiceID

In case of a communication or technical issue, the payment or card acquisition request can remain in-progress. When this happens, the terminal cannot be used until the request times out on its own, usually after 150 seconds. Because you haven't received the response yet, you do not have the ServiceID required to cancel the request.

You can get the ServiceID of the original request by sending a transaction status request with an empty TransactionStatusRequest object. You can then follow up with request to cancel the payment or card acquisition request.

To get the ServiceID of the original request:

1. Make a Terminal API transaction status request, specifying:

   • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to TransactionStatus.

     Parameter	Required	Description
     ProtocolVersion		3.0
     MessageClass		Service
     MessageCategory		TransactionStatus
     MessageType		Request
     SaleID		Your unique ID for the POS system component to send this request from.
     ServiceID		Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
     POIID		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

   • TransactionStatusRequest: an empty object.

2. From the TransactionStatusResponse, save the following:

   • ServiceID: The unique ID of the original payment or card acquisition request.
   • SaleID: Your unique ID for the system where you send this request from.

   • MessageCategory: Can be Payment or CardAcquisition.

3. Follow up with a request to cancel the in-progress payment or card acquisition using the ServiceID from the transaction status response.

Cancel from the terminal

To cancel an in-progress payment on a terminal:

• On the terminal keypad, select the Cancel key
  In case of a terminal without a keypad, on the display select the Cancel icon

If this is successful:

• The terminal shows a Cancelled message on the display.

• The payment request returns a response containing:

  • Result: Failure

  • ErrorCondition: Cancel

Canceling a signature on the display

In a Terminal API integration with a terminal that is configured to let shoppers draw their signature on the display, the transaction is already authorized when the signature prompt appears. Therefore, the terminal always approves the signature even when the shopper selects Cancel on the signature screen. See Signature for more information.

Handling failed cancel requests

If your cancel request failed (and the payment was approved), you will need to refund the payment. For more information on refunding a payment, see Refund a completed payment.

See also