Learn how to take a payment with the Square Terminal API and Square Terminal.
Terminal API

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 topic 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 Connect a Square Terminal.

At a high level, you learn about:

  • Requesting a Square Terminal checkout for payment.

  • Monitoring the status of a checkout request.

  • Adding additional payment options to a checkout request.

  • Canceling a checkout request.

  • Verifying a payment.

  • Searching for 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, see 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 merchant can pre-authorize the initial payment and request additional transactions to cover the remaining balance.

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 calls the CreateDeviceCode endpoint to pair with a Square Terminal and get a device ID. For more information, see Connect a Square Terminal.

  2. Await notification of device paring success.

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

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

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

  6. The Square Terminal notifies Square of the payment.

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

Important

In a production environment, you must use a device ID generated by the Devices API. You cannot use a device ID from the Seller Dashboard.

If the collect_signature option is set to true in the CreateTerminalCheckout endpoint under device_options, the payment flow requests the buyer's signature for the payment.

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:

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: 2022-05-12' \
  -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.

  • 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
  • 26
{
  "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 later supports manual payment card entry by providing the payment_type field the TerminalCheckout object and the CheckoutOptionsPaymentType 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
  • 18
  • 19
  • 20
  • 21
curl https://connect.squareup.com/v2/terminals/checkouts \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -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",
      "device_options": {
        "skip_receipt_screen": true,
        "device_id": "R5WNWB5BKNG9R"
      }
    }
  }'

The response carries a checkout object with the payment_type requested.

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

Square Terminal version 5.13 and later supports the ability to require or skip collecting a signature for a payment, by providing the collect_signature field for the DeviceCheckoutOptions object. If collect_signature is set to true in the checkout request, the Square Terminal displays the signature collection screen during checkout. The buyer is then required to provide a signature before proceeding to the next screen.

If collect_signature is set to false, the checkout skips the signature capture screen. The default value for collect_signature is false.

Important

  • The Square API version must be 2022-04-20 or later to use the collect_signature field. If Square-Version in the request header is not set, then the request defaults to using the API version from the Developer Dashboard. For more information, see How Square API versioning works.

  • The collect_signature field is applicable only in the US and Canada. In other regions, Square Terminal determines if it needs to collect signatures from buyers.

The following command configures the Square Terminal checkout request to require signature collection:

Create Terminal Checkout
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
curl https://connect.squareup.com/v2/terminals/checkouts \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "crd68753445",
    "checkout": {
      "amount_money": {
        "amount": 100,
        "currency": "USD"
      },
      "reference_id": "232323",
      "note": "hamburger",
      "payment_type": "CARD_PRESENT",
      "device_options": {
        "device_id": "R5WNWB5BKNG9R",
        "collect_signature": true
      }
    }
  }'

The response carries a checkout object with collect_signature requested:

Additional options for payments in a checkout Permalink Get a link to this section

Terminal API also provides additional ways to work with payments: the ability to collect fees, delay the capture of payments, link orders with line items to a Terminal checkout, and take partial payments from cards with a limited balance.

Important

App fees, delayed capture, orders and itemizations, and partial authorization are currently in beta and supported only in the US. Review the Requirements and limitations section before using these features.

Take a fee from a payment Permalink Get a link to this section

Square Terminal version 5.13.0055 and later supports collecting an application fee from a payment. The app_fee_money property has a value amount limit.

The following steps provide an example of the fee collection flow:

  1. Create a CreateTerminalCheckout request and add app_fee_money with 100 (1.00 USD) and USD as the amount and currency, respectively.

Create Terminal Checkout
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
curl https://connect.squareup.com/v2/terminals/checkouts \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "28a0c3bc-7839-11ea-bc55-0242ac130003",
    "checkout": {
      "app_fee_money": {
        "amount": 100,
        "currency": "USD"
      },
      "reference_id": "id11572",
      "device_options": {
        "device_id": "dbb5d83a-7838-11ea-bc55-0242ac130003"
      },
      "note": "A brief note"
    }
  }'
  1. When the buyer completes the checkout flow on the Square Terminal, the Terminal checkout transitions to a status of COMPLETED. A payment_id is attached to the Terminal checkout.

  1. Call the GetPayment API using the payment_id to verify that the app fee money amount was properly attached to the payment and attributed to your application's ID.

  2. Log into the Square dashboard as the merchant associated with your application, and navigate to the “Balances” section to verify the expected amount has been added to your Square balance. After you’ve linked a bank account, the collected fees will be transferred nightly to your linked bank account.

For more information about how to collect fees from payments, see Take Payments and Collect Fees.

Take a delayed capture payment Permalink Get a link to this section

Square Terminal version 5.5.0037 and later supports delayed capture of payments made with the POS application.

To learn how delayed capture works with card payments, see Delayed Capture of a Card Payment.

