Cards API

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

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

Saving cards on file makes it easy for sellers to take payments — especially for recurring subscriptions and invoices — and for buyers to make payments. Letting buyers select a card on file leads to fast and seamless checkouts that can keep buyers coming back. In addition to storing cards in a seller account for payments to that seller, the Cards API can be used to retrieve card information, disable cards, or store shared cards in a developer account for payments to multiple sellers.

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

Applications that integrate with the Cards API can benefit from enterprise-level features provided by Square:

• Secure storage - Card information is securely stored by Square.
• Network tokenization - Enables faster, more secure payments with a reduced risk of fraud and declines.
• Strong Customer Authentication (SCA) verification - Integrates support for verifying the buyer's identity, reduces the risk of fraud, and shifts chargeback liability from sellers.
• Automatic account updates - When allowed by the issuing bank, Square automatically updates expiring cards to reduce declines and help increase customer retention. Subscribe to the card.automatically_updated webhook event to get notifications that contain the updated expiration date and last 4 digits of the card number.
• Shared cards - Enables franchise and marketplace applications to make card-on-file payments to multiple sellers.

• To save a card on file for a Square seller in the production environment, the seller account must be enabled for card processing.

• Applications using OAuth require the following permissions to manage stored cards in a seller account:

  • PAYMENTS_WRITE to create or disable cards.
  • PAYMENTS_READ to retrieve cards.
  • CUSTOMERS_READ and CUSTOMERS_WRITE to retrieve and create customer profiles associated with a card.

  Sellers who receive payments from shared cards must grant the following permissions:

  • PAYMENTS_WRITE_SHARED_ONFILE to create payments from shared cards on file.
  • CUSTOMERS_READ and CUSTOMERS_WRITE to retrieve and create corresponding customer profiles.

• The access token in the CreateCard request must be issued for the same application that generates the payment token or the payment used as the card source.

• Only credit cards and debit cards can be saved as cards on file. Payments made using Square Pay, Apple Pay, Google Pay, Cash App Pay, or cards on file cannot be used to store a card.

  To manage Square gift cards on file, use the Gift Cards API and Gift Card Activities API.

• To be notified when cards are created or changed, you must subscribe to card webhook events.

• Square doesn't provide a prebuilt form for collecting a billing address or other contact information from a buyer, so you need to create one.

The Cards API lets you save a credit or debit card on file for a customer in a Square account and later retrieve or disable the stored card. Cards are typically stored in a seller account and used only for payments to that seller. Square also supports storing shared cards in a developer account for payments to different sellers.

After the card is stored, the card ID can be used for card-on-file payments. When allowed by the issuing bank, Square automatically updates expiring cards with the new expiration date and last four digits. You can subscribe to card.automatically_updated and other webhook events to be notified about automatic updates and other card changes.

The process of saving a card on file typically starts with your application collecting card information from buyers (using the Web Payments SDK or In-App Payments SDK) and optionally creating a payment. Then, you can call CreateCard to store the card. Note the following key fields in the request:

• source_id can be a payment ID from a recent payment created using the Payments API or a payment token generated using the Web Payments SDK or In-App Payments SDK.

• card contains information such as the cardholder name and billing address. To get the required customer_id, use the Customers API to retrieve an existing customer profile or create a new one if needed.

• verification_token authenticates a buyer's identity for SCA, which is required for some regions or sellers. Buyer verification can be implicitly included in the request when using the Web Payments SDK.

For each CreateCard request, Square initiates a $0 charge for verification purposes, without removing any money from the customer’s account. If the verification fails, Square returns an error. Possible reasons for failure include:

• An incorrect card account number was provided.
• The card verification value (CVV) check failed.
• The expiration date has passed.
• The account associated with the card is closed or in bad standing.
• The address verification service (AVS) check failed because the billing postal code provided by the customer doesn't match the issuer's records.

You can save a card on file using the ID of a recent successful payment made using the credit or debit card that you want to store. To use a payment ID:

• Get the ID from a CreatePayment or ListPayments response. You can also call RetrieveOrder or SearchOrders and get the payment ID from the id or payment_id field of the corresponding tender.
• Provide the payment ID as the source_id in your CreateCard request.

For example steps, see Charge and Store a Card on File with SCA.

You can save a card on file using a payment token, which securely encapsulates payment instrument data. To use a payment token:

• Use the Web Payments SDK or In-App Payments SDK from your application frontend to collect credit or debit card information from the buyer and generate a payment token.
• Provide the payment token as the source_id in your CreateCard request.

For example steps, see Create a Card on File and a Payment.

The Cards API integrates with other Square APIs when saving cards on file.

• Payments API - Used to store a card when providing a payment ID as the source_id in a CreateCard request. Typically, this is the payment ID returned from a CreatePayment request. Alternatively, get the payment ID by calling ListPayments or by calling RetrieveOrder or SearchOrders in the Orders API. In an order, the payment ID is the id or payment_id field of the corresponding tender.

• Web Payments SDK or In-App Payments SDK - Used to store a card when providing a payment token as the source_id in a CreateCard request. Also used to integrate SCA and to generate a payment token for the source_id in a CreatePayment request. Your application frontend uses one of these SDKs to provide the form where customers input their card information.

• Customers API - Used to create or retrieve the customer profile associated with the stored card. Call SearchCustomers or CreateCustomer (as needed) to get the customer_id for a CreateCard request.

In addition, applications can configure settings in the Terminal API, Point of Sale API, and Invoices API that allow buyers to save a card on file after a payment. Square handles the card storage process for these integrations.

Square GraphQL queries provide read access to card data through the cardsOnFile entry point.

Square supports network tokenization for Visa, Mastercard, and American Express cards in all supported countries. Network tokenization replaces the primary account number (PAN) and other card information with a token provided by the card issuer. When used for payment, Square sends the network token instead of the PAN.

Network tokenization leads to more sales (fewer declines) because network tokens are updated in real time and are more trusted by issuers than standard PANs. Square manages network tokenization and token updates, so no action is needed by sellers or developers.

Developers can store cards in their own Square developer account and use them for payments to different Square sellers. These stored cards, known as shared cards, allow buyers to save a card once and use it with any seller on the application.

For example, suppose your application lets buyers order from various food and beverage sellers. When a buyer pays for an order from a seller (such as Pasta Donna), they're prompted to store their card for future payments through the application. The buyer can then use the card to pay for orders from other sellers on the application (such as Joy Bakeshop or Authentic Tacos).

Each buyer who pays using a shared card must have a customer profile in your developer account and a corresponding customer profile in each seller account that takes a shared card payment. For the customer_id field in the CreatePayment request, specify the ID of the corresponding customer profile in the seller account.

For steps that show how to store a shared card and use it for a payment, see Create a Shared Card on File and Make a Payment.

Participating sellers must grant your application the permissions needed to make shared card payments:

• PAYMENTS_WRITE_SHARED_ONFILE to create payments from shared cards in the seller account.
• CUSTOMERS_WRITE and CUSTOMERS_READ to create and retrieve customer profiles in the seller account.
• Optional - PAYMENTS_READ if your application also retrieves payment information from the seller account.

Card-on-file payments can be created or configured using the card ID with the Subscriptions API, Invoices API, and Payments API. If you need to get a card ID, you can list cards on file for a customer.

• Subscriptions API - A card_id can be specified in a CreateSubscription request to automatically charge the card each billing period.

• Invoices API - A card_id can be specified in a CreateInvoice request to automatically charge the card when the payment is due.

• Payments API - A card ID can be specified as the source_id in a CreatePayment request to make a card-on-file payment. Card-on-file payments also require the customer_id of the associated customer profile. For payments from a shared card, customer_id is the ID of the corresponding customer profile in the seller account (not the developer account).

  You can integrate SCA verification in a CreatePayment request.

In addition, the Refunds API accepts a card ID for unlinked refunds to cards on file. The Invoices API and Point of Sale API can also be used to configure card-on-file payments as an accepted payment method.

• 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