Customers API Workflows
Basic process flow
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:
The frontend collects customer information with customer consent.
The backend packages the information as a
CreateCustomer
request object and sends it to theCreateCustomer
endpoint.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.
The frontend displays results for the customer.
Process flow for cards on file
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:
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.
The client server packages the customer information as a
CreateCustomer
request object and sends it to theCreateCustomer
endpoint.The Square server returns a
Customer
object with anid
. This value is used as thecustomer_id
in theCreatePayment
request.The client server packages a
CreateCustomerCard
request object containing thecustomer_id
and the card nonce generated by the Square payment form.The Square server returns a
CustomerCard
object with anid
. This value is used as thecustomer_card_id
in theCreatePayment
request.The client server packages a
CreatePayment request
with both acustomer_card_id
and acustomer_id
instead of acard_nonce
.
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.