Criar Cliente
POST/v2/payment-customers
Cadastra o cliente pagador (PaymentCustomer) para receber assinaturas e cartões tokenizados.
Cabeçalhos (Headers)
| Cabeçalho | Valor | Obrigatório | Descrição |
|---|---|---|---|
Authorization | Bearer <token> | Sim | Token JWT Bearer autenticado |
Content-Type | application/json | Sim | Tipo de mídia |
Idempotency-Key | <guid_ou_string> | Sim | Chave de idempotência |
Parâmetros
Exemplo de requisição
{
"externalId": "CLI-9921",
"documentType": "PF",
"documentNumber": "11122233344",
"name": "Carlos Eduardo",
"email": "[email protected]",
"phoneNumber": "1133334444",
"mobilePhoneNumber": "11988887777",
"addressStreet": "Avenida Paulista",
"addressNumber": "1000",
"addressComplement": "Apto 101",
"addressNeighborhood": "Bela Vista",
"addressCity": "São Paulo",
"addressState": "SP",
"addressZipCode": "01310100"
}Resposta (201 Created)
Exemplo de resposta
{
"id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"externalId": "CLI-9921",
"documentType": "PF",
"documentNumber": "***.222.333-**",
"name": "Carlos Eduardo",
"email": "c***@example.com",
"status": "ACTIVE",
"createdOn": "2026-09-09T10:05:00Z"
}Próximos Passos
Após criar o cliente, utilize o id retornado (PaymentCustomerId) para:
- Vincular Cartão de Crédito: Armazene e vincule o cartão no cofre seguro em Vincular Meio de Pagamento informando
/v2/payment-customers/{customerId}/payment-methods. - Criar Assinatura: Contrate um plano para este cliente em Criar Assinatura.
- Iniciar Checkout: Pré-vincule este cliente ao gerar uma sessão em Criar Sessão de Checkout.
- Consultar Histórico: Acompanhe o cadastro em Consultar Cliente e suas faturas em Listar Faturas do Cliente.
Erros
As respostas de erro conhecidas estão abaixo. Os retornos observados em homologação estão identificados separadamente dos exemplos documentados; as respostas podem variar conforme o ambiente e a configuração.
Ver validações observadas em homologação
Requisição com corpo JSON vazio ou identificador sintético. O retorno abaixo mostra a validação realizada em homologação.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"Idempotency-Key": [
"The key field is required."
]
},
"traceId": "00-7af13906a7c9429ebe3050115b3f72b2-95bf973d7e5429b8-00"
}Observado em homologação
Requisição com o header Idempotency-Key e corpo JSON vazio; os identificadores na rota são sintéticos.
[
{
"tag": "DocumentType",
"description": "'Document Type' deve ser informado."
},
{
"tag": "DocumentNumber",
"description": "'Document Number' deve ser informado."
},
{
"tag": "Name",
"description": "'Name' deve ser informado."
}
]Campos da resposta de erro
A tabela reúne os campos presentes nos exemplos acima. Uma resposta HTTP sem corpo não inclui esses campos.
