Reader SDK: Code Cookbook

Save Cards on File

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 the customer to specify that they wish to save their card information for future purchases.

Reader SDK
Java (Android)

Important

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

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

  • You will need an access token. If you are using OAuth, you will 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 they are still valid and can be charged.

  • You need to have created a Customer object using the Customers API. You can follow The Customers API Setup Guide to create your first Customer object.

Step 1: Collect the card information
Permalink Get a link to this section

Did you know?

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

We recommend displaying a spinner or loading indicator before starting the card on file workflow and clearing it when you receive the result (success or failure) so users know that work is being done in the background.

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

import com.squareup.sdk.reader.ReaderSdk;
import com.squareup.sdk.reader.crm.CustomerCardManager;
import com.squareup.sdk.reader.core.CallbackReference;

CustomerCardManager customerCardManager =
    ReaderSdk.customerCardManager();

...

CallbackReference storeCardCallbackRef = customerCardManager.addStoreCardActivityCallback(result -> {
 hideLoadingIndicatorOnYourActivity();
 if (result.isSuccess()) {
   showStoreCardSuccessDialog(result.getSuccessValue());
 } else {
   showErrorDialog(result.getError());
 }
});

Step 2: Save the customer card on file
Permalink Get a link to this section

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

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