Introducing New Terminal API Customization Features

The Terminal API allows developers to integrate Square Terminal, our all-in-one card processing device, with their custom point-of-sale, ERP, practice management system, or any other app to process in-person payments.

We are excited to announce the beta launch of Custom Workflows on Terminal API, a new feature empowering developers to create dynamic buyer-facing workflows on the Square Terminal that extend beyond payments. Developers can now incorporate customizable screens and interactive steps during the checkout process to better support sellers with more intricate business and operational needs. Examples of custom workflows that can be built into the Terminal include:

• Confirmation Screen: Capture the customer’s decision to agree or disagree, such as their confirmation of order details or terms.
• Signature Capture: Collect a customer’s signature outside of a payment, such as when they pick up an order or consent to terms.
• Email / Phone Number Collection: Collect customer contact information, such as their phone number or email address.
• Multiple Choice Screen: Display menu options for customers to select.
• Display QR Code: Display a scannable QR code.

Developers can now streamline operations and modernize the checkout experience for sellers by enabling them to accomplish multiple tasks and seamlessly accept payments all through the convenience of a single device - the Square Terminal.

"Custom Workflows provides all the functionality we need to complete our full signature capture flow and is also very well designed and easy to use. The screens look good, and they flow seamlessly from one to the other."

— Braulio Salcedo, Developer at BestRx

But that’s not all. In addition to Custom Workflows, we are thrilled to announce the general availability of Custom Idle Screen on Terminal API. This feature gives sellers the ability to showcase their brand by displaying a series of rotating images and their business name on the Square Terminal. Sellers can easily upload images and customize the Terminal idle screen at any time through the Square Dashboard without the need for any developer involvement.

How it works

Here’s an example of making a signature capture request.

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.

   curl https://connect.squareup.com/v2/terminals/actions \
    -X POST \
    -H 'Square-Version: 2023-06-13' \
    -H 'Authorization: Bearer ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "idempotency_key": "5f2e1vb9-c86a-6431-88d2-c0b49a84df66",
      "action": {
        "device_id": "R5WNWB5BKNG9R",
        "type": "SIGNATURE",
        "signature_options": {
          "title": "Complete your pickup order",
          "body": "Please sign below."
        }
      }
    }'
   

   The TerminalAction 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 has signed the form, the Terminal action is then 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.

curl https://connect.squareup.com/v2/terminals/actions/{action_id} \
 -H 'Square-Version: 2023-06-13' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json'

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": "2023-06-13T12:17:55.353Z",
     "updated_at": "2023-06-13T12:17:56.091Z",
     "type": "SIGNATURE",
     "app_id": "sq0ids-abcdefg123456789",
     "signature_options": {
       "title": "Equipment Pick Up",
       "body": "Sign below to confirm your equipment pickup.",
       "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="
            }
         ]
      }
    }
  }
}

“Healthcare organizations usually collect signatures from patients by scanning printed copies of forms or using a separate signature pad. The new custom workflows for Terminal API enables us to help organizations such as California Skin Institute collect patient signatures directly from the Square Terminal, without the need to print or use a separate device.”

— John Bona, Co-Founder at Reference Health

Get started

Custom Workflows is available in beta to developers and Custom Idle Screen is generally available to sellers using Square Terminal in the U.S., Canada, UK, France, Ireland, Spain, Australia, and Japan.

To start building, check out the Custom Workflows developer documentation, technical reference, and payments pricing. If you need to assist sellers with the implementation of Custom Idle Screen, check out this documentation. As always, please share your feedback in our community Slack channel or Square Developer Forums. If you want to keep up to date with the rest of our content, be sure to follow this blog and our Twitter account.