Cards API

Create a Shared Card on File and Make a Payment

This topic is useful for third-party applications. Store a card on file in your Square developer account and make payments with the card in other Square seller accounts. A customer and card are created in your developer account. A customer and payment are created in a seller account.

Get a payment token
Step 1: Create customer in your developer account
Step 2: Create a shared card in your Developer account
Step 3: Create a customer in the seller account
Step 4: Create a payment in the seller account using the shared card
See also

Link to section
Get a payment token

Before saving a card on file, you need to get a valid single-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 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.

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 customer in your developer account

Use the CreateCustomer endpoint to create a new customer in your developer account. Use your personal access token or an OAuth token scoped to your developer 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-08-16' \
  -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: Create a shared card in your Developer account

Call the CreateCard endpoint with a payment card token and an idempotency key. Use your personal access token or an OAuth token scoped to your own developer account.

The following example uses your Square account personal access token to create a new card on file in your Square account:

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-08-16' \
  -H 'Authorization: Bearer {PERSONAL_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "source_id": "{PAYMENT_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": 2018,
    "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 customer in the seller account

To make a payment with the card saved in step 2, your application must create a new customer in the Square seller account or find a matching customer in the seller account.

The required OAuth scope is CUSTOMERS_WRITE.

The following example request uses a seller account OAuth access token and is run when a matching customer isn't found and then creates a new customer in the seller 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-08-16' \
  -H 'Authorization: Bearer {SELLER_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 on seller account"
  }'

The Customers API allows the creation of duplicate customers.

In production, a matching customer might have already been created in the seller account when the buyer made an earlier purchase from the seller. Your application should search for an existing customer that matches the customer information you want to create. If a match is found, use that customer instead of creating a new one.

Link to section
Step 4: Create a payment in the seller account using the shared card

Use a seller account OAuth access token to create a payment in the seller account, referencing the customer_id from step 3 (the customer in the seller account) and the shared card on file as the source_id value from step 2.

The required OAuth scope is PAYMENTS_WRITE and PAYMENTS_WRITE_SHARED_ONFILE.

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-08-16' \
  -H 'Authorization: Bearer {SELLER_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 200,
      "currency": "USD"
    },
    "source_id": "ccof:uIbfJXhXETSP197M3GB",
    "autocomplete": true,
    "customer_id": "{CUSTOMER_ID_FROM_SELLER}",
    "location_id": "XK3DBG77NJBFX",
    "reference_id": "123456"
  }'

Link to section
See also

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

Docs

Create a Shared Card on File and Make a Payment

On this page

Link to section
Get a payment token

Important

Link to section
Step 1: Create customer in your developer account

Link to section
Step 2: Create a shared card in your Developer account

Important

Link to section
Step 3: Create a customer in the seller account

Did you know?

Link to section
Step 4: Create a payment in the seller account using the shared card

Link to section
See also

On this page

Docs

Create a Shared Card on File and Make a Payment

On this page

Link to section Get a payment token

Important

Link to section Step 1: Create customer in your developer account

Link to section Step 2: Create a shared card in your Developer account

Important

Link to section Step 3: Create a customer in the seller account

Did you know?

Link to section Step 4: Create a payment in the seller account using the shared card

Link to section See also

On this page

Link to section
Get a payment token

Link to section
Step 1: Create customer in your developer account

Link to section
Step 2: Create a shared card in your Developer account

Link to section
Step 3: Create a customer in the seller account

Link to section
Step 4: Create a payment in the seller account using the shared card

Link to section
See also