Dismiss Terminal Checkouts and Refunds

Applies to: Terminal API

Learn how to dismiss Terminal checkouts and Interac refunds on a Square Terminal when a buyer needs to abandon a checkout or a refund operation.

Link to section

Overview

If a buyer abandons a checkout or refund, you can clear the Square Terminal screen and return to the idle screen without waiting for a checkout or refund to time out. The DismissTerminalCheckout and DismissTerminalRefund endpoints provide a direct method to transition the Square Terminal screen back to the idle screen for checkout and refund operations, respectively.

Link to section

Dismiss a checkout

A DismissTerminalCheckout request requires the checkout_id of the given Terminal API checkout object. The endpoint returns a 200 response with the status of the Terminal checkout object when the dismissal is requested and transitions the Square Terminal to the idle screen. When you dismiss a checkout, the checkout transitions to a COMPLETED or CANCELED state in one of the following payment scenarios:

  • If the payment is authorized but not yet captured, and the checkout isn't completed, the Square Terminal attempts to capture the payment, complete the checkout, and transition to the idle screen.
  • If the payment is authorized and captured, but the checkout isn't completed, the Square Terminal completes the checkout and transitions to the idle screen.
  • If the payment isn't authorized or captured, and the checkout isn't completed, the Square Terminal attempts to cancel the payment and checkout and then returns to the idle screen.
  • If the payment is authorized and captured, and the checkout is completed, the Square Terminal ignores the dismiss request.

The following endpoint call example shows the dismiss request and response of a checkout.

The following POST v2/terminal/checkouts/{checkout_id}/dismiss request uses LmZEKbo3SBfqO for checkout_id:

Dismiss terminal checkout

Link to section

Dismiss a refund

A DismissTerminalRefund request requires the refund_id of the given Terminal API refund object. The endpoint returns a 200 response with the current status of the Terminal refund object and transitions the Square Terminal to the idle screen. When you dismiss a refund, the refund transitions to a COMPLETED or CANCELED state in one of the following refund scenarios:

  • If the refund isn't completed, the Square Terminal cancels the refund and returns to the idle screen.
  • If the refund is completed, the Square Terminal ignores the dismiss request.

The following endpoint call example shows the dismiss request and response of a refund.

The following POST v2/terminal/refunds/{terminal_refund_id}/dismiss request uses 009DP5HD-5O5OvgkcNUhl7JBuINflcjKqUzXZY for terminal_refund_id.

Dismiss terminal refund

Link to section

When to dismiss versus cancel a checkout or refund

Dismissing a Terminal checkout and refund functions similarly to canceling them. Note the following differences and Square's recommended use cases for each endpoint.

The difference between using the DismissTerminalCheckout endpoint or the CancelTerminalCheckout endpoint involves whether the payment has been captured.

Link to section

Dismissing a checkout

If the payment isn't captured but is authorized, the Square Terminal attempts to capture and complete the payment, such as when a buyer is interacting with the tip screen. In all scenarios, dismissing a checkout guarantees that the Square Terminal returns to the idle screen. DismissTerminalCheckout allows you to clear the Square Terminal screen without needing to know the current state of the checkout.

Link to section

Canceling a checkout

If the payment isn't captured on the dip/tap/swipe screen or on the tip screen, or the seller doesn't want to complete the checkout in certain situations, the Square Terminal cancels both the payment and checkout. This event occurs even if the payment is authorized and causes the Square Terminal to return to the idle screen. In all other cases, canceling a checkout is a no-op (no operation) and the Square Terminal doesn't dismiss the screen as a result, which means you need to use DismissTerminalCheckout instead. If you send a CancelTerminalCheckout request to try to cancel the checkout, the Square Terminal terminates the process but the POS application might still be stuck waiting for the checkout request to time out.

Link to section

Dismissing or canceling a refund

Both DismissTerminalRefund and CancelTerminalRefund endpoints function the same, except that dismissing a refund guarantees that the Square Terminal returns to the idle screen. DismissTerminalRefund and CancelTerminalRefund apply only to Interac card payments.

Link to section

See also