Store a Card on File using Reader SDK

Last year, we announced the release of Square Reader SDK for iOS and Android, along with plugins for React Native and Flutter. While Reader SDK makes it easy to take in-person payments within your own app using Square hardware, you may also want to store customer card information securely to use in the future (for example, to create a recurring billing plan).

To help you create a seamless experience for returning customers and enable recurring payments, Reader SDK now supports storing a card on file using Square hardware. This new functionality works in tandem with the Customers API and Transactions API, allowing you to create a customer profile; swipe, tap, or dip a card to store it securely; and then charge the card for future purchases at any time.

Here’s how it works:

Create a Customer

Use the Customers API to create a customer profile, including contact information such as name, address, email, and phone number.

curl https://connect.squareup.com/v2/customers \
 -H "Authorization: Bearer SQUARE_ACCESS_TOKEN" \
 -H "Content-Type: 'application/json'" \
 -d '{
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "[email protected]",
    "address": {
        "address_line_1": "500 Electric Ave",
        "address_line_2": "Suite 600",
        "locality": "New York",
        "administrative_district_level_1": "NY",
        "postal_code": "10003",
        "country": "US"
    },
    "phone_number": "1-212-555-4240",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "a customer"
}'

Store a Card on File

Use Reader SDK to swipe, tap, or dip a customer’s card and store it as a card on file. Reader SDK handles all payment information securely and creates a Customer Card object for you, so you don’t have to worry about handling raw card details or dealing with PCI compliance.

Android

Create a CustomerCardManager:

import com.squareup.sdk.reader.ReaderSdk;
Import com.squareup.sdk.reader.crm.CustomerCardManager;

CustomerCardManager customerCardManager =
    ReaderSdk.customerCardManager();

Write a callback to handle the result:

import com.squareup.sdk.reader.core.CallbackReference;

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

Add code to start the Store Customer Card flow:

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

iOS

Implement StoreCustomerCardControllerDelegate Methods:

import SquareReaderSDK

extension <#YourViewController#>: SQRDStoreCustomerCardControllerDelegate {

    func storeCustomerCardController(_ storeCustomerCardController: SQRDStoreCustomerCardController, didFailWith error: Error) {
        hideLoadingView()
        // Show error message to user
    }
    
    func storeCustomerCardController(_ storeCustomerCardController: SQRDStoreCustomerCardController, didFinishWith card: SQRDCard) {
        hideLoadingView()
        // Indicate to user that card was linked
    }
    
    func storeCustomerCardControllerDidCancel(_ storeCustomerCardController: SQRDStoreCustomerCardController) {
        hideLoadingView()
        // Return to previous UI state
    }

Add code to start the Store Customer Card flow:

import SquareReaderSDK

extension <#YourViewController#> {
    func storeCardOnFile() {
        showLoadingView()
        let cardOnFileController = SQRDStoreCustomerCardController(customerID: customerID, delegate: self)
        cardOnFileController.present(from: self)
    }
}

Charge the Card on File

Once you’ve stored a Card on File for a given Customer, you can use the Transactions API to charge the card for future payments.

curl https://connect.squareup.com/v2/locations/LOCATION_ID/transactions \
  -H 'Authorization: Bearer SQUARE_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "idempotency_key": "UNIQUE_IDEMPOTENCY_KEY",
  "customer_id":"CBASEBJj_XENvP8BFVzZvlOa_y0gAQ",
  "customer_card_id": "8299e337-b459-5008-6dda-3724dda71f6b",
  "amount_money": {
        "amount": 100,
        "currency": "USD"
  }
}'

Meet your buyers wherever they are

With Square’s omnichannel developer platform and the addition of Card on File to Reader SDK, you can now add cards to a customer profile regardless of where the customer relationship starts: online, in-store, or in-app. We are excited to see what you’ll build!

You can read more about Reader SDK in our documentation. Be sure to read and follow the requirements for obtaining customer consent and disclosing terms and conditions outlined in the documentation.

If you want to keep up to date with the rest of our content, be sure to follow this blog, follow our Twitter account, and sign up for our developer newsletter! We also have a Slack community for connecting with and talking to other developers implementing Square APIs.