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 to take a payment with a paired 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. To learn more about subscribing to webhooks, read How to Subscribe to Events.

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

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 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: 2021-05-13' \
  -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"
  }
}

Take a payment with a manually entered card Permalink Get a link to this section

Square Terminal version 4.27.0037 and newer supports manual payment card entry by providing the payment_type field the TerminalCheckout object and the TerminalCheckoutPaymentType enumeration. When a payment_type with the value of MANUAL_CARD_ENTRY is specified in the checkout request, the Terminal displays the Manual Credit Card Entry form and a virtual keyboard for the input of card information.

The following command configures the Square Terminal checkout to:

  • Accept manual payment card input.

Create Terminal Checkout
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
curl https://connect.squareup.com/v2/terminals/checkouts \
  -X POST \
  -H 'Square-Version: 2021-05-13' \
  -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",
      "payment_type": "MANUAL_CARD_ENTRY"
    }
  }'

The response carries a checkout object with the payment_type requested.

{
  "checkout": {
    "id": "Dobuud5jsMbqO",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "reference_id": "232323",
    "note": "hamburger",
    "payment_type": "MANUAL_CARD_ENTRY",
    "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: 2021-05-13' \
  -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"
  }
}

Checkout request time-out cancellation Permalink Get a link to this section

The Terminal API server sets a Terminal checkout to CANCELED if a checkout is not completed prior to the created_at time plus the deadline_duration.

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

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.

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: 2021-05-13' \
  -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: 2021-05-13' \
  -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.