Save a Card on File with the Terminal API

Applies to: Terminal API | Cards API | Payments API | Customers API | OAuth API

Learn how to save a customer's card for making future purchases.

After pairing a Square Terminal with a POS application, use the Terminal API to save a customer's card on file. 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 must be paired with a POS application.

• You must have a customer profile. You create a customer profile with the Customers API.

• The following permissions are enabled using the OAuth API:

  • PAYMENTS_WRITE
  • PAYMENTS_READ
  • CUSTOMERS_WRITE
  • CUSTOMERS_READ

• The latest Square Terminal OS version is installed. 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 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 taps the Confirm button to continue.
4. The Terminal API attempts to save the card.
5. After successfully saving the card on file, the Square Terminal 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.

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.

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.

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