POST /v2/cards

Default value: "application/json"

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

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.

Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK.

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

The name of the cardholder.

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

Not currently set. Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.

The card's brand.

Indicates whether the Card is prepaid or not. The Card object includes this field only in response to Payments API calls.

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.

Unique ID for this card. Generated by Square.

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

The last 4 digits of the card number.

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.

Indicates whether or not a card can be used for payments.

The type of the card. The Card object includes this field only in response to Payments API calls.

The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API returns this field.

Represents a postal address in a country. The address format is based on an open-source library from Google. For more information, see AddressValidationMetadata. This format has dedicated fields for four address components: postal code, locality (city), administrative district (state, prefecture, or province), and sublocality (town or village). These components have dedicated fields in the Address object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons.

For the remaining address components, the Address type provides the address_line_1 and address_line_2 fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want.

Note that, in the current implementation, all other Address type fields are blank. These include address_line_3, sublocality_2, sublocality_3, administrative_district_level_2, administrative_district_level_3, first_name, last_name, and organization.

When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.

The third line of the address, if any.

Optional first name when it's representing recipient.

The address's postal code.

Optional organization name when it's representing recipient.

The second line of the address, if any.

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).

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

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

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

The city or town of the address.

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

Optional last name when it's representing recipient.

A civil entity within the address's country. In the US, this is the state.

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

The address's country, in ISO 3166-1-alpha-2 format.

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.