Terminal API

Save a Card on File with the Terminal API Beta release

This is pre-release documentation for an API in public beta and is subject to change.

After pairing a Square Terminal with a POS application, use the Terminal API to save a customer card on file for future transactions. This feature uses the Terminal actions endpoint to send a request to the Square Terminal, where it prompts the buyer to confirm to save the card on file. You can then send additional requests to get the card details. You can also manage the card with the Cards API and charge it using the Payments API.

Link to section
Prerequisites

A Square Terminal paired with a POS application.
A customer profile. You create a customer profile with the Customers API.
The following permissions enabled using the OAuth API:
- PAYMENTS_WRITE
- PAYMENTS_READ
- CUSTOMERS_WRITE
- CUSTOMERS_READ
The latest Square Terminal OS version. To check the OS version, on the Square Terminal, choose Settings, choose General, choose About Terminal, and then check the software version.
Your developer account must be enabled to subscribe to Terminal API action webhooks.

Link to section
Requirements and limitations

Saving a card on file is available only in the United States, Canada, and Australia.
In the United States, cards can be dipped or swiped to be saved on file.
In Canada and Australia, cards can only be swiped to be saved on file.

Link to section
Save a customer's card on file

Link to section
Create a new POST request and send it to the Square Terminal

Send a POST request to the Square Terminal with the CreateTerminalAction endpoint. In the Terminal action request details, provide the DEVICE_ID of the Square Terminal, the SAVE_CARD action type, and the customer_id and reference_id for save_card_options.

You can get the customer_id from the Customers API. The reference_id is an optional user-defined reference ID that you can use to associate the Card entity to another entity in an external system. For example, the value can be a customer ID that a third-party system generates.

The POST request uses the idempotency key (generated from the API request) and includes details about the Terminal action.

Create Terminal Action

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

curl https://connect.squareup.com/v2/terminals/actions \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "5f2e1vb9-c86a-6431-88d2-c0b49a84df66",
    "action": {
      "device_id": "{{DEVICE_ID}}",
      "type": "SAVE_CARD",
      "save_card_options": {
        "customer_id": "VDX6V4U34SDMNP8125E3453D",
        "reference_id": "user-id-1"
      }
    }
  }'

The response includes the Terminal action response ID, the status, and other details.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
   "action": {
       "id": "termapia:jveJIAkkAjILHkdCE",
       "device_id": "device_id123",
       "deadline_duration": "PT5M",
       "status": "PENDING",
       "created_at": "2021-07-28T23:22:07.476Z",
       "updated_at": "2021-07-28T23:22:07.476Z",
       "location_id": "LWTMJESMBQXZC9",
       "type": "SAVE_CARD",
       "app_id": "sq0ids-ESXCwyTF7NBxgzdrF_pvhA",
       "save_card_options": {
           "customer_id": "customer123",
           “reference_id”: “store-921”
       }
   }
}

After you get the response with a status code 200, the POS application launches the card collection flow.

Link to section
Card collection flow

The buyer authorizes the POS application to save the card on file.

On the Square Terminal, the buyer swipes the card.
The buyer gives authorization to the seller to save their card on file by tapping the Agree button.
The buyer confirms the email address, and then taps the Confirm button to continue.
The Terminal API attempts to save the card.
After successfully saving the card on file, the Terminal device displays a confirmation screen.

Link to section
Additional methods

Link to section
Get information about the saved card on file

Send a GET request to the Square Terminal with the GetTerminalAction endpoint, provide the action_id in the path parameter, and receive a response with information about the saved card on file.

Get Terminal Action

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

The response returns resources for the card and the customer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "action": {
    "id": "termapia:jveJIAkkAjILHkdCE",
    "device_id": "device_id123",
    "deadline_duration": "PT5M",
     "status": "PENDING",
     "created_at": "2021-07-28T23:22:07.476Z",
     "updated_at": "2021-07-28T23:22:07.476Z",
     "location_id": "LWTMJESMBQXZC9",
     "type": "SAVE_CARD",
     "app_id": "sq0ids-ESXCwyTF7NBxgzdrF_pvhA",
     "save_card_options": {
       "customer_id": "customer123",
       "card_id": "ccof:uIbfJXhXETSP197M3GB"
     },
   },
 },
}

Link to section
Search for the card on file

Send a POST request to the Square Terminal with the SearchTerminalActions endpoint, provide a search query in the request body, and receive a response with information based on the query. You can search for a customer resource, a card that is linked from the Terminal action, or both.

The POST request queries for devices with the PENDING status.

Search Terminal Actions

1
2
3
4
5
6
7
8
9
10
11
12

curl https://connect.squareup.com/v2/terminals/actions/search \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "status": "PENDING"
      }
    }
  }'

The response returns details about the device and the customers.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "action": [
    {
      "id": "98765",
      "device_id" : "xyz",
      "type": "SAVE_CARD",
      "status": "PENDING",
      "save_card_options": {
        "customer_id" : "JDKYHBWT1D4F8MFH63DBMEN8Y4"
      }
    },
    {
      "id": "98767",
      "device_id" : "xyz",
      "type": "SAVE_CARD",
      "status": "PENDING",
      "save_card_options": {
        "customer_id" : "JDKYHBWT1D4F8MFH63DBMEN8Y5"
      }
    },
  ],
  "cursor": "slfao29834ifuhk4eu9fgy234"
}

Link to section
Cancel the card collecting Terminal action

Use the v2/terminals/actions/{action_id}/cancel endpoint to send a POST request to the Square Terminal to cancel a pending or in-progress Terminal action. The response body contains information about the Terminal action used originally to save the card on file.

You can cancel the save card-on-file process in the following cases:

Before the buyer taps the Confirm button on the email confirmation screen.
When the buyer sees an error message on the Square Terminal after confirming the email.

The POST request includes the Terminal action ID.

Cancel Terminal Action

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

The response returns the pending status of the cancel request.

1
2
3
4
5
6
7
8
9
10
11

{
  "action": {
    "id": "actionId123",
    "device_id" : "deviceId123",
    "type": "SAVE_CARD",
    "status": "CANCEL_PENDING",
    "save_card_options": {
      "customer_id" : "customerId123"
    }
  }
}

Link to section
See also

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Save a Card on File with the Terminal API Beta release

This is pre-release documentation for an API in public beta and is subject to change.

Link to section
Prerequisites

Link to section
Requirements and limitations

Link to section
Save a customer's card on file

Link to section
Create a new POST request and send it to the Square Terminal

Link to section
Card collection flow

Link to section
Additional methods

Link to section
Get information about the saved card on file

Link to section
Search for the card on file

Link to section
Cancel the card collecting Terminal action

Link to section
See also

On this page

Docs

Save a Card on File with the Terminal API Beta release This is pre-release documentation for an API in public beta and is subject to change.

Link to section Prerequisites

Link to section Requirements and limitations

Link to section Save a customer's card on file

Link to section Create a new POST request and send it to the Square Terminal

Link to section Card collection flow

Link to section Additional methods

Link to section Get information about the saved card on file

Link to section Search for the card on file

Link to section Cancel the card collecting Terminal action

Link to section See also

On this page

Save a Card on File with the Terminal API Beta release

This is pre-release documentation for an API in public beta and is subject to change.

Link to section
Prerequisites

Link to section
Requirements and limitations

Link to section
Save a customer's card on file

Link to section
Create a new POST request and send it to the Square Terminal

Link to section
Card collection flow

Link to section
Additional methods

Link to section
Get information about the saved card on file

Link to section
Search for the card on file

Link to section
Cancel the card collecting Terminal action

Link to section
See also