You are viewing an old version of the API

All Versions

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

Guide

Manage cards on file Try in API Explorer

Path Parameters

Example code

Name	Description
`customer_id string` Required	The Square ID of the customer profile the card is linked to.

Request Body

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. For more information, see Walkthrough: Integrate Square Payments in a Website. NOTE: Card nonces generated by digital wallets (such as Apple Pay) cannot be used to create a customer card.
`billing_address Address`	Address information for the card on file. NOTE: If a billing address is provided in the request, the `CreateCustomerCardRequest.billing_address.postal_code` must match the postal code encoded in the card nonce.
`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

POST /v2/customers/{customer_id}/cards

curl https://connect.squareup.com/v2/customers/customer_id0/cards \
  -X POST \
  -H 'Square-Version: 2021-05-13' \
  -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"
  }'

{
  "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 The AVS could not be verified.	>
402 Payment required	VERIFY_CVV_FAILURE The CVV could not be verified.	>
403 Forbidden	CARD_PROCESSING_NOT_ENABLED The location provided in the API call is not enabled for credit card processing.	>

{
  "errors": [
    {
      "code": "CARD_EXPIRED",
      "category": "PAYMENT_METHOD_ERROR"
    }
  ]
}