Cards API

Applies to: Cards API | Customers API | Payments API | Web Payments SDK | In-App Payments SDK

Use the Cards API to save credit or debit card information for future card-on-file payments.

Storing cards on file makes it easy for sellers to take payments — especially for recurring subscriptions and invoices — and for buyers to make payments. In addition to storing cards in a seller account, the Cards API can be used to retrieve card information, disable cards, or store shared cards in a developer account for payments to different sellers.

Watch the following video tutorial for an introduction to the Cards API and then continue reading for an in-depth overview.

• The Square seller account must be enabled for card processing to create a card on file.
• Applications using OAuth must have the following permissions to manage stored cards:
  • PAYMENTS_WRITE to create or disable cards.
  • PAYMENTS_READ to retrieve cards.
• When a card stored in a Square developer account is used to make payments to 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.
• 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. Square gift cards are managed using the Gift Cards API and Gift Card Activities API. For more information, see Manage Square Gift Cards on File.

The Cards API is used to store a buyer's credit card or debit card in a Square account. Cards are typically stored in a seller account for payments to that seller only, but the Cards API also supports storing shared cards in a developer account for payments to different sellers.

To store a card on file in a seller account, call the CreateCard endpoint and provide:

• Card information, such as the card holder's name and billing address.
• The customer ID obtained using the Customers API to retrieve an existing customer or create a new customer.
• A payment token generated using the Web Payments SDK or In-App Payments SDK, or the ID of a recent payment created using the Payments API.

After the card is stored on file, the card ID is used for payments to the seller account. You can call the ListCards endpoint to retrieve the cards on file for a customer.

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. If the verification process fails, CreateCard returns an error. 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.

If the stored card is suspended or expires after it has been stored, 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.

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.

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.

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.

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.

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.

• Manage Customer Cards on File
• Create a Card on File from a Payment ID
• Create a Card on File and a Payment
• Create a Shared Card on File and Make a Payment