Cards API

Create a Card on File and a Payment

This procedure is used when your Square account is a seller 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 Permalink Get a link to this section

Before saving a card on file, you need to get a valid one-time use payment token (also known as a nonce), which represents a buyer's payment card used in a charge transaction. Use the Web Payments SDK or In-App Payments SDK to generate the payment token.

Both of the two Cards API examples in this topic require their own unique token.

Important

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

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

Step 1: Create a customer record in the target seller account Permalink Get a link to this section

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: 2021-07-21' \
  -H 'Authorization: Bearer {SELLER_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "Amelia.Earhart@example.com",
    "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:

{
  "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": "Amelia.Earhart@example.com",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "THIRD_PARTY"
  }
}

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

Step 2: Save a card on file in the seller Square account Permalink Get a link to this section

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: 2021-07-21' \
  -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:

{
  "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
  }
}

Step 3: Create a payment using the card on file Permalink Get a link to this section

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: 2021-07-21' \
  -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"
  }'

Related topics Permalink Get a link to this section