Customers API

How It Works

A deeper look at Customers API.

Customers API

Basic process flow
Permalink Get a link to this section

The Customers API is a RESTful web service hosted on Square servers. It creates and manages customer information and card on file payment for recurring payments.

Creating a customer profile typically includes the following steps:

  1. Frontend collects customer information with customer consent.

  2. Backend packages the information as a CreateCustomer request object and sends it to the CreateCustomer endpoint.

  3. The Square server processes the request.

    • If the request succeeds — the Square server returns a Customer object.

    • If the request fails — the Square server returns an error.

  4. Frontend displays results for the customer.

process-flow-1

Process flow for cards on file
Permalink Get a link to this section

You can save a card on file for a particular customer by sending a card_nonce and customer_id to the CreateCustomerCard endpoint. You can then use the returned card ID to process payments. The Customers API, SqPaymentForm, and the CreatePayment endpoint from the Payments API work together to process card-on-file payments.

Important

Credit card information must be collected using the Square Payment Form.

Saving a card on file typically includes the following steps:

  1. The Square payment form collects card information and uses it to generate a card nonce. We recommend that you also collect customer contact information at this point with your own form.

  2. The client server packages the customer information as a CreateCustomer request object and sends it to the CreateCustomer endpoint.

  3. The Square server returns a Customer object with an id. This value will be used as the customer_id in the CreatePayment request.

  4. The client server packages a CreateCustomerCard request object containing the customer_id and the card nonce generated by the Square payment form.

  5. The Square server returns a CustomerCard object with an id. This value will be used as the customer_card_id in the CreatePayment request.

  6. The client server packages a CreatePayment request with both a customer_card_id and a customer_id instead of a card_nonce.

process-flow-2

To link a customer to a payment or to save a card on file, you must create or retrieve a customer profile before packaging the CreatePayment request. Customer profiles cannot be linked to completed payments.