Drive Growth

Customers API Setup Guide

Integrate with the Customers API to manage profiles and take payment with cards on file.

The Customers API can create and manage customer profiles and save credit card information (card on file) for future and recurring payments. This guide provides step-by-step instruction for integrating with the Customers API.

Prerequisites

Assumptions

This guide makes the following assumptions:

  • You have read the Customers API Overview, which covers general functionality of the API.
  • You can create and run websites on localhost or a development server.
  • You are familiar with HTML and PHP.
  • You are familiar with HTTPS. If this is your first time working with HTTPS, consider reading the HTTPS Guide before continuing.
  • You are familiar with JSON. If you are new to JSON, consider reading the JSON Getting Started Guide on Codular before continuing.

Development environment assumptions

To write the sample code in this setup guide, we set up the Customers API on a website with the following characteristics. These characteristics are not required to use the Customers API.

  • The Customers API is being used as a single merchant solution. In other words, the merchant site and the Square account used to save customer records are associated with the same business. While we recommend using OAuth for authorization whenever possible, personal access tokens are are acceptable for single-merchant solutions, especially during development.
  • The merchant site uses PHP version 5.4 or later. PHP is used to provide example code but the Customers API is language agnostic and the setup steps are comparable across languages.
  • The merchant site has installed the Square Connect PHP SDK.

Step 1: Get your application credentials

We recommend using sandbox ID and locations for testing and development. To get your sandbox ID:

  1. Open your Application Dashboard.
  2. If you DO have an application you want to use for accepting online payments, click on the application.
  3. If you DO NOT have an application you want to use for accepting online payments, click New Application, enter a name for your application (e.g., "My Online Store") and click Create Application.
  4. Copy the Sandbox Access Token value on the Credentials tab of the application control panel.

Instead of a sandbox or personal access token, you can also use OAuth and the CUSTOMERS_WRITE permission. OAuth is the preferred API authorization mechanism for production applications, since it allows you to scope permissions. You can also review, renew, or revoke access at any time. Sandbox tokens and personal access tokens are appropriate for testing and development.

Step 2: Add code that collects customer information

Your eCommerce site needs a way to collect customer information. The code below is a minimal HTML form that asks customers to:

  • Provide their name, email, and physical address.
  • Provide consent to save their data in a customer profile.
  • Provide consent to save a credit card on file for future or recurring payments.

Add this code to the page where you want to collect customer information.

<!-- Sample Customer Form-->
<form action="create_customer_request.php" method="post" onsubmit="paymentFormSubmit()" >
    <h2>Save a Customer Profile</h2>
      <label>Name</label>
      <input type="text" id="name" name="name"  placeholder="Name"/>
      <label>Email</label>
      <input type="email" id="email" name="email"  placeholder="Email" required/>

    <h3> Shipping Address </h3>
      <label>Street</label>
      <input type="text" id="streetAddress1" name="streetAddress1"  placeholder="Address Line 1"/>
      <label>Street</label>
      <input type="text" id="streetAddress2" name="streetAddress2"  placeholder="Address Line 2"/>
      <label>City</label>
      <input type="text" id="city" name="city"  placeholder="City"/>
      <label>Zip</label>
      <input type="text" id="zip" name="zip"  placeholder="Zip"/>

    <!--We recommend you ask your customers for consent before saving any customer information.-->
    <p>
      <input type="checkbox" name="checkbox" value="check" required>
      Allow us to save your information to a customer profile.
    </p>

    <!--You must ask your customers for consent before saving credit card information.
    Uncomment this extra checkbox if you want to save cards on file.-->
    <!--
    <p>
      <input type="checkbox" name="checkbox" value="check" required>
      Allow us to save your credit card information for future purchases.
    </p>
    -->
    <input type="submit" id="submit" value="submit" class="btn btn-primary"/>
  </form>

To create a Customer object, you'll need to provide at least one of the following fields:

  • given_name
  • family_name
  • company_name
  • email_address
  • phone_number

Read about other available fields in the API reference for CreateCustomer.

Step 3: Add code that sends your customer information to the CreateCustomer endpoint.

  1. Create a file called create_customer_request.php in the same directory as your HTML form.
  2. In your new file, initialize the API object by filling in your personal access token from Step 1: Get your application credentials.
//Replace with your access token
$accessToken = '{REPLACE_ME}';

// Include the Square Connect API resources
require_once(__DIR__ . '/local/path/to/Square/Connect/SDK/autoload.php');

// Create and configure a new API client object
$defaultApiConfig = new \SquareConnect\Configuration();
$defaultApiConfig->setAccessToken($accessToken);

$defaultApiClient = new \SquareConnect\ApiClient($defaultApiConfig);
$customersApi = new SquareConnect\Api\CustomersApi($defaultApiClient);
  1. Pull the customer information from your HTML form and package it as a Customer object.
//Pull in fields from your HTML form
$name = $_POST['name'];
$email = $_POST['email'];
$streetAddress1 = $_POST['street_address_1'];
$streetAddress2 = $_POST['street_address_2'];
$city = $_POST['city'];
$zip = $_POST['zip'];

// Set values in your customer object.
$customer = new \SquareConnect\Model\CreateCustomerRequest();
$customer->setGivenName($name);
$customer->setEmailAddress($email);

// Put address information in an Address array.
$customer->setAddress(
    array(
        'address_line_1'=>$streetAddress1,
        'address_line_2'=>$streetAddress2,
        'city'=>$city,
        'zip'=>$zip
    )
);

  1. Send the Customer object to the CreateCustomer endpoint. For now, we'll print the raw result to the screen.
try {
    $result = $customersApi->createCustomer($customer);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling CustomersApi->createCustomer: ', $e->getMessage(), PHP_EOL;
}
  1. Serve both your HTML and PHP files on a webserver. To serve it locally, navigate to the website directory in Terminal and enter the following command:
php -S localhost:8000
  1. Visit localhost:8000 in your browser to see your HTML form. Try saving a customer. If your call is successful, the CreateCustomer endpoint will return your Customer object with three new fields:

    • A unique ID — use this value to reference this customer in other API calls.
    • A created on timestamp — the date and time this customer profile was created.
    • A last updated timestamp — the date and time this customer profile was last updated.

    Fields in the CreateCustomer response object are only set if they contain data. For example, if the CreateCustomer request does not include a phone number, the response object will not include a phone_number field.

    The CreateCustomer endpoint accepts partial addresses. For example, you can save a customer's zipcode without including their full street address. Even if you only provide a partial address, the CreateCustomer return object includes an Address object to hold the address information. If you do not explicitly set the country field in an Address object, it has the default value "ZZ"

The sample code above prints the raw response for testing purposes. The following optional steps cover some of the more interesting things you can do once you create a Customer object.

To link a Customer object to a transaction, set the customer_id field in your ChargeRequest object to a valid customer ID returned by the Customers API RetrieveCustomer endpoint.

For example:

Linking customers and transactions provides reporting and analytic benefits in the Square Dashboard. Read more about using the Transactions API.

Prev
< Customers API Overview
Next
Take payments with Square APIs >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow