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

Take Payments with the Terminal API

To take a payment with a paired Square Terminal, follow this guide to complete the following steps:

  1. Request a Square Terminal checkout for payment.

  2. Monitor the status of a checkout request.

  3. Configure the behavior of the checkout with payment options.

  4. Cancel a checkout request.

  5. Verify a payment.

  6. Search for a checkout request.

To learn how to configure a Square Terminal and pair it with your application, see Connect a Square Terminal.

Did you know?

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

When using a Sandbox device ID, you can test the Terminal checkout process and verify the checkout status change. In production, you should use 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.

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.

Note

A Square Terminal accepts Apple Pay, Google Pay, Square gift cards, and prepaid debit cards. However, for US-based sellers, if the balance of a gift card or prepaid card is not sufficient to pay for a transaction, the seller can delay the capture of the initial payment and request additional transactions to cover the remaining balance.

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. The payment checkout process does the following steps:

  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 pairing 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 the device_id returned from the Devices API. In the checkout request body for device_id, you can also enter the Square Terminal's serial number, which you can find on the back of the Square Terminal. You cannot use a device code generated from the Seller Dashboard; however, you can view the device ID in the Seller Dashboard after the Devices API has generated it.

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.

Did you know?

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.

The following command configures the Square Terminal checkout to:

  • Prompt for a tip.

  • 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-11-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 with a PENDING status. Note that the PENDING status changes to IN_PROGRESS when the Square Terminal acknowledges the request and shows the checkout display screen to the buyer while 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. The buyer can also cancel the checkout through the POS application while the request is in the IN_PROGRESS status.

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

Square Terminal version 4.27.0037 and later supports manual payment card entry by providing the payment_type field in the TerminalCheckout object and in the CheckoutOptionsPaymentType enumeration. When a payment_type with the value of MANUAL_CARD_ENTRY is specified in the checkout request, the Square 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-11-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",
      "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.

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 the Square-Version in the request header is not set, 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 United States and Canada. In other regions, Square Terminal determines whether 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-11-16' \
  -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.

The Terminal API also provides additional ways to work with payments:

  • The ability to collect fees.

  • The delay of the capture of payments.

  • Linking orders with line items to a Terminal checkout.

  • Taking partial payments from cards with a limited balance.

Important

Application fees, delayed capture, and orders and itemizations are available only in the United States.

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-11-16' \
      -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"
        }
      }'
  2. 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.

  3. Call the GetPayment endpoint using the payment_id to verify that the application fee amount was properly attached to the payment and attributed to the application ID.

  4. Log in to the Seller Dashboard as the seller associated with your application and navigate to the Balances section to verify that the expected amount has been added to your Square balance. After you have linked a bank account, the collected fees are transferred nightly to your linked bank account.

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

Square Terminal version 5.5.0037 and later supports the 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. The 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. The 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-11-16' \
      -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 now has a status of APPROVED.

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

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

To learn more about updating payments, see Update Payments.

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. For information about how to create an order, see Orders API: What It Does.

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 is shown on the Terminal. The 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-11-16' \
  -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 to which the Square Terminal is currently logged in.

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

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 sellers to authorize a payment for less than the total amount when the Square gift card does not have enough money in the balance. The seller can then initiate a follow-up checkout request to authorize the remaining amount.

The following checkout request incorporates a 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-11-16' \
  -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 set to a COMPLETED state and the payment_id is set to the APPROVED state.

To pay for the remainder of the order, which is $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-11-16' \
  -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 about partial payments and how to pay for orders, see Take Partial Payments and Pay for Orders, respectively.

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, 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 Payment after the transaction is completed.

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

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.

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

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.

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

The following is returned:

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-11-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
  }'

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

  • The Terminal API does not 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 might respond with an erroneous result. To update the order, cancel the checkout with CancelTerminalCheckout and then 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.