Cards API

A seamless buyer experience starts at checkout. Nothing says “poor experience'' like asking a buyer to rummage for their credit card every time they shop at their favorite store. With the Cards API, you can now store, retrieve, and manage credit and debit cards on file using a recent payment.

If you’re building a marketplace app, you can charge a stored card on behalf of multiple sellers who have authorized shared card-on-file functionality. Terminal API developers can also use Cards API to add card-on-file functionality to their application. Sellers won’t need to collect card payment information from their customers every time they make a purchase – improving customer experience and making it easier for sellers to close a sale.

The new Cards API release includes webhooks to notify you of new, disabled, and updated cards, and the API keeps stored cards up to date automatically as expirations and account numbers change.

How it works

Use the CreateCustomer endpoint to create a new customer in your developer account. Use your personal access token or an OAuth token scoped to your developer account.

curl https://connect.squareupsandbox.com/v2/customers \
  -X POST \
  -H 'Square-Version: 2021-06-16' \
  -H 'Authorization: Bearer {PERSONAL_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "[email protected]",
    "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"
    },
    "phone_number": "1-212-555-4240",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "a customer"
  }'

Then call the CreateCard endpoint with a nonce and an idempotency key, using an Oauth Token generated for the target seller account.

Then call the CreateCard endpoint with a payment card token and an idempotency key. Use your personal access token or an OAuth token scoped to your own developer account.

curl https://connect.squareupsandbox.com/v2/cards \
  -X POST \
  -H 'Square-Version: 2021-06-16' \
  -H 'Authorization: Bearer {PERSONAL_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "source_id": "{CARD_TOKEN}",
    "card": {
      "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"
      },
      "cardholder_name": "Amelia Earhart",
      "customer_id": "Q6VKKKGW8GWQNEYMDRMV01QMK8",
      "reference_id": "user-id-1"
    }
  }'

Next, create a customer record on the target seller account.

curl https://connect.squareupsandbox.com/v2/customers \
  -X POST \
  -H 'Square-Version: 2021-06-16' \
  -H 'Authorization: Bearer {SELLER_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "[email protected]",
    "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"
    },
    "phone_number": "1-212-555-4240",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "a customer on seller account"
  }'

Finally, create a payment using the developer’s card on a target seller account.

curl https://connect.squareupsandbox.com/v2/customers \
  -X POST \
  -H 'Square-Version: 2021-06-16' \
  -H 'Authorization: Bearer {SELLER_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "[email protected]",
    "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"
    },
    "phone_number": "1-212-555-4240",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "a customer on seller account"
  }'

You can also use Cards API to create a card on file with a payment ID as the source and manage cards with endpoints like RetrieveCard, ListCards, and DisableCard.

Start building

Cards API is publicly available to developers in the U.S., Canada, the UK, Ireland, Australia, and Japan. The API is free for developers, and businesses pay Square’s card-on-file processing rate (learn more about pricing). Cards API replaces the CreateCustomerCard and DeleteCustomerCard endpoints of the Customers API, which are now deprecated.

Check out the Cards API documentation to get started. As always, please share your feedback in our community Slack channel or Square Developer Forums. If you want to keep up to date with the rest of our content, be sure to follow this blog and our Twitter account!