Additional Payment and Checkout Features

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

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

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. Sign in to the ${SQUARE_DASHBOARD_NAME} 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 status 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.

The following device_options settings configure the Square Terminal checkout to:

• Prompt for a tip on the Square Terminal.
• Show the receipt screen.

The device_options object sets the following 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"
  }
}

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 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 the kiosk then 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.

The team member ID is associated with an individual TeamMember record and who is associated with creating the Terminal checkout.

For more information about setting up team members, see the Team API's Integration guide.

The statement description identifier can contain a customer ID or an order object ID.

For more information about statement descriptions, see Card Payment and Statement Description.