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

You are viewing an old version of the API
Create card

POST /v2/cards

Adds a card on file to an existing merchant.

Permissions
PAYMENTS_WRITE
 Try in API Explorer

Request Body

Example code
Name Description
idempotency_key
string
Required

A unique string that identifies this CreateCard request. Keys can be any valid string and must be unique for every request.

Max: 45 characters

See Idempotency keys for more information.

Min Length 1
source_id
string
Required

The ID of the source which represents the card information to be stored. This can be a card nonce or a payment id.

Min Length 1 Max Length 16384
verification_token
string

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

See the SCA Overview.
card
Card
Required

Payment details associated with the card to be stored.

Response Fields
Name Description
errors
Error [ ]

Information on errors encountered during the request.
card
Card

The newly created card.

Examples

You are viewing an old version of the API
POST /v2/cards
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/cards \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "4935a656-a929-4792-b97c-8848be85c27c",
    "source_id": "cnon:uIbfJXhXETSP197M3GB",
    "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": "VDKXEEKPJN48QDG3BGGFAK05P8",
      "reference_id": "user-id-1"
    }
  }'
Response JSON 
{
  "card": {
    "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"
    },
    "fingerprint": "ex-p-cs80EK9Flz7LsCMv-szbptQ_ssAGrhemzSTsPFgt9nzyE6t7okiLIQc-qw_quqKX4Q",
    "bin": "411111",
    "card_brand": "VISA",
    "card_type": "CREDIT",
    "cardholder_name": "Amelia Earhart",
    "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8",
    "enabled": true,
    "exp_month": 11,
    "exp_year": 2022,
    "last_4": "1111",
    "merchant_id": "6SSW7HV8K2ST5",
    "prepaid_type": "NOT_PREPAID",
    "reference_id": "user-id-1",
    "version": 1
  }
}

Error Descriptions
400 Bad request CUSTOMER_NOT_FOUND

The provided customer id can't be found in the merchant's customers list.

 >
400 Bad request SOURCE_EXPIRED

The provided source id has expired.

 >
400 Bad request SOURCE_USED

The provided source id was already used to create a card.

 >
400 Bad request INVALID_CARD_DATA

Generic error - the provided card data is invalid.

 >
402 Payment required CARD_DECLINED_VERIFICATION_REQUIRED

The payment card was declined with a request for additional verification.

 >
403 Forbidden CARD_PROCESSING_NOT_ENABLED

The location provided in the API call is not enabled for credit card processing.

 >
402 Payment required 
{
  "errors": [
    {
      "code": "CARD_DECLINED_VERIFICATION_REQUIRED",
      "category": "PAYMENT_METHOD_ERROR"
    }
  ]
}