Save a Card on File

Link to section


Use the Reader SDK card-on-file workflow to create a customer card for an existing Customer object. The card-on-file workflow is a sequence of screens used by customers to specify that they want to save their card information for future purchases.


Always ask customers for permission before saving their card information. For example, include a checkbox in your purchase flow that customers can select to specify that they want to save their card information for future purchases.

Linking cards on file without obtaining customer permission can result in your application being disabled without notice.

Link to section

Requirements and limitations

  • You need an access token. If you're using OAuth, you need CUSTOMERS_WRITE permission to save a card on file and PAYMENTS_WRITE permission to process payments with the saved card. Cards on file are automatically updated on a monthly basis to confirm that they are still valid and can be charged.
  • You need to create a Customer object using the Customers API. To create your first Customer object, see Customers API.
Link to section

1. Collect the card information

Did you know?

The card-on-file workflow begins with an asynchronous call to Square servers, which can be slow depending on network conditions.

You should display a spinner or loading indicator before starting the card-on-file workflow and clear it when you receive the result (success or failure) so users know that work is being performed in the background.

Use the CustomerCardManager class to create a new customer card manager to securely collect card information. Customer card information is stored on Square servers, not on the device running the Reader SDK, so you need to implement a callback to handle the response from Square.

Link to section

2. Save the customer card on file

Use the customer card manager to start the StoreCard activity and link the card to an existing customer ID.

showLoadingIndicatorOnYourActivity(); customerCardManager.startStoreCardActivity(activity, customerId));