Payments

Customers

A customer is the person or company that pays you. Attach customers to charges and subscriptions to keep a payment history per buyer.

On this page

Customers group payments by buyer. You can create them yourself through the API, or let the checkout create them: when a buyer pays without a customer_id, KrokoPay matches their email to an existing customer or creates a new one. Either way, every charge, refund and subscription of that buyer shows up under one record in the dashboard.

The customer object

Attributes

idstring: Unique identifier, prefixed with cus_.
objectstring: Always customer.
namestring: Full name or company name.
emailstring: Used for receipts and to match the buyer at the checkout (case-insensitive).
phonestring | null: Phone number in international format.
documentstring | null: CPF or CNPJ, always returned masked. See Tax ids.
created_atstring: ISO 8601 timestamp.

A customerJSON

{  "id": "cus_8Hq2LmZr4TxN1a",  "object": "customer",  "name": "Ana Beatriz Souza",  "email": "ana.souza@example.com",  "phone": "+55 11 5555-0101",  "document": "•••.•••.•••-00",  "created_at": "2026-10-28T13:04:11.000Z"}

Create a customer

POST/v1/customers

Create the customer when the buyer signs up in your product, then reuse the id for every charge. Only name and email are required.

Body parameters

namestringRequired: Full name or company name.
emailstringRequired: A valid email address. In tests, use @example.com.
phonestringOptional: Optional phone number.
documentstringOptional: Optional CPF (11 digits) or CNPJ (14 digits), with or without punctuation.

Name and email only

curl -X POST https://api.krokopay.app/v1/customers \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Content-Type: application/json" \  -d '{    "name": "Ana Beatriz Souza",    "email": "ana.souza@example.com"  }'

With phone and document

curl -X POST https://api.krokopay.app/v1/customers \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Idempotency-Key: customer_ana_souza" \  -H "Content-Type: application/json" \  -d '{    "name": "Ana Beatriz Souza",    "email": "ana.souza@example.com",    "phone": "+55 11 5555-0101",    "document": "000.000.001-00"  }'

Warning: Avoid duplicates

Look the buyer up in your own database before creating, and send an Idempotency-Key derived from your user id, so a retried request does not create a second customer. See Idempotency.

Retrieve a customer

GET/v1/customers/{id}

Retrieve a customer

curl https://api.krokopay.app/v1/customers/cus_8Hq2LmZr4TxN1a \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b"

List customers

GET/v1/customers

Query parameters

limitintegerOptional: How many customers to return, newest first. The maximum is to be defined.

List customers

curl https://api.krokopay.app/v1/customers?limit=20 \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b"

Search by email and cursor-based pagination are to be defined in the proposal. Keep the cus_… id next to your own user record instead of searching for it.

Update a customer

POST/v1/customers/{id}

Send only the fields you want to change: name, email, phone or document. Fields you leave out keep their value.

Change the phone number

curl -X POST https://api.krokopay.app/v1/customers/cus_8Hq2LmZr4TxN1a \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Content-Type: application/json" \  -d '{    "phone": "+55 11 5555-0199"  }'

Attach customers to charges

Pass customer_id when you create a charge. The charge appears in the customer's history, and the checkout already knows who is paying.

A charge for a known customer

curl -X POST https://api.krokopay.app/v1/charges \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Idempotency-Key: order_1043" \  -H "Content-Type: application/json" \  -d '{    "amount": 49700,    "currency": "BRL",    "description": "Curso Identidade Visual do Zero",    "customer_id": "cus_8Hq2LmZr4TxN1a",    "methods": [      "pix"    ]  }'

With customer_id: the charge is linked to that customer from the start.
Without customer_id: the checkout asks for name and email. On payment, the buyer is matched to an existing customer by email (case-insensitive), or a new customer is created, and the charge's customer_id is filled in.
Subscriptions always belong to a customer: customer_id is required when you create a subscription.

Tax ids (CPF and CNPJ)

The document field holds a Brazilian tax id: a CPF for people (11 digits) or a CNPJ for companies (14 digits). You may send it formatted or as digits only.

You send	The API returns
`000.000.001-00` (CPF)	`•••.•••.•••-00`
`00000000000100` (CNPJ)	`••.•••.•••/••••-00`
nothing	`null`

Warning: Use only fictional test values

In the test environment, never send a real person's CPF or company's CNPJ. Use clearly fictional values such as 000.000.001-00. Responses keep only the last two digits, so do not rely on the API to give the full document back: if you need it, store it yourself under your own data protection rules.

Creating charges: charge a customer once.
Subscriptions: charge a customer every period.
Errors: validation errors such as an invalid email.

The customer object

Create a customer

Retrieve a customer

List customers

Update a customer

Attach customers to charges

Tax ids (CPF and CNPJ)

Related