Learn how to create a new card on file in a Square account using a Payment ID as a source.
Cards API

Create a Card on File from a Payment ID

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.

Important

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 payment

Call the CreatePayments endpoint to request a new Payment object.

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 200,
      "currency": "USD"
    },
    "source_id": "{PAYMENT_TOKEN}",
    "autocomplete": true,
    "location_id": "XK3DBG77NJBFX",
    "reference_id": "123456"
  }'
Try in API Explorer

If the payment succeeds, your application gets a response from the Payments API like the following example:

  • 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
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
{
  "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"
    }
   }
}

The Payment id field value is used in step 3.

Link to section
Step 2: Create a customer

Create a new customer to associate with the card you create in step 3.

The required OAuth scope is CUSTOMERS_WRITE.

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-03-15' \
  -H 'Authorization: Bearer {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"
  }'
Try in API Explorer

The Customers API returns the following response:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
{
  "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
    }
  }
}

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

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

Call the CreateCard endpoint, setting the value of the source_id field to the payment ID in the step 1 Payment response object and the customer_id value from the step 2 Customer response object.

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-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "source_id": "Dv9xlBgSgVB8i6eT0imRYFjcrOaZY",
    "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"
    }
  }'
Try in API Explorer

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

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.

Link to section
Related topics

On this page