Cards API

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.

How the API works Permalink Get a link to this section

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 fetch 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 does not remove any money from the card holder'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.

Store a card on file from a payment token Permalink Get a link to this section

To create a card on file with a payment token source, you must generate a payment token using the Web Payments SDK, Square payment form, or In-App Payments SDK. Provide the card token in the 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.

Store a card on file from a payment ID Permalink Get a link to this section

You can store a card on file if you have a card Payment whose source was keyed-in or card-present. A card on file cannot be used as a source. In this case, fetch 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 is not 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.

Store and charge a card on behalf of a seller account Permalink Get a link to this section

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 then 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.

Requirements and limitations Permalink Get a link to this section

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.

Related topics Permalink Get a link to this section