Save a Card on File with the Terminal API

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.

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

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

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.

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

{
   "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.

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

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

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.

The response returns resources for the card and the customer.

{
  "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"
     },
   },
 },
}

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.

The response returns details about the device and the customers.

{
  "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"
}

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.

The response returns the pending status of the cancel request.

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

• Connect a Square Terminal to a POS Application
• OAuth API Overview
• Customers API Overview
• Cards API Overview