Display a QR Code Beta release

Applies to: Terminal API

Learn how to display a QR code for a buyer to scan on the Square Terminal.

As part of creating custom workflows with the Terminal API, you can create a screen workflow that allows a buyer to scan a QR code. You send a Terminal action request of the QR_CODE type and configure options for the QR code in qr_code_options.

In the request body for qr_code_options, you provide the title text, body text, and barcode content that display on the screen.

For more information about encoding information to barcode content, see the open-source reference for barcode image processing standards.

You can build a screen workflow that prompts the buyer to scan the QR code and download the seller's application.

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

   Create terminal action

   cURL

   Copy

   Expand

   curl https://connect.squareup.com/v2/terminals/actions \
     -X POST \
     -H 'Square-Version: 2025-03-19' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "idempotency_key": "5f2e1vb9-c86a-6431-88d2-c0b49a84df66",
       "action": {
         "device_id": "R5WNWB5BKNG9R",
         "type": "QR_CODE",
         "qr_code_options": {
           "title": "Download the app",
           "body": "Skip the line with order ahead. Scan the QR code to download the app.",
           "barcode_contents": "BEGIN:VEVENT\nSUMMARY:dtestewtse\nDTSTART:20210316T230200Z\nDTEND:20210317T000200Z\nEND:VEVENT\n"
         }
       }
     }'

   Try in API Explorer

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

   Copy

   Expand

   {
      "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": "QR_CODE",
        "app_id": "sq0ids-abcdefg123456789",
        "qr_code_options": {
            "title": "Download the app",
            "body": "Skip the line with order ahead. Scan the QR code to download the app.",
            "barcode_contents": 
                  "BEGIN:VEVENT\nSUMMARY:dtestewtse\nDTSTART:20210316T230200Z\nDTEND:20210317T000200Z\nEND:VEVENT\n"
        }
     }
   }

   The Square Terminal displays the QR code screen for the buyer.

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

   Copy

   Expand

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

   Try in API Explorer

   The following response example shows the response with the status of COMPLETED for the QR code request:

   Copy

   Expand

   {
     "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:03:06.830Z",
       "type": "QR_CODE",
       "app_id": "sq0ids-abcdefg123456789",
       "qr_code_options": {
            "title": "Download the app",
            "body": "Skip the line with order ahead. Scan the QR code to download the app.",
            "barcode_contents": 
                  "BEGIN:VEVENT\nSUMMARY:dtestewtse\nDTSTART:20210316T230200Z\nDTEND:20210317T000200Z\nEND:VEVENT\n"
        }
     }
   }