The Cards API provides a set of endpoints for you to manage cards on file. You can retrieve card information, list cards on file, and disable a card.
Cards API

Manage Customer Cards on File

The Cards API provides a set of endpoints for you to manage cards on file. You can retrieve card information, list cards on file, and disable a card.

If your application has a card ID, it calls the RetrieveCard endpoint to get information about the associated card.

Retrieve Card
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/cards/CARD_ID \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The Cards API returns a response like the following example:

Call the ListCards endpoint to get a paginated list of information about the cards on file for the Square account associated with the access token provided in the request.

Your application can get all saved cards in a Square account or it can limit the response to cards for a customer, enabled the state of a card, or both. Regardless of whether you filter by a customer ID, you can set a page size for the response pages.

The following request lists all the enabled cards for a given customer:

List Cards
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/cards?customer_id=CUSTOMER_ID&cursor=CURSOR&limit=25&enabled=true \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The Cards API returns a response like the following example:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
{
  "cards": [
    {
        "id": "ccof:uIbfJXhXETSP197M3GB",
        "billing_address": {
           "address_line_1": "500 Electric Ave",
           "address_line_2": "Suite 600",
           "locality": "New York",
           "administrative_district_level_1": "NY",
           "postal_code": "10003",
           "country": "US"
        },
        "bin": "411111",
        "card_brand": "VISA",
        "card_type": "CREDIT",
        "cardholder_name": "Amelia Earhart",
        "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8",
        "enabled": true,
        "exp_month": 11,
        "exp_year": 2024,
        "last_4": "1111",
        "prepaid_type": "NOT_PREPAID",
        "reference_id": "user-id-2",
        "version": 2
    }
  ],
  "cursor": "13SDKXRNKPJN48QDG3BGGFAK05P81653"
}

If your application has a card ID, it calls the DisableCard endpoint to disable a card on file. After a card is disabled, any request to the CreatePayment endpoint that references the disabled card returns an error.

Disable Card
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareupsandbox.com/v2/cards/CARD_ID/disable \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The Cards API returns a response like the following example:

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.