The delayed capture flow with the Terminal API works as follows:

  1. Create a CreateTerminalCheckout request and set autocomplete to false to authorize the payment but not capture it. Set delay_duration to PT24H, which is 24 hours.

  • The autocomplete attribute is a boolean type that indicates whether Payment objects are automatically completed or left in an APPROVED state for later changes. Default value is true.

  • The delay_duration attribute is a modifiable string type that indicates the length of time in RFC 3339 format before Square automatically cancels the payment. This property applies only when autocomplete is false. Default value is PT36H, which is 36 hours from the time the checkout request was created.

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
curl https://connect.squareup.com/v2/terminals/checkouts \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "28a0c3bc-7839-11ea-bc55-0242ac130003",
    "checkout": {
      "amount_money": {
        "amount": 2610,
        "currency": "USD"
      },
      "reference_id": "id11572",
      "payment_options": {
        "autocomplete": false,
        "delay_duration": "PT24H"
      },
      "device_options": {
        "device_id": "dbb5d83a-7838-11ea-bc55-0242ac130003"
      },
      "note": "A brief note"
    }
  }'
  1. When the buyer completes the checkout flow on the Square Terminal, the Terminal checkout transitions to a COMPLETED status, and includes the resulting payment_id. The payment object will have a status of APPROVED.

  2. Call the UpdatePayment API using the payment_id to change the payment amount and tip amount after the payment is authorized.

  3. Call the CompletePayment API to capture the payment, or call the CancelPayment API to void the payment.

To learn more about updating payments, see Update Payments.

Take a partial authorized payment Permalink Get a link to this section

Square Terminal version 5.9 and later supports accepting partial payments with a Square Gift Card and cards with a limited balance. The following information uses a Square Gift Card as an example.

A buyer swipes or manually enters a Square Gift Card on the Square Terminal. In the Terminal checkout request under payment_options, set accept_partial_authorization to true and autocomplete to false, which allows merchants to authorize a payment for less than the total amount when the Square Gift Card doesn’t have enough money in the balance. The merchant can then initiate a follow-up checkout request to authorize the remaining amount.

The following checkout request incorporates partial payment authorization and an order ($20 Order). The checkout request is for $20 USD and charging a Square Gift Card with a balance of $5.00.

Create Terminal Checkout
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
curl https://connect.squareup.com/v2/terminals/checkouts \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "checkout": {
      "amount_money": {
        "amount": 2000,
        "currency": "USD"
      },
      "payment_options": {
        "autocomplete": false,
        "accept_partial_authorization": true
      },
      "device_options": {
        "device_id": "{DEVICE_ID}"
      }
    }
  }'

After the buyer uses their gift card, the terminal checkout is put to a COMPLETED state and the payment id is put in an APPROVED state.

To pay for the remainder of the order, $15, create another checkout with autocomplete set to false, accept_partial_authorization to true, and the same order_id.

Create Terminal Checkout
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
curl https://connect.squareup.com/v2/terminals/checkouts \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "checkout": {
      "amount_money": {
        "amount": 1500,
        "currency": "USD"
      },
      "payment_options": {
        "autocomplete": false,
        "accept_partial_authorization": true
      },
      "device_options": {
        "device_id": "{DEVICE_ID}"
      }
    }
  }'

After the buyer completes the terminal checkout with a credit card, the seller must complete the order by using the PayOrder endpoint.

For more information on partial payments and to pay for orders, see Take Partial Payments and Pay for Orders, respectively.

Take a payment for an itemized order Permalink Get a link to this section

Square Terminal version 5.7.0049 and later supports linking an order and an order’s line items to a Terminal checkout.

Before adding an order to a Terminal checkout request, you must create a new order object with the Orders API. See What It Does for information on how to create an order.

After creating a new order, you can link the order to a Terminal checkout by including the order’s order_id to the Terminal checkout POST request body.

The show_itemized_cart attribute determines whether a screen displaying the order’s line items will show on the Terminal. Default value is true.

The following checkout request shows where the order_id is defined:

Create Terminal Checkout
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
curl https://connect.squareup.com/v2/terminals/checkouts \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "checkout": {
      "amount_money": {
        "amount": 2000,
        "currency": "USD"
      },
      "device_options": {
        "device_id": "{DEVICE_ID}"
      },
      "order_id": "{ORDER_ID}"
    }
  }'
  • The order is created after the checkout request passes the following validation rules:

  • The order must belong to the location that the Square Terminal is currently logged into.

  • The order must be in an OPEN state.

  • The order and checkout currency must match.

  • The order and checkout amount must be equal to each other if payment_options.autocomplete is set to true. This will move the order to a COMPLETED state.

After the checkout request is sent to the Square Terminal, the buyer can complete or cancel the checkout. If the buyer successfully completes the payment for the Terminal checkout, the Terminal checkout moves to a COMPLETED state.

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, transitions 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: 2022-05-12' \
  -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 request timeout 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 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 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:

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

A completed payment for the full purchase amount means that the checkout is complete and the POS payment window can be closed. Receipt options are available after the buyer has provided their card.

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: 2022-05-12' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The following is returned:

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: 2022-05-12' \
  -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.

  • 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 OAuth Permissions Reference.

  • Terminal API doesn't support updates made to orders after a Terminal checkout has been made with the order_id set to IN_PROGRESS, which means that the Square Terminal is currently processing the checkout. If you try to update the order while the checkout is in progress, the checkout may respond with an erroneous result. To update the order, cancel the checkout with CancelTerminalCheckout and then either create a new Terminal checkout request with the same order, or create a new order along with a new Terminal checkout request.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.