Skip to main content
POST
Create a customer

Authorizations

Authorization
string
header
required

Your account's secret key: Authorization: Bearer sk_test_… or sk_live_…. Server-side only.

Headers

Idempotency-Key
string

A unique key per operation (a UUID works). Retrying with the same key returns the original response.

Body

application/json
externalId
string
required

This customer's id in your own system (for example, your app's user id). Required; sending the same value again returns the same customer.

name
string | null

Customer name.

email
string | null

Customer email.

taxId
string | null

CPF or CNPJ.

pspRef
string | null

The customer's reference with the payment processor, if you already have one. Usually not needed.

metadata
object

Your own free-form JSON data. Stored on the enrollment.

Response

Customer created

The payer, at the level of your account. externalId is unique within the account.

id
string<uuid>

Customer ID. Not the enrollment ID.

externalId
string

This customer's id in your own system.

name
string | null
email
string | null
taxId
string | null

CPF or CNPJ.

phone
string | null

Contact phone, in international format as digits only, without + (for example 5511999999999). Used for contact; it does not identify the customer.

pspRef
string | null

The customer's reference with the payment processor, when there is one.

createdAt
string<date-time>