Cards API

Applies to: Cards APICards API | Customers APICustomers API | Payments APIPayments API | Web Payments SDKWeb Payments SDK | In-App Payments SDKIn-App Payments SDK | GraphQLGraphQL

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 tokenizationNetwork tokenization - Enables faster, more secure payments with a reduced risk of fraud and declines.
• Strong Customer Authentication (SCA) verificationStrong 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 eventwebhook event to get notifications that contain the updated expiration date and last 4 digits of the card number.
• Shared cardsShared 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 OAuthOAuth 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 cardsshared 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 APIGift Cards API and Gift Card Activities API.

• To be notified when cards are created or changed, you must subscribe to card webhook eventswebhook 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 disableretrieve 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 cardsshared 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 paymentscard-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 eventswebhook 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 SDKWeb Payments SDK or In-App Payments SDKIn-App Payments SDK) and optionally creating a payment. Then, you can call CreateCardCreateCard to store the card. Note the following key fields in the request:

• source_id can be a payment IDpayment ID from a recent payment created using the Payments API or a payment tokenpayment 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 SCASCA, 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 paymentpayment made using the credit or debit card that you want to store. To use a payment ID:

• Get the ID from a CreatePaymentCreatePayment or ListPaymentsListPayments response. You can also call RetrieveOrderRetrieveOrder or SearchOrdersSearchOrders 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 SCACharge 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 SDKWeb Payments SDK or In-App Payments SDKIn-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 PaymentCreate a Card on File and a Payment.

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

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

• Web Payments SDKWeb Payments SDK or In-App Payments SDKIn-App Payments SDK - Used to store a card when providing a payment tokenpayment 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 APICustomers API - Used to create or retrieve the customer profile associated with the stored card. Call SearchCustomersSearchCustomers or CreateCustomerCreateCustomer (as needed) to get the customer_id for a CreateCard request.

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

Square GraphQLSquare 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 countriessupported 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 PaymentCreate 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 customerlist cards on file for a customer.

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

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

• Payments APIPayments API - A card ID can be specified as the source_id in a CreatePaymentCreatePayment 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 cardshared card, customer_id is the ID of the corresponding customer profile in the seller account (not the developer account).

  You can integrate SCA verificationSCA verification in a CreatePayment request.

In addition, the Refunds API accepts a card ID for unlinked refundsunlinked 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 FileManage Customer Cards on File
• Create a Card on File from a Payment IDCreate a Card on File from a Payment ID
• Create a Card on File and a PaymentCreate a Card on File and a Payment
• Create a Shared Card on File and Make a PaymentCreate a Shared Card on File and Make a Payment