Dismiss Terminal Checkouts and Refunds

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

If a buyer abandons a checkout or a refund, you can clear the 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.

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 examples show the dismiss request and response of a checkout.

{
  "checkout": {
    "id": "LmZEKbo3SBfqO",
    "amount_money": {
      "amount": 2610,
      "currency": "USD"
    },
    "device_options": {
      "device_id": "dbb5d83a-7838-11ea-bc55-0242ac130003",
      "collect_signature": true,
      "tip_settings": {
        "separate_tip_screen": true,
        "custom_tip_field": false,
        "allow_tipping": true
      },
      "skip_receipt_screen": false,
      "loyalty_settings": {
        "show_loyalty_screen": false,
        "show_non_qualifying_loyalty_screen": false,
        "loyalty_screen_max_display_duration": "PT60S",
        "show_card_linked_reward_redemption_screen": false
      }
    },
    "status": "COMPLETED",
    "payment_ids": [
      "D7vLJqMkvSoAlX4yyFzUitOy4EPZY"
    ],
    "created_at": "2023-11-29T14:59:50.682Z",
    "updated_at": "2023-11-29T15:00:18.936Z",
    "app_id": "APP_ID",
    "deadline_duration": "PT5M",
    "location_id": "LOCATION_ID",
    "payment_type": "CARD_PRESENT",
    "payment_options": {
      "autocomplete": true
    }
  }
}

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 examples show the dismiss request and response of a refund.

{
  "refund": {
    "id": "009DP5HD-5O5OvgkcNUhl7JBuINflcjKqUzXZY",
    "refund_id": "5O5OvgkcNUhl7JBuINflcjKqUzXZY_43Q4iGp7sNeATiWrUruA1EYeMRUXaddXXlDDJ1EQLvb",
    "payment_id": "5O5OvgkcNUhl7JBuINflcjKqUzXZY",
    "amount_money": {
      "amount": 111,
      "currency": "CAD"
    },
    "reason": "Returning item",
    "device_id": "f72dfb8e-4d65-4e56-aade-ec3fb8d33291",
    "deadline_duration": "PT5M",
    "status": "COMPLETED",
    "created_at": "2020-09-29T15:21:46.771Z",
    "updated_at": "2020-09-29T15:21:48.675Z",
    "app_id": "sandbox-sq0idb-c2OuYt13YaCAeJq_2cd8OQ",
    "card": {
      "card_brand": "INTERAC",
      "last_4": "1111",
      "exp_month": 1,
      "exp_year": 2022,
      "fingerprint": "sq-1-B1fP9MNNmZgVVaPKRND6oDKYbz25S2cTvg9Mzwg3RMTK1zT1PiGRT-AE3nTA8vSmmw",
      "card_type": "CREDIT",
      "bin": "411111"
    },
    "order_id": "kcuKDKreRaI4gF4TjmEgZjHk8Z7YY",
    "location_id": "76C9W6K8CNNQ5"
  }
}

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.

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.

If the payment isn't captured on the dip/tap/swipe screen or on the tip screen, or if the seller doesn't want to complete the checkout in certain situations, the Square Terminal cancels both the payment and the 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.

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.

• Take Payments with the Terminal API
• Refunds API Overview
• Refund Interac Payments
• Link and Dismiss Terminal Actions