PayZu GatewayClientes e cartões
Consultar clientes
Leia um cliente pelo id ou percorra os clientes da conta, do mais novo para o mais antigo.
Consulte um cliente
bash
curl https://api.sandbox.payzu.dev/v1/customers/cus_bdQT0ls1QMIXVuhngvhbwC \
-H "Authorization: Bearer SUA_CHAVE_DE_API"json
{
"id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"name": "Maria Souza",
"email": "maria@exemplo.com.br",
"phone": "11987654321",
"birthdate": "1990-05-20",
"document": "52998224725",
"document_type": "cpf",
"created_at": "2026-11-11T15:20:59.318Z",
"updated_at": "2026-11-11T15:20:59.318Z",
"address": {
"street": "Avenida Paulista",
"number": "1000",
"complement": "Sala 12",
"district": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"zip_code": "01310100",
"country": "BR"
},
"metadata": {
"internal_id": "1234"
}
}Referência: Consultar um cliente
O address fica null quando o cliente não tem endereço. O metadata fica null quando nunca foi enviado.
Liste os clientes
bash
curl "https://api.sandbox.payzu.dev/v1/customers?search=maria&limit=20" \
-H "Authorization: Bearer SUA_CHAVE_DE_API"Resposta
{
"items": [
{
"id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"name": "Maria Souza",
"email": "maria@exemplo.com.br",
"phone": "11912345678",
"birthdate": "1990-05-20",
"document": "52998224725",
"document_type": "cpf",
"created_at": "2026-11-11T15:20:59.318Z",
"updated_at": "2026-11-11T15:20:59.325Z",
"address": {
"street": "Avenida Paulista",
"number": "1000",
"complement": "Sala 14",
"district": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"zip_code": "01310100",
"country": "BR"
},
"metadata": {
"internal_id": "1234"
}
}
],
"next_cursor": null
}Referência: Listar os clientes
Cada item de items traz o cliente completo, como na consulta pelo id. Os clientes excluídos não entram na lista.
| Parâmetro | O que faz |
|---|---|
search | Procura no nome, no e-mail, no documento e no telefone. |
subscription_status | Traz os clientes com assinatura active, canceled ou incomplete. |
plan_id | Traz os clientes com assinatura nesse plano. |
created_from, created_to | Traz os clientes criados nesses dias, em AAAA-MM-DD, no fuso de São Paulo. |
cursor | Abre a página seguinte, com o next_cursor da anterior. |
limit | Clientes por página, de 1 a 100. |
Com subscription_status e plan_id juntos, os dois valem para a mesma assinatura. Parâmetro que a lista não tem é ignorado. A lista não traz total, como explica Paginação.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
| - | 404 | Cliente não encontrado para o id informado. |
O 404 vale para cliente excluído, de outra conta ou com id desconhecido. Os erros de autenticação e de validação estão no Catálogo de erros.