Get a Buyer's Confirmation

Applies to: Terminal API

Learn how to display a confirmation screen and ask for a buyer's input on the Square Terminal.

As part of creating custom workflows with the Terminal API, you can create a screen workflow that collects a buyer's decision input on a confirmation screen. You send a Terminal action request of the CONFIRMATION type and the Square Terminal displays the confirmation screen where the buyer is asked to agree or disagree with the information presented. The buyer's decision can be found in the Terminal action response when the Terminal action is in a COMPLETED state.

In the request body, you can edit the title and body text that displays on the confirmation screen. The title text has a maximum length of two lines and a 250-character limit. The body text is scrollable with a 10,000-character limit. You can edit the text that displays for the agree and disagree buttons, both of which have a 250-character limit.

The following animation shows how the Square Terminal displays the confirmation screen for the buyer:

1. Send a Terminal action POST request using the CreateTerminalAction endpoint and specify the CONFIRMATION action type. In the confirmation_options body, provide screen text for title, body, agree_button_text, and disagree_button_text. You can also omit the disagree_button_text field type if you're creating the confirmation screen with only one screen button prompt.

   Create terminal action

   cURL

   The Terminal action response includes an action_id and a PENDING status because the Square Terminal hasn't yet received the request.

   {
      "action": {
        "id": "termapia:abcdefg1234567",
        "device_id": "R5WNWB5BKNG9R",
        "deadline_duration": "PT5M",
        "status": "PENDING",
        "created_at": "2022-03-09T09:01:19.622Z",
        "updated_at": "2022-03-09T09:03:06.830Z",
        "type": "CONFIRMATION",
        "app_id": "sq0ids-abcdefg123456789",
        "confirmation_options": {
          "title": "Marketing communications",
          "body": "I agree to receive promotional emails about future events and activities.",
          "agree_button_text": "Agree",
          "disagree_button_text": "Decline"
          "decision": {
            "has_agreed": true
      }
   }

   The Square Terminal displays the confirmation screen for the buyer.

After the buyer selects a decision, the Terminal action is put in a COMPLETED state and the Square Terminal displays the idle screen.

2. Send a GET request to see the Terminal action that includes the decision.

   Get terminal action

   cURL

   The response returns the buyer's confirmation in the confirmation_options body. The following response example shows that the buyer decided to agree with the information presented on the screen, as indicated by has_agreed set to true in the decision response body:

   {
     "action": {
       "id": "termapia:abcdefg1234567",
       "device_id": "R5WNWB5BKNG9R",
       "deadline_duration": "PT5M",
       "status": "COMPLETED",
       "created_at": "2022-03-09T09:01:19.622Z",
       "updated_at": "2022-03-09T09:03:06.830Z",
       "type": "CONFIRMATION",
       "app_id": "sq0ids-abcdefg123456789",
        "confirmation_options": {
          "title": "Marketing communications",
          "body": "I agree to receive promotional emails about future events and activities.",
          "agree_button_text": "Agree",
          "disagree_button_text": "Decline"
          "decision": {
            "has_agreed": true
         }
       }
     }
   }