Customers API

Customers API Workflows

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 payments for recurring payments.

Creating a customer profile typically includes the following steps:

  1. The frontend collects customer information with customer consent.

  2. The 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. The 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. You should 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 is 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 is 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 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.

Related topics Permalink Get a link to this section