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 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 signature confirmation screen. You can also edit the text that displays for the agree and disagree buttons.

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": "Please 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 see the Terminal action that includes the decision.

The response returns the signature image in the data field, as a PNG file encoded in base64.

{
    "action": {
      "id": "termapia:Dw3eDfGPqIBublCE",
      "device_id": "R5WNWB5BKNG9R",
      "deadline_duration": "PT5M",
      "status": "COMPLETED",
      "created_at": "2022-03-09T12:17:55.353Z",
      "updated_at": "2022-03-09T12:17:56.091Z",
      "type": "SIGNATURE",
      "app_id": "sq0ids-abcdefg123456789",
      "signature_options": {
        "title": "Equipment Pick Up",
        "body": "Sign below to confirm your equipment pickup.",
        "signature": [
          {
            "id": "John_Hancock_Signature.png",
            "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