• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Create customer card

POST /v2/customers/{customer_id}/cards

Adds a card on file to an existing customer.

As with charges, calls to CreateCustomerCard are idempotent. Multiple calls with the same card nonce return the same card record that was created with the provided nonce during the first call.


Permissions
CUSTOMERS_WRITE
Try in API Explorer
Name Description
customer_id
string

Required

The Square ID of the customer profile the card is linked to.

Name Description
card_nonce
string

Required

A card nonce representing the credit card to link to the customer.

Card nonces are generated by the Square Payment Form when customers enter their card information. See Embedding the payment form for more information.

NOTE: Card nonces generated by digital wallets (e.g., Apple Pay) cannot be used to create a customer card.

billing_address
Address

Address information for the card on file. Only the postal_code field is required for payments in the US and Canada.

cardholder_name
string

The full name printed on the credit card.

verification_token
string

An identifying token generated by SqPaymentForm.verifyBuyer(). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity.

Response Fields

Name Description
errors
Error [ ]

Any errors that occurred during the request.

card
Card

The created card on file.

Examples

You are viewing an old version of the API
POST /v2/customers/{customer_id}/cards
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
curl https://connect.squareup.com/v2/customers/customer_id0/cards \
  -X POST \
  -H 'Square-Version: 2020-08-26' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_nonce": "YOUR_CARD_NONCE",
    "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"
  }'
Response JSON
{
  "card": {
    "id": "icard-card_id",
    "card_brand": "VISA",
    "last_4": "1111",
    "exp_month": 11,
    "exp_year": 2018,
    "cardholder_name": "Amelia Earhart",
    "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"
    }
  }
}

Error Descriptions

400 Bad request CARD_EXPIRED

The card issuer declined the request because the card is expired.

>
400 Bad request CARD_TOKEN_EXPIRED

The provided card token (nonce) has expired.

>
400 Bad request CARD_TOKEN_USED

The provided card token (nonce) was already used to process payment.

>
400 Bad request INVALID_CARD

The credit card cannot be validated based on the provided details.

>
400 Bad request INVALID_CARD_DATA

Generic error - the provided card data is invalid.

>
400 Bad request INVALID_EXPIRATION

The expiration date for the payment card is invalid. For example, it indicates a date in the past.

>
400 Bad request UNSUPPORTED_ENTRY_METHOD

The entry method for the credit card (swipe, dip, tap) is not supported.

>
402 Payment required VERIFY_AVS_FAILURE

402 Request failed - the AVS could not be verified.

>
402 Payment required VERIFY_CVV_FAILURE

402 Request failed - the CVV could not be verified.

>
403 Forbidden CARD_PROCESSING_NOT_ENABLED

403 Forbidden - the location provided in the API call is not enabled for credit card processing.

>
400 Bad request
{
  "errors": [
    {
      "code": "CARD_EXPIRED",
      "category": "PAYMENT_METHOD_ERROR"
    }
  ]
}

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?