Cards API Overview

Use the Cards API to save a credit or debit card for a customer. Your application can then charge the card when the customer makes purchases in the future. The API can also be used by a developer account-registered application to create and charge cards on behalf of a seller account.

The following video tutorial provides an introduction to the Cards API. For an in-depth overview of the Cards API, see the following sections in this topic.

Important

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

How the API works

The Cards API is used along with the Customers API to store payment cards for a customer in a Square account. To store a card on file, your application must use the Customers API to retrieve an existing customer or create a new customer. When your application obtains a customer ID, it can call the CreateCard endpoint with card information, a payment token, and the customer ID. After the card is stored on file for the customer, that customer can used the stored card for payments to the seller account.

When you send a CreateCard request, the Cards API confirms that the card is valid by initiating a $0 verification against the card. The verification process doesn't remove any money from the cardholder's account. The verification process can fail for several reasons, including:

  • An incorrect card account number or CVV number.
  • The expiration date has passed.
  • The account associated with the card is closed or in bad standing.

In these cases, the CreateCard endpoint returns an error.

If the stored card is suspended or expires after it has been stored then the Cards API automatically updates the status of the stored card. When an automatic update happens, your application is notified as long as it has subscribed to the card.automatically_updated webhook event.

Note

To save a Square gift card on file, use the Gift Cards API. For more information about saving a Square gift card on file, see Manage gift cards on file.

Link to section

Store a card on file from a payment token

To create a card on file with a payment token source, you must generate a payment token using the Web Payments SDK or In-App Payments SDK. To see an example that uses the Web Payments SDK to get a payment token and store a card, see Card on File with SCA.

Provide the card token in the Cards API CreateCard request to create a card on file for a customer in the seller Square account.

The OAuth access token you use in the CreateCard call must be issued for the same application ID that you used in the application that generated the card token.

Link to section

Store a card on file from a payment ID

You can store a card on file if you have a card Payment object whose source was keyed in or the card was present. A card on file cannot be used as a source. In this case, retrieve the Payment object and fill the source_id value with the Payment.id. The card that is keyed in for the payment is now stored on file for the customer who made the payment.

Important

A request to create a card on file from a payment ID must meet the following conditions:

  • The payment ID must be on a credit or debit card successfully authorized within the last 24 hours.
  • A card on file is saved with the postal code from the payment ID if the postal code isn't provided with the CreateCard call.
  • If a postal code is provided in the CreateCard call, it must match the postal code of the payment ID.
  • The payment ID can be used to create only one card on file.
  • The payment ID and the card to be stored must be on the same seller account.
  • A payment ID from a developer-shared card on file cannot be used to duplicate a card on file on the target seller account.
  • A new card on file cannot be created using a payment ID authorized from an existing card on file.
Link to section

Store and charge a card on behalf of a seller account

A third-party developer can store cards on file in their own Square developer account for the customers of the Square sellers who use the third-party application.

Cards stored by a third-party application can be used for any other seller on the application. These are known as shared cards and enable a customer to save a card in the application once and use it with any other seller on the application.

For example, the third-party application you develop might be used by many different food sellers. When a customer wants to pay for a pie from one of the Square sellers on your application (such as Bob's Online Pizza Orders), the customer is prompted once to store the payment card with the seller's Square account. The customer can then use the card for purchases from any other Square seller that uses your application (such as Hometown Pies To Go or Rafael's Tacos to Your Door).

Developers put the cards on file for their own developer account and sellers grant the developer permission to create payments on the seller account using the developer stored card.

Link to section

Network tokenization

Network tokenization replaces a MasterCard or Visa payment card primary account number (PAN) and other card information with a token provided by the card issuer. When a tokenized card is used for a payment, the Cards API provides the network token to the card network as the payment card identifier. In this way, sensitive card information isn't transmitted with each payment request, reducing the risk of payment card fraud. Chargeback liability can be shifted from the seller to the card issuer in many cases.

Unlike a physical payment card or stored PAN, a network token doesn't expire. In practice, that means that if the buyer's Mastercard or Visa payment card has been stored on file and tokenized, they can still make payments with the stored card even though their physical card might have expired.

Note

For card brands that the Cards API doesn't provide network tokenization, storing a card on file is still available. In these cases, payment requests are transmitted to the card network using PANs. For information about supported card brands, see Card on file for payment.

Link to section

Requirements and limitations

Your application can use the Cards API when it meets the following requirements:

Permission requirements

  • The seller Square account must be enabled for card processing to create a card on file.
  • Applications using OAuth must have the following permissions:
    • PAYMENTS_WRITE to create or disable cards.
    • PAYMENTS_READ to retrieve cards.
  • When a card on file owned by a Square developer account is used to make payments for a seller, the following permissions are required:
    • PAYMENTS_WRITE_SHARED_ONFILE to pay with a shared card.
    • CUSTOMERS_WRITE to create a customer in the seller account.

API limitations

  • The Cards API cannot create a card on file using Apple Pay or Google Pay payment tokens.
  • The Cards API cannot store, retrieve, or manage Square gift cards. Use the Gift Cards API for Square gift cards.
Link to section

See also