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.

Link to section


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.

Link to section

How Square Terminal displays the confirmation screen

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

An animated GIF of the confirmation screen displayed on the Square Terminal.

Link to section

Make a confirmation screen request

  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

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

    The Square Terminal displays the confirmation screen for the buyer.

    A Square Terminal screen to confirm to agree or decline receiving marketing communications from the seller.

    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

    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: