Take One-Off Payments

Applies to: Terminal APITerminal API | Payments APIPayments API | Devices APIDevices API | Orders APIOrders API

Learn how to take an one-off payment with the Terminal API, Square Terminal, and a POS application.

This guide assumes that you obtained a device code, signed in to one or more Square Terminals (depending on the seller's number of Square Terminals in the fleet), and paired the Square Terminal with a POS application. If not, these steps are covered in the Terminal API QuickstartQuickstart.

For more information about how the POS client pairs with the Square Terminal, see POS Application Pairing with Square Terminal.POS Application Pairing with Square Terminal.

To take a payment with a paired Square TerminalSquare Terminal, perform the following steps:

1. Request a Square Terminal checkout for payment from the buyer.
2. Complete the checkout.
3. Verify a payment.
4. Search for Terminal checkout requests.
5. Cancel a checkout request, when applicable.

• To add payment and checkout features in a Terminal checkout requestpayment and checkout features in a Terminal checkout request, the Square Terminal software must be on the latest version and your application should use the latest Square API release version. To view the Square Terminal version and verify that your version supports a given checkout feature or device option:
  1. On the Square Terminal, swipe left, and then tap Settings.
  2. Tap Hardware, tap General, and then tap About Terminal.
  3. Under Terminal, view the OS Version.
• Applications must have the following OAuth permissions: PAYMENTS_WRITE to process payments and PAYMENTS_READ to retrieve payments.
• You cannot take cash payments with the Terminal API.
• Application fees require calling CreateTerminalCheckout with an OAuth token and the PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS permission, in addition to the existing required OAuth permissions. For more information, see TerminalTerminal.
• Using CancelTerminalCheckoutCancelTerminalCheckout to cancel an e-money payment after getting an error on the Square Terminal is currently not supported. To cancel an e-money payment, the buyer needs to manually cancel the payment on the Square Terminal.

The following procedure describes the checkout process.

Your POS application must specify the total amount to be paid by the buyer (including any sales tax or other fees) when requesting a checkout. Optionally, your POS application can require the Square Terminal to prompt the buyer to add a tip amount, show a receipt screen, or show a signature screen.

To take a payment from a buyer, the Square Terminal needs to have the total purchase amount and currency. For example, a Square Terminal can be told to accept $100 (USD). To process this request:

1. The POS application makes a request to Square using the Terminal API to send the payment request to a paired Square Terminal, identified by the device ID.
2. The payment checkout process starts, which involves enabling the POS client to send a request to checkout a buyer, accept the payment, and complete the checkout.

When the status of a Terminal checkout object is updated, webhook notifications are sent to the endpoint that is registered for a POS application. To get the notifications, be sure that your Square application is updated in the Developer Console. The webhook notifications are as follows:

• terminal.checkout.created
• terminal.checkout.updated

When a Terminal checkout object is created, canceled, or completed, a full copy of the object is sent to your application at your webhook URL. The object provides status and payment_ids fields.

When the checkout completes, a PaymentPayment object is created to record the details of the charge. The payment status can be COMPLETED, CANCELED, or FAILED. A completed payment is normally for the full amount of the purchase but must be verified against the amount expected by your POS application. A completed payment for the full purchase amount means that the checkout is complete and the POS payment window can be closed.

When a checkout is completed, it has one or more payment_ids listed on it. These are confirmations about how much money was actually collected, if any.

Get a completed checkout to find its payment_ids, as shown in the following example:

The following is returned:

{
    "checkout": {
        "id": "xv4gh2KBCmlqO",
        "amount_money": {
            "amount": 100,
            "currency": "USD"
        },
        ...snip...
        "status": "COMPLETED",
        "payment_ids": [
            "{PAYMENT_ID}"
        ],
    }
}

Search for existing Terminal checkout requests filtered by the:

• Device ID.
• Time and date range that the Terminal checkout was requested.
• Terminal checkout status.

Search results are sorted and paginated and allow for a custom page size. Search for existing requests if you need to verify completed Terminal checkouts and if you need to complete pending checkout requests.

The following example requests an additional page of completed Terminal checkout requests sent to the Square Terminal with ID R5WNWB5BKNG9R, created on or after noon UTC/GMT, and started on 03-20-2020. Results are limited to 10 Terminal checkouts per result page.

To learn more about how to work with cursors, see PaginationPagination.

A Terminal checkout request can be canceled from the POS application while the status of the checkout is PENDING or IN_PROGRESS. To cancel a Terminal checkout, POST a request to the CancelTerminalCheckoutCancelTerminalCheckout endpoint. Canceling a PENDING Terminal checkout causes the Terminal checkout to be CANCELED. IN_PROGRESS Terminal checkouts transition to CANCEL_REQUESTED and, if the buyer hasn't yet completed the transaction, transition to CANCELED.

If the transaction is already complete, the checkout request becomes COMPLETED. In this case, the seller cannot trigger a refund for the PaymentPayment after the transaction is completed.

In this example, the seller cancels a PENDING Terminal request from the POS application:

If the request is successful, the response provides the Terminal checkout object in its new state.

{
  "checkout": {
    "id": "{CHECKOUT_ID}",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "device_options": {
      "device_id": "432532423`",
      "tip_settings": {
        "allow_tipping": false
      },
      "skip_receipt_screen": true
    },
    "status": "CANCELED",
    "created_at": "2020-04-06T21:37:08.516Z",
    "updated_at": "2020-04-06T21:37:08.516Z",
    "app_id": "sq0ids-o38CJ3JfIrKJ_xn10mRhFg"
  }
}

Using CancelTerminalCheckoutCancelTerminalCheckout to cancel an e-money payment after getting an error on the Square Terminal is currently not supported. If the Square Terminal gets an error, the buyer needs to close the error message window and then tap the navigation button back to the checkout screen to cancel the checkout. The checkout request has either the IN_PROGRESS or PENDING status when this error occurs.

The Terminal API server sets a Terminal checkout to CANCELED if a checkout isn't completed prior to the created_at time.

A Terminal might be completing a payment at the threshold of the timeout. When this happens, the Terminal API server might set the CANCELED state on the checkout while the Terminal device is completing it. In this case, the checkout might become CANCELED prior to becoming COMPLETED. If you subscribe to Terminal API webhooks, any confusion can be avoided because you're receiving updates with each state change.