Clientes

Criar Cliente

Cadastra um cliente na sua conta a partir do CPF/CNPJ, com endereço opcional.

O documento é a chave do cliente dentro da conta e não pode ser alterado depois. Por padrão, se já existir um cliente com o mesmo documento, a API devolve 200 com o cadastro existente em vez de duplicar. Envie upsert: true para que a tentativa de recadastrar retorne erro 400 (CUSTOMER_ALREADY_EXISTS).

Quando o endereço é informado, o código IBGE do município (cityCode) é resolvido automaticamente a partir do CEP — necessário para emissão de NFS-e.

Case de uso:

Como plataforma, quero cadastrar meus clientes junto com o endereço de cobrança, para depois gerar assinaturas e cobranças sem redigitar os dados a cada venda.

POST/v1/customers

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

Authorizations

bearer

Authorization

string · header · required

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

customers/write

Body

application/json

Content-Type:application/json

{
  "name": "Alexandre Souza",
  "document": "11144477735",
  "phone": "5511987654321",
  "email": "alexandre@exemplo.com.br",
  "upsert": false,
  "address": {
    "zipCode": "01310100",
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Sala 5",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  }
}

Schema

namestringRequired

Nome completo ou razão social

documentstringRequired

Regra:^\d{11}$|^\d{14}$

CPF (11) ou CNPJ (14), apenas dígitos

phonestringRequired

E.164 com DDI 55

emailstringOptional

upsertbooleanOptional

true retorna erro 400 se o documento já existir (default false)

addressobjectOptional

← Anterior

Consultar status do estorno

Listar Clientes

const url = 'https://sandbox.validapay.com.br/v1/customers';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "name": "Alexandre Souza",
  "document": "11144477735",
  "phone": "5511987654321",
  "email": "alexandre@exemplo.com.br",
  "upsert": false,
  "address": {
    "zipCode": "01310100",
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Sala 5",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  }
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

201201

{
  "customer": {
    "customerId": "cus_xxx",
    "id": "cus_xxx",
    "name": "Alexandre Souza",
    "document": "11144477735",
    "email": "alexandre@exemplo.com.br",
    "phone": "5511987654321",
    "accountId": "460851686",
    "status": "ACTIVE",
    "createdAt": "2026-08-28T12:00:00.000Z"
  }
}

200200

{
  "customer": {
    "customerId": "cus_xxx",
    "document": "11144477735",
    "name": "Alexandre Souza"
  }
}

400400

{
    "error": {
        "message": "Já existe um cliente cadastrado com este documento",
        "code": "CUSTOMER_ALREADY_EXISTS",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

← Anterior

Consultar status do estorno

Listar Clientes