Docs Sign In
Docs
Square API
API Reference API Explorer Square SDKs
Web
Setup guide SDK reference
Mobile
Setup guide iOS reference Android reference
Setup guide iOS reference Android reference
Setup guide iOS reference Android reference
Developer forums Slack community Contact support
Developer dashboard Settings
Seller dashboard Sign out
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 information for recurring payments.

Creating a customer profile typically includes the following steps:

  1. The frontend collects customer information with the customer's consent.

  1. The backend packages the information as a CreateCustomer request object and sends it to the CreateCustomer endpoint.

  1. Square processes the request:

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

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

  1. The frontend displays results for the customer.

    process-flow-1

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

Warning

Using the Customers API to manage credit and debit cards on file is deprecated. To save a card on file, you should use CreateCard in the Cards API. For more information, see Cards API Overview or Migrate to the Cards API and Gift Cards API.

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

Important

Your application must use the Web Payments SDK or In-App Payments SDK to collect card information.

Saving a card on file typically includes the following steps:

  1. The frontend uses the Web Payments SDK or In-App Payments SDK to collect card information and generate a secure payment token. The frontend should also collect contact information for the customer at this point. Customers must consent to saving their card and contact information.

  1. The backend packages the contact information as a CreateCustomer request object and sends it to the CreateCustomer endpoint.

  1. Square returns a Customer object with an id. This value is used as the customer_id in the CreatePayment request.

  1. The backend packages a CreateCustomerCard request object containing the customer_id and card_nonce and sends it to the CreateCustomerCard endpoint (deprecated). The card_nonce value is the payment token generated in step 1.

  1. Square returns a CustomerCard object with an id. This value is used as the customer_card_id in the CreatePayment request.

  1. The backend packages a CreatePayment request object with the customer_card_id and a customer_id and sends it to the CreatePayment endpoint.

    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.

    process-flow-cof

Related topics Permalink Get a link to this section