API Explorer

You are viewing an old version of the API

All Versions

Create card

POST /v2/cards

Adds a card on file to an existing merchant.

Open in API Reference

Access Tokens Sign in to populate your access tokens from the developer dashboard Sign In

Body

card

Payment details associated with the card to be stored.

Card

billing_address

The billing address for this card.

Address

address_line_1

The first line of the address.

Fields that start with address_line provide the address's most specific details, like street number, street name, and building name. They do not provide less specific details like city, state/province, or country (these details are provided in other fields).

string

address_line_2

The second line of the address, if any.

string

address_line_3

The third line of the address, if any.

string

administrative_district_level_1

A civil entity within the address's country. In the US, this is the state. For a full list of field meanings by country, see Working with Addresses.

string

administrative_district_level_2

A civil entity within the address's administrative_district_level_1. In the US, this is the county.

string

administrative_district_level_3

A civil entity within the address's administrative_district_level_2, if any.

string

country

The address's country, in the two-letter format of ISO 3166. For example, US or FR.

string

Select country

US United States of America

first_name

Optional first name when it's representing recipient.

string

last_name

Optional last name when it's representing recipient.

string

locality

The city or town of the address. For a full list of field meanings by country, see Working with Addresses.

string

postal_code

The address's postal code. For a full list of field meanings by country, see Working with Addresses.

string

sublocality

A civil region within the address's locality, if any.

string

sublocality_2

A civil region within the address's sublocality, if any.

string

sublocality_3

A civil region within the address's sublocality_2, if any.

string

cardholder_name

The name of the cardholder.

Max Length 96

string

customer_id

Required The ID of a customer created using the Customers API to be associated with the card.

string

exp_month

The expiration month of the associated card as an integer between 1 and 12.

integer

exp_year

The four-digit year of the card's expiration date.

integer

reference_id

An optional user-defined reference ID that associates this card with another entity in an external system. For example, a customer ID from an external customer management system.

Max Length 128

string

version

Current version number of the card. Increments with each card update. Requests to update an existing Card object will be rejected unless the version in the request matches the current version for the Card.

integer

idempotency_key

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

string

source_id

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

string

Sandbox Values

No Results Clear field to see options

verification_token

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.

string

You are viewing an old version of the API

All Versions

Request

cURL

Response

// No response received yet.

Thanks for the feedback. For more help, check out our support resources.

Developer Support Developer Forums

There was an error submitting feedback. Try again later.

Developer Support Developer Forums