PayZu GatewayClientes e cartões
Cadastrar um cliente
O cadastro retorna o id que identifica o cliente nas faturas e nas assinaturas.
Envie os dados do cliente
bash
curl -X POST https://api.sandbox.payzu.dev/v1/customers \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b1e7c2a-8d4f-4a3b-9e6c-2f1a0b9c8d7e" \
-d '{
"name": "Maria Souza",
"email": "maria@exemplo.com.br",
"phone": "11987654321",
"birthdate": "1990-05-20",
"document": "52998224725",
"document_type": "cpf",
"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" }
}'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: Criar um cliente
O documento de um cliente excluído reativa esse cliente.
A resposta é 201 com o mesmo id. Os campos enviados substituem os gravados, o endereço gravado fica quando address não vem, e os cartões salvos não voltam.
Campos
| Campo | Regra | Obrigatório |
|---|---|---|
name | De 1 a 120 caracteres. | Sim |
email | E-mail válido. | Sim |
document | CPF ou CNPJ válido, único na conta. Só os dígitos são guardados. | Sim |
document_type | cpf ou cnpj. | Sim |
phone | DDD e número, com 11 dígitos. | Não |
birthdate | Data no formato AAAA-MM-DD, até o dia de hoje. | Não |
address | O endereço do cliente, que vai com a cobrança no cartão. Os campos estão na aba Endereço. | Não |
metadata | Dados do seu sistema, como explica Metadados. | Não |
| Campo | Regra | Obrigatório |
|---|---|---|
street | De 1 a 54 caracteres. | Sim |
district | De 1 a 45 caracteres. | Sim |
city | De 1 a 50 caracteres. | Sim |
state | A UF, com 2 letras. | Sim |
zip_code | 8 dígitos, sem hífen. | Sim |
number | Até 5 caracteres. | Não |
complement | Até 14 caracteres. | Não |
country | 2 letras. Sem o campo, vale BR. | Não |
Campo fora destas tabelas, na raiz ou em address, responde 400. A Idempotency-Key é opcional: com ela, repetir a mesma chamada em até 24 horas retorna a primeira resposta. Veja Idempotência.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ700 | 409 | Já existe um cliente com este documento. |
Os erros de autenticação, de idempotência e de validação estão no Catálogo de erros.