Create customer card
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.
Name | Description |
---|---|
customer_
Required
|
The Square ID of the customer profile the card is linked to. |
Name | Description |
---|---|
card_
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 information for the card on file. NOTE: If a billing address is provided in the request, the
|
cardholder_
|
The full name printed on the credit card. |
verification_
|
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. |
Response Fields
Name | Description |
---|---|
errors
|
Any errors that occurred during the request. |
card
|
The created card on file. |
Examples
- cURL
- Ruby
- Python
- C#
- Java
- PHP
- Node.js
curl https://connect.squareup.com/v2/customers/customer_id0/cards \
-X POST \
-H 'Square-Version: 2023-01-19' \
-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_ The card issuer declined the request because the card is expired. |
> |
400 Bad request |
CARD_ The provided card token (nonce) has expired. |
> |
400 Bad request |
CARD_ The provided card token (nonce) was already used to process the payment or refund. |
> |
400 Bad request |
INVALID_ The credit card cannot be validated based on the provided details. |
> |
400 Bad request |
INVALID_ Generic error - the provided card data is invalid. |
> |
400 Bad request |
INVALID_ The expiration date for the payment card is invalid. For example, it indicates a date in the past. |
> |
400 Bad request |
UNSUPPORTED_ The entry method for the credit card (swipe, dip, tap) is not supported. |
> |
402 Payment required |
VERIFY_ The AVS could not be verified. |
> |
402 Payment required |
VERIFY_ The CVV could not be verified. |
> |
403 Forbidden |
CARD_ The location provided in the API call is not enabled for credit card processing. |
> |
{
"errors": [
{
"code": "CARD_EXPIRED",
"category": "PAYMENT_METHOD_ERROR"
}
]
}