Capture a buyer's signature

Learn how to display a confirmation screen that captures a buyer's signature on the Square Terminal.

Overview

As part of creating custom workflows with the Terminal API, you can create a screen workflow that captures a buyer's signature as confirmation of the displayed information. You send a Terminal action request of the SIGNATURE type and the Square Terminal displays a screen where the buyer provides a signature for the seller's records. The captured signature is returned in the Terminal action response when the action reaches the COMPLETED state.

In the request body, you can edit the title and body text that displays on the signature screen.

Link to section

How Square Terminal displays the signature screen

The following animation shows how the Square Terminal displays the signature screen for the buyer.

An animation of the signature collection screen displayed on the Square Terminal. A buyer is signing a form and submitting it.

Link to section

Make a signature capture request

Send a Terminal action POST request using the CreateTerminalAction endpoint and specify the SIGNATURE action type. In the signature_options body, provide screen text for title and body.

The Terminal action response includes an action_id and a PENDING status.

{
   "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": "SIGNATURE",
     "app_id": "sq0ids-abcdefg123456789",
     "signature_options": {
       "title": "Complete your pickup order",
       "body": "Sign below."
     }
   }
 }

The Square Terminal displays the signature capture screen for the buyer.

A captured signature on the Square Terminal screen.

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

Send a GET request to retrieve the completed Terminal action and the captured signature.

The response returns the captured signature in signature_options.signature. The data field contains the PNG image encoded as Base64.

{
    "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:04:11.091Z",
      "type": "SIGNATURE",
      "app_id": "sq0ids-abcdefg123456789",
      "signature_options": {
        "title": "Complete your pickup order",
        "body": "Sign below.",
        "signature": [
          {
            "image_type": "image/png;base64",
            "data":
               "iVBORw0KGgoAAAANSUhEUgAAAMcAAAA+BAMAAABtthIkAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAADBQTFRFAAAAgAAAAIAAgIAAAACAgACAAICAgICAwMDA/wAAAP8A//8AAAD//wD/AP//////ex+xxAAABFdJREFUWMPtl7uW3CAMhumg86vSQQcddHpVd1JHJMD4Oh4nu+7CSfbseow+/RKSGFXeX7P6D3kdQiA/4XcgtLOTx19RfkP/zZVnEAz1Zdf+smO3Asrowt6HE8M9g8xTNamqsdmM7TonsKHMdxCyw/Q9JDpPyfncLA+TIpA4WOZur1UPlZjMYQl9U1ieZtmdlmB+irRanbqFVCs9vbgGy+oExB+5m6380urCLWQWj7s/bg2WgmS+CYlqc/ZuIWa1hINRNVlTA/ZZiNJbZ28gOEJCZPaPGXIlJMkzObpWwebxHWSEhGB7WLkSSac1I2zZNdOoJm4DfHRR7Ty4gSy5JU6L3z4miAZFGzp+geIESnznt5X2MPOJtw4eQrAL4Q0z5CApoqaPVEAL1bAuIU44leQTv60BkJORdDIPIV4aCeXEpWhoDpLw1PQlXbOPwVsg7jG2SdbiE1cHP4kPw8WNCQ33RFMChsB24lR0F9LS7ksyHLqJgdIxbXD1RJA1qMsziAgBqZXAmzkg7B//LEFqAOqh4BwDFMV6qy7DJ4AUp1CXfUo+QwhyDaybIU3SgKNne5KVWgNGIoQTlTkwQbxR2Ytayirsg3UDSRmqkOCZMAci3XqybJkkWvzPQuYIRkl2RiPua/KSsOkZhJtsDaxD8ZSd5qj3wlQtWqlkzUKg0hFmA/KZk5wf6/QDhHiLtF2cUlHAEpjU/OMxUaNFEyK/VPWRh9Z3ZBzkPji/Qoilo3QGSzXkdWLVrczgauZfYw7R1bBtLbbfY3kAIRlT0gNxciJIjlaRtGfHDM0Oy3CUM0SbSb4u/QSSa+gl7cYjH8pp6ZWUfXZBChLXkXQR6weQ2qisuGNdPVKf7V0u/A5plwxpqNXdYzSofF0PIG0U1qvGLqd9uVPEz5D2RnauV/4J0ieICDkvTgd3wW+XOjmXxHccXtZfQahZSLvJNkRKB4inMjhD8tK8SM7oEUJN6bUQuTBa2g9e9tbx/z12s5ukjx0g3QN7KYSnGNc5yAkmCXhdmSvHQV5Xcjlu0+aOkH7/IXUZdvEJbE7WsV23up/We59o44a23R8PkKV7XmcEAxUl5i2cPjk82EbC7CFLpaLaHXSOj4QBaPIpJC6U44WLztTNtesAWd61W3WUZQYLh6egkwl/7BrJn3XHcROWWttAxmVxFUJVQSWIJAIRsf/CkN0ZUYdOp0hHXiHDwRHQXF2kURaEImQ39vj8luuVlPPSo8IOsvSQ9WjVmmUNYYEE3H+JyxeB2mB4vDU5A7Iw0I6cDQXjAW0OEvPLl7V83RsQM4J59m59kta6uxNxWAtk8cpe1WGXQnIrftDqP0FGsNRlI5fg0185fwUJ3Vf7aVjQPxMGBEewwr+b+gbppueb28GPIb0ZtQnzFqT7b18SUiE9I/hOQjqk2Sb77YLwE0irkRcZAqnXY4oG3oTUQ/xa0lcIvcoQyKydepUhEHLudvj8CuT99R/yd5A/BOwVsIky5msAAAAASUVORK5CYII="
             }
          ]
       }
     }
   }

Docs

Capture a buyer's signature

On this page

Overview

How Square Terminal displays the signature screen

Make a signature capture request

On this page