Cards API

Create a Card on File and a Payment

This procedure is used when your Square account is not a developer account and your application uses only a seller account access token. The customer, card, and payment are all created in a seller account.

Get a payment token
Step 1: Create a customer record in the target seller account
Step 2: Save a card on file in the seller Square account
Step 3: Create a payment using the card on file
Related topics

Link to section
Get a payment token

Before saving a card on file, you need to get a valid one-time-use payment token, which represents a buyer's payment card. Use the Web Payments SDK or In-App Payments SDK to generate the payment token. You do not need to charge the buyer's card in order to save it. The payment token can be used to save a card on file, create a payment, or both.

The two Cards API examples in this topic require their own unique token.

The postal code entered in the payment card form must match the postal code used in each CreateCard call in this topic.

When you enter card information from Sandbox Test Values, be sure to enter the postal code 10003 to match the values used in this topic.

Link to section
Step 1: Create a customer record in the target seller account

Use the CreateCustomer endpoint to create a new customer in the seller Square account using an OAuth token generated for the seller.

The following example CreateCustomer request is made with an access token from the seller Square account:

Create Customer

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

curl https://connect.squareupsandbox.com/v2/customers \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {PERSONAL_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "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",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "a customer"
  }'

The Customers API returns the following response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "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]",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "THIRD_PARTY"
  }
}

The id field in the response is used in the following step.

Link to section
Step 2: Save a card on file in the seller Square account

Call the CreateCard endpoint with a card token and idempotency key using an OAuth token from the seller Square account.

The following example uses the customer_id value of Q6VKKKGW8GWQNEYMDRMV01QMK8 returned in the response in the previous step:

Create Card

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

curl https://connect.squareupsandbox.com/v2/cards \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {SELLER_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "source_id": "{CARD_TOKEN}",
    "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": "Q6VKKKGW8GWQNEYMDRMV01QMK8",
      "reference_id": "user-id-1"
    }
  }'

The Cards API returns the following response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "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"
    },
    "bin": "411111",
    "card_brand": "VISA",
    "card_type": "CREDIT",
    "cardholder_name": "Amelia Earhart",
    "customer_id": "Q6VKKKGW8GWQNEYMDRMV01QMK8",
    "enabled": true,
    "exp_month": 11,
    "exp_year": 2024,
    "last_4": "1111",
    "prepaid_type": "NOT_PREPAID",
    "reference_id": "user-id-1",
    "version": 1
  }
}

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.

Link to section
Step 3: Create a payment using the card on file

Use CreatePayment for a new payment in the seller account.

The access token that you use in any Square API call determines which Square account the call applies to.

This is an optional step that you do only if you want to take a payment with the card that was just stored on file. If you do not want to take a payment, skip this step. The customer payment card is already stored on file.

Create a new payment in the seller account where the source_id is the ID of the newly saved card on file from step 2 and the customer_id from step 1.

Create Payment

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "4935a656-a929-4792-b97c-8848be85c27c",
    "amount_money": {
      "amount": 200,
      "currency": "USD"
    },
    "source_id": "ccof:uIbfJXhXETSP197M3GB",
    "autocomplete": true,
    "customer_id": "Q6VKKKGW8GWQNEYMDRMV01QMK8",
    "location_id": "XK3DBG77NJBFX",
    "reference_id": "123456"
  }'

Link to section
Related topics

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Create a Card on File and a Payment

On this page

Link to section
Get a payment token

Important

Link to section
Step 1: Create a customer record in the target seller account

Link to section
Step 2: Save a card on file in the seller Square account

Important

Link to section
Step 3: Create a payment using the card on file

Did you know?

Link to section
Related topics

On this page

Docs

Create a Card on File and a Payment

On this page

Link to section Get a payment token

Important

Link to section Step 1: Create a customer record in the target seller account

Link to section Step 2: Save a card on file in the seller Square account

Important

Link to section Step 3: Create a payment using the card on file

Did you know?

Link to section Related topics

On this page

Link to section
Get a payment token

Link to section
Step 1: Create a customer record in the target seller account

Link to section
Step 2: Save a card on file in the seller Square account

Link to section
Step 3: Create a payment using the card on file

Link to section
Related topics