Applies to: Terminal 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
Applies to: Terminal 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
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 CreateTerminalActionDEVICE_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 APIreference_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
The buyer authorizes the POS application to save the card on file.
Send a GET request to the Square Terminal with the GetTerminalActionaction_id
in the path parameter, and receive a response with information about the saved card on file.
Get terminal action
Send a POST request to the Square Terminal with the SearchTerminalActions
The POST request queries for devices with the PENDING
status.
Search terminal actions
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:
The POST request includes the Terminal action ID.
Cancel terminal action
If you need more assistance, contact Developer and App Marketplace Support