Clientes

Atualizar Cliente

Atualiza os dados de um cliente. Envie apenas os campos que deseja alterar.

O documento não pode ser alterado: enviar um CPF/CNPJ diferente do atual retorna erro 400 (DOCUMENT_UPDATE_NOT_ALLOWED). Quando o endereço é enviado, ele substitui o endereço padrão do cliente.

Case de uso:

Como plataforma, quero atualizar o e-mail e o telefone de um cliente que mudou de contato, sem recriar o cadastro.

PATCH/v1/customers/:customerId
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

Path Parameters

NameTypeRequiredDescription
customerIdstringRequiredCustomerid

Body

application/json

Content-Type:application/json
{
  "name": "Alexandre Souza Silva",
  "email": "novo@exemplo.com.br",
  "additionalEmails": ["financeiro@exemplo.com.br"],
  "phone": "5511987654321",
  "address": {
    "zipCode": "01310100",
    "street": "Avenida Paulista",
    "number": "2000",
    "complement": "Andar 3",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  }
}

Schema

namestringOptional
emailstringOptional
additionalEmails[1]array
phonestringOptional

E.164 com DDI 55

addressobjectOptional

substitui o endereço padrão

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

const options = {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "name": "Alexandre Souza Silva",
  "email": "novo@exemplo.com.br",
  "additionalEmails": ["financeiro@exemplo.com.br"],
  "phone": "5511987654321",
  "address": {
    "zipCode": "01310100",
    "street": "Avenida Paulista",
    "number": "2000",
    "complement": "Andar 3",
    "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

200200
{
  "customer": {
    "customerId": "cus_xxx",
    "name": "Alexandre Souza Silva",
    "email": "novo@exemplo.com.br",
    "phone": "5511987654321"
  }
}
400400
{
    "error": {
        "message": "O documento do cliente não pode ser alterado",
        "code": "DOCUMENT_UPDATE_NOT_ALLOWED",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

← Anterior

Detalhar Cliente

Próximo →

Remover Cliente