Terminal

Take Payments with the Terminal API

Use the Square Terminal API and the Devices API to integrate a Square Terminal with a Point of Sale (POS) application.

Overview Permalink Get a link to this section

This guide walks you through the development steps necessary to take a payment with Square Terminal. To learn how to configure a Square Terminal and pair it with your application, see Integrate with Square Terminal.

At a high level, you learn about:

  • Requesting a Square Terminal checkout for payment.

  • Monitoring the status of a checkout request.

Did you know?

You can test your Terminal API integration in the Square Sandbox. Use these sandbox test values to test your integration against successful and failed Terminal checkout requests.

When using a sandbox device ID, your checkout request gets a response almost immediately because the checkout process is not awaiting a response from a human buyer at a Square Terminal. In production, you should use the Terminal API webhooks to get a checkout response notification because there can be a significant delay between requesting a checkout and the completion of the checkout.

Request a Square Terminal checkout Permalink Get a link to this section

The 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, the POS application can require the Square Terminal to add a tip amount or show a receipt screen.

Note

A Square Terminal accepts Apple Pay, Google Pay, Square Gift Cards, and prepaid debit cards. However, if the balance of a Gift Card or prepaid card is not sufficient to pay for a transaction, the card is declined.

Payment flow Permalink Get a link to this section

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, 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. This process flows is as follows:

  1. The POS client sends the Terminal API a request to check out a buyer and accept a payment.

  2. Square sends the checkout details to the Square Terminal, which shows the payment details to the buyer.

  3. The buyer dips, taps, or swipes a payment card in the Square Terminal.

  4. The Square Terminal notifies Square of the payment.

  5. The Terminal API notifies the POS backend that the Terminal checkout was COMPLETED.

Take a payment with a tip Permalink Get a link to this section

The following command configures the Square Terminal checkout to:

  • Print a receipt.

  • Show the receipt screen.

The device_options object sets these behaviors:

{
  "device_options": {
    "skip_receipt_screen": false,
    "tip_settings": {
      "allow_tipping": true,
      "separate_tip_screen": true,
      "custom_tip_field": false
    }
  }
}
Create Terminal Checkout
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
curl https://connect.squareup.com/v2/terminals/checkouts \
  -X POST \
  -H 'Square-Version: 2020-12-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "blart34343432",
    "checkout": {
      "amount_money": {
        "amount": 100,
        "currency": "USD"
      },
      "reference_id": "232323",
      "note": "hamburger",
      "device_options": {
        "skip_receipt_screen": false,
        "tip_settings": {
          "allow_tipping": true,
          "separate_tip_screen": true,
          "custom_tip_field": false
        },
        "device_id": "R5WNWB5BKNG9R"
      }
    }
  }'

The response is returned when the paired Square Terminal acknowledges the checkout request. Note that the PENDING status changes to IN_PROGRESS when the Square Terminal is showing the checkout to the buyer and awaiting input. When the checkout is complete and Square has accepted the payment card, the status is COMPLETED.

While the status of the checkout is PENDING, the POS client or the buyer can cancel the checkout. When the status is IN_PROGRESS, the process continues until COMPLETED. At that time, the POS client can query for the final state of the checkout.

{
  "checkout": {
    "id": "Dobuud5jsMbqO",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "reference_id": "232323",
    "note": "hamburger",
    "device_options": {
      "device_id": "R5WNWB5BKNG9R",
      "tip_settings": {
        "separate_tip_screen": true,
        "custom_tip_field": false,
        "allow_tipping": true
      },
      "skip_receipt_screen": false
    },
    "device_id": "R5WNWB5BKNG9R",
    "status": "PENDING",
    "created_at": "2020-03-20T21:23:05.051Z",
    "updated_at": "2020-03-20T21:23:05.051Z",
    "app_id": "sq0ids-o38CJ3JfIrKJ_xn10mRhFg",
    "deadline_duration": "PT10M"
  }
}

Cancel a Terminal checkout Permalink Get a link to this section

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 cancel 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 has not yet completed the transaction, will transition to CANCELED.

If the transaction is already complete, the checkout request becomes COMPLETED. In that case, the Payment is to be refunded if the buyer wants to void the transaction.

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

Cancel Terminal Checkout
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareup.com/v2/terminals/checkouts/CHECKOUT_ID/cancel \
  -X POST \
  -H 'Square-Version: 2020-12-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

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",
    "deadline_duration": "PT5M"
  }
}

Verify a payment Permalink Get a link to this section

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 application is updated in the Developer Dashboard with the following webhook notifications:

  • 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 Payment 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.

Completed payment for the full purchase amount means that the checkout is complete and the POS payment window can be closed. A receipt for the amount charged on the payment card is printed by the Square Terminal.

Completed payment for a partial purchase amount means that the buyer used a Square Gift Card or a prepaid debit card when the full balance of the card was insufficient to complete a purchase. The payment is COMPLETED but the buyer is charged only the balance of the card. The POS payment window should remain open to initiate a checkout for the remaining balance.

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 at all.

Important

A COMPLETED checkout might not have collected the exact total you requested. For example, when a tip is added to the payment. You should always check the Payment object to determine the actual amount collected.

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

Get Terminal Checkout
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareup.com/v2/terminals/checkouts/CHECKOUT_ID \
  -H 'Square-Version: 2020-12-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

which returns:

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

Search for Terminal checkout requests Permalink Get a link to this section

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.

This 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 Pagination.

Search Terminal Checkouts
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
curl https://connect.squareup.com/v2/terminals/checkouts/search \
  -X POST \
  -H 'Square-Version: 2020-12-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "device_id": "R5WNWB5BKNG9R",
        "created_at": {
          "start_at": "2020-03-20T12:00:00.000Z",
          "end_at": "2020-03-20T24:00:00.000Z"
        },
        "status": "COMPLETED"
      },
      "sort": {
        "sort_order": "ASC"
      }
    },
    "cursor": "YTt3Nej0VB04dG4jS06HqO4Hm4Q9cEaCrCL84f5KzLg_p",
    "limit": 10
  }'

Requirements and limitations Permalink Get a link to this section

  • 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.