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 to a POS Application.

The following payment options are available only in the US:

• Application fees
• Delayed capture (including actions to be applied to delayed capture payments after the delay duration time has elapsed)
• Orders and itemizations
• (Beta) Statement description identifiers
• (Beta) Tip money

To use the payment options for a Terminal checkout request, you must update the Square Terminal software to the latest version, and use the latest release version of the Square API.

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, 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 to a POS Application.
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.

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.

The following command configures the Square Terminal checkout to:

• Prompt for a tip on the Square Terminal.
• 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
    }
  }
}

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.

{
  "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"
  }
}

Square deletes completed checkouts after 30 days. If you need to store the checkouts for future reference, retain the checkout's payment IDs.

If the buyer uses the POS application to enter a tip amount before the checkout is sent to the Square Terminal, the seller doesn't need to use the Square Terminal to collect a tip. You already know the tip amount before calling the Terminal API, for which you use the tip_money beta parameter and the amount_money parameter in the checkout request.

A common scenario for this tip collection flow involves the seller using a kiosk POS application that calculates the tip, and you don't want the buyer to enter the tip on the Square Terminal. The buyer-facing flow on the kiosk includes adding a tip, and then the kiosk sends the total amount (including tip) to the Square Terminal as a checkout request.

The tip_money parameter can only be set and included in the request if the checkout request has tip settings disabled. The default value for the allow_tipping field in the TipSettings object is false. For more information about how to process payments with tip money, see Take Cash Payments and Update Payment and Tip Amounts.

Square Terminal 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:

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"
  }
}

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

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

The response carries a checkout object with collect_signature requested.

{
  "checkout": {
    "id": "jnaokd5jsMbqO",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "reference_id": "232323",
    "note": "hamburger",
    “device_options”: {
      “device_id”: "R5WNWB5BKNG9R",
      “collect_signature”: true
      },
    "payment_type": "CARD_PRESENT",
    "device_id": "R5WNWB5BKNG9R",
    "status": "PENDING",
    "created_at": "2020-04-20T21:23:05.051Z",
    "updated_at": "2020-04-20T21:23:05.051Z",
    "app_id": "sq0ids-o38CJ3JfIrKJ_xn10mRhFg"
  }
}

The Terminal API also provides additional options to work with payments. These options are also available through the Payments API.

• 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.
• (Beta) Assigning a team member ID to the checkout. The ID is associated with an individual TeamMember record.
• Specifying whether to cancel or complete a delayed capture payment, when the time for delaying the payment capture has elapsed.
• (Beta) Adding a statement description identifier to the checkout request. The identifier can contain a customer ID or an order object ID. For more information about statement descriptions, see Card Payment and Statement Description.

Square Terminal 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

   cURL

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.

   {
     "checkout": {
       "id": "jnaokd5jsMbqO",
       "amount_money": {
         "amount": 500,
         "currency": "USD"
       },
       "reference_id": "232323",
       "note": "hamburger",
       “device_options”: {
         “device_id”: "R5WNWB5BKNG9R",
         “collect_signature”: true
         },
       "payment_type": "CARD_PRESENT",
       "device_id": "R5WNWB5BKNG9R",
       "status": "COMPLETED",
       "created_at": "2022-05-12T21:23:05.051Z",
       "updated_at": "2022-05-12T21:23:05.051Z",
       "app_id": "sq0ids-o38CJ3JfIrKJ_xn10mRhFg"
     }
   }

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've 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 Collect Application Fees.

Square Terminal 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

   cURL

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

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

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

You can also specify the action for Square to take on the payment when the length of time for the delayed capture has elapsed. Under payment_options, add the delayed_action attribute and set it to either CANCEL or COMPLETE.

To learn more about updating payments, see Update Payment and Tip Amounts.

Square Terminal 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 Overview. 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:

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 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 doesn't 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.

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.

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 Partial Payment Authorizations 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 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 Payment 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 CancelTerminalCheckout 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.

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.

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.

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.

• 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 Terminal.
• The 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 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.
• Using CancelTerminalCheckout 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.