Applies to: Cards API
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
Network tokenization - Enables faster, more secure payments with a reduced risk of fraud and declines. - Strong Customer Authentication (SCA) verification
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 eventwebhook event to get notifications that contain the updated expiration date and last 4 digits of the card number. - Shared cards
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
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
andCUSTOMERS_WRITE
to retrieve and create customer profiles associated with a card.
Sellers who receive payments from shared cards
shared cards must grant the following permissions:PAYMENTS_WRITE_SHARED_ONFILE
to create payments from shared cards on file.CUSTOMERS_READ
andCUSTOMERS_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
Gift Cards API and Gift Card Activities API .To be notified when cards are created or changed, you must subscribe to card webhook events
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.
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.
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
After the card is stored, the card ID can be used for card-on-file paymentscard.automatically_updated
and other webhook events
The process of saving a card on file typically starts with your application collecting card information from buyers (using the Web Payments SDK
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 requiredcustomer_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.
Create card
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
- Get the ID from a CreatePayment
CreatePayment or ListPaymentsListPayments response. You can also call RetrieveOrderRetrieveOrder or SearchOrdersSearchOrders and get the payment ID from theid
orpayment_id
field of the corresponding tender. - Provide the payment ID as the
source_id
in yourCreateCard
request.
For example steps, see Charge and Store a Card on File with SCA
The source payment used for the
CreateCard
request must:- Have been authorized within the last 24 hours. To validate, check the
card_details.created_at
timestamp. - Be in a successful state. To validate, make sure that
card_details.status
isAUTHORIZED
orCAPTURED
. - Not be a card-on-file payment. To validate, check that
card_details.entry_method
isn'tON_FILE
. - Be created in the same seller account where the card is stored. Note that payment IDs cannot be used to store shared cards
shared cards in a developer account.
- Have been authorized within the last 24 hours. To validate, check the
If the payment includes a postal code in the
billing_address.postal_code
field, the card on file defaults to this value. If you provide a postal code in aCreateCard
request, it must match the payment's postal code if one is defined.Set the appropriate intent when integrating SCA verification
SCA verification :SDK Intent or buyer action Web Payments SDK CHARGE_AND_STORE
, which lets you use the same verification forCreatePayment
andCreateCard
.In-App Payments SDK
Android -
Charge
forCreatePayment
verification and thenStore
forCreateCard
verification.iOS -
chargeActionWithMoney
forCreatePayment
verification and thenstoreAction
forCreateCard
verification.
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
Web 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 yourCreateCard
request.
For example steps, see Create a Card on File and a Payment
If you provide a postal code in a
CreateCard
request, it must match the postal code entered by the buyer in the SDK's payment card form.Set the appropriate intent when integrating SCA verification
SCA verification :SDK Intent or buyer action. Web Payments SDK STORE
forCreateCard
verification.In-App Payments SDK
Android -
Store
forCreateCard
verification.iOS -
storeAction
forCreateCard
verification.
The Cards API integrates with other Square APIs when saving cards on file.
Payments API
Payments API - Used to store a card when providing a payment IDpayment ID as thesource_id
in aCreateCard
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 theid
orpayment_id
field of the corresponding tender.Web Payments SDK
Web Payments SDK or In-App Payments SDKIn-App Payments SDK - Used to store a card when providing a payment tokenpayment token as thesource_id
in aCreateCard
request. Also used to integrate SCA and to generate a payment token for thesource_id
in aCreatePayment
request. Your application frontend uses one of these SDKs to provide the form where customers input their card information.Customers API
Customers API - Used to create or retrieve the customer profile associated with the stored card. Call SearchCustomersSearchCustomers or CreateCustomerCreateCustomer (as needed) to get thecustomer_id
for aCreateCard
request.
In addition, applications can configure settings in the Terminal API
Square GraphQLcardsOnFile
entry point.
Note
The Cards API also integrates with other Square APIs for card-on-file payments
Square supports network tokenization for Visa, Mastercard, and American Express cards in all supported countries
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
andCUSTOMERS_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
Subscriptions API - Acard_id
can be specified in a CreateSubscriptionCreateSubscription request to automatically charge the card each billing period.Invoices API
Invoices API - Acard_id
can be specified in a CreateInvoiceCreateInvoice request to automatically charge the card when the payment is due.Payments API
Payments API - A card ID can be specified as thesource_id
in a CreatePaymentCreatePayment request to make a card-on-file payment. Card-on-file payments also require thecustomer_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 verification
SCA verification in aCreatePayment
request.
In addition, the Refunds API accepts a card ID for unlinked refunds
- Manage Customer Cards on File
Manage Customer Cards on File - Create a Card on File from a Payment ID
Create a Card on File from a Payment ID - Create a Card on File and a Payment
Create a Card on File and a Payment - Create a Shared Card on File and Make a Payment
Create a Shared Card on File and Make a Payment