Capture a Buyer's Signature

Applies to: Terminal API

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

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.

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

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

   Create terminal action

   cURL

   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.

   

   After the buyer signs the form, 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 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="
                }
             ]
          }
        }
      }
   }