Learn how to create a new card on file in a Square account using a payment ID as a source.
Applies to: Cards API | Customers API | Payments API
You need a valid access token - Access tokens determine the Square APIs you can call and the Square account that the call applies to. The steps in this topic call Square APIs in the Square Sandbox, so you can use your Sandbox access token in the requests. Square recommends testing with Sandbox credentials when possible. To call Square APIs in the production environment, change the base URL to https://connect.squareup.com and use production credentials.
Applications that use OAuth access tokens require PAYMENTS_WRITE and CUSTOMERS_WRITE permissions to perform these steps.
You need a payment token - Payment tokens are generated by the Web Payments SDK or In-App Payments SDK using card information entered by buyers. To learn more, see Get a payment token.
Before saving a card on file, you need to get a valid single-use payment token that represents a buyer's payment card using the Web Payments SDK or In-App Payments SDK. You don't need to charge the buyer's card to save it. The payment token can be used to save a card on file, create a payment, or both.
Important
The postal code entered in the SDK's payment card form must match the postal code used in the CreateCard request.
You can use Sandbox test card information to generate a test payment token for the following steps. Be sure to enter the postal code 10003 in the payment card form so it matches the example values used.
Call the CreatePayment endpoint to create a payment. Set source_id to the single-source payment token you generated for the card using the Web Payments SDK or In-App Payments SDK. Payment tokens are prefixed by cnon (for example, cnon:CBASEAZOKxw_kwAJQu3FI7dIkek).
If successful, Square returns a Payment object, as shown in the following example response. Copy the payment ID so you can use it to create a card in step 3.
{
"payment": {
"id": "Dv9xlBgSgVB8i6eT0imRYFjcrOaZY",
"created_at": "2021-03-31T20:56:13.220Z",
"updated_at": "2021-03-31T20:56:13.411Z",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"status": "COMPLETED",
"delay_duration": "PT168H",
"source_type": "CARD",
"card_details": {
"status": "CAPTURED",
"card": {
"card_brand": "AMERICAN_EXPRESS",
"last_4": "6550",
"exp_month": 3,
"exp_year": 2023,
"fingerprint": "sq-1-hPdOWUYtEMft3yQ",
"card_type": "CREDIT",
"prepaid_type": "NOT_PREPAID",
"bin": "371263"
},
"entry_method": "KEYED",
"cvv_status": "CVV_ACCEPTED",
"avs_status": "AVS_ACCEPTED",
"statement_description": "SQ *DEFAULT TEST ACCOUNT",
"card_payment_timeline": {
"authorized_at": "2021-03-31T20:56:13.334Z",
"captured_at": "2021-03-31T20:56:13.411Z"
}
},
"location_id": "VJN4XSBFTVPK9",
"total_money": {
"amount": 100,
"currency": "USD"
},
"approved_money": {
"amount": 100,
"currency": "USD"
}
}
}
Step 2: Create a customer
Call the CreateCustomer endpoint to create a customer to associate with the card.
If successful, Square returns a Customer object, as shown in the following example response. Copy the customer ID so you can use it to create a card in step 3.
{
"customer": {
"id": "Q6VKKKGW8GWQNEYMDRMV01QMK8",
"created_at": "2021-03-31T18:27:07.803Z",
"updated_at": "2021-03-31T18:27:07Z",
"given_name": "Amelia",
"family_name": "Earhart",
"email_address": "[email protected]",
"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"
},
"phone_number": "1-212-555-4240",
"note": "a customer on seller account",
"reference_id": "reference-id-1",
"preferences": {
"email_unsubscribed": false
},
"creation_source": "THIRD_PARTY",
"version": 0
}
}
Step 3: Create a card on file using the payment ID as the source
Call the CreateCard endpoint to save a card on file for the customer. Set source_id to the payment ID (from step 1) and card.customer_id to the customer ID (from step 2).
Important
Always ask customers for permission before saving their card information. For example, include a checkbox in your purchase flow that customers can select to specify that they want to save their card information for future purchases.
Linking cards on file without obtaining customer permission can result in your application being disabled without notice.
If successful, Square returns a Card object, as shown in the following example response:
{
"card": {
"id": "ccof:uIbfJXhXETSP197M3GB",
"card_brand": "VISA",
"last_4": "1111",
"exp_month": 11,
"exp_year": 2025,
"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"
},
"fingerprint": "sq-1-Fqm6frzaqEflW0CjZ0_JqJ-17rrOTHmDN9V-18Mnra8ZQ-T7zmVdE9tsDXtYKjaQrg",
"customer_id": "Q6VKKKGW8GWQNEYMDRMV01QMK8",
"merchant_id": "8QJTJCE6AZSN6",
"reference_id": "user-id-1",
"enabled": true,
"card_type": "CREDIT",
"prepaid_type": "NOT_PREPAID",
"bin": "411111",
"created_at": "2021-03-31T22:29:01Z",
"version": 1
}
}