Contas e Subcontas

Criar Proposta PF

POST/v1/proposals

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

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

Autenticação

bearerAuthorizationstring · header · obrigatório

Envie no header:

Authorization: Bearer {{token}}

Envia ou atualiza o formulário de abertura de conta para pessoa física, incluindo dados pessoais e documentos.

Criar/atualizar proposta (Pessoa Física)

documentNumber com 11 dígitos determina PF. financialDetails é obrigatório para finalizar (status: FINISHED); sem ele retorna UNFINISHED.

Campo	Obrig.	Tipo	Descrição
`documentNumber`	✅	string	CPF 11 dígitos
`fullName`	✅	string	Nome completo
`phoneNumber`	✅	string	E.164
`email`	✅	string	email válido
`motherName`	✅	string	Nome da mãe
`birthDate`	✅	string	YYYY-MM-DD
`isPoliticallyExposedPerson`	✅	boolean	PEP
`address.*`	✅	object	CEP, logradouro, número, bairro, cidade, UF
`financialDetails.*`	✅*	object	renda, profissão, patrimônio (obrig. p/ finalizar)
`webhookUrl`	❌	string	Notificações de onboarding

Body

application/json

Content-Type:application/json

{
  "documentNumber": "12345678901",
  "fullName": "João da Silva",
  "phoneNumber": "+5511999998888",
  "email": "joao@email.com",
  "motherName": "Maria da Silva",
  "birthDate": "1990-01-15",
  "isPoliticallyExposedPerson": false,
  "socialName": null,
  "address": {
    "postalCode": "01310100",
    "street": "Av. Paulista",
    "number": "1000",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "addressComplement": "Apto 52"
  },
  "financialDetails": {
    "declaredIncome": "5000.00",
    "occupation": "Desenvolvedor",
    "netWorth": "50000.00"
  },
  "webhookUrl": "https://meusite.com/webhook"
}

Schema

Field	Type	Required	Description
documentNumber	string	-	-
fullName	string	-	-
phoneNumber	string	-	-
email	string	-	-
motherName	string	-	-
birthDate	string	-	-
isPoliticallyExposedPerson	boolean	-	-
socialName	object	-	-
address	object	-	-
financialDetails	object	-	Ver referência
webhookUrl	string	-	-

Headers

Name	Type	Value	Required
Content-Type	-	application/json	Optional

← Anterior

Gerar Token

Criar Proposta PJ

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

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "documentNumber": "12345678901",
  "fullName": "João da Silva",
  "phoneNumber": "+5511999998888",
  "email": "joao@email.com",
  "motherName": "Maria da Silva",
  "birthDate": "1990-01-15",
  "isPoliticallyExposedPerson": false,
  "socialName": null,
  "address": {
    "postalCode": "01310100",
    "street": "Av. Paulista",
    "number": "1000",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "addressComplement": "Apto 52"
  },
  "financialDetails": {
    "declaredIncome": "5000.00",
    "occupation": "Desenvolvedor",
    "netWorth": "50000.00"
  },
  "webhookUrl": "https://meusite.com/webhook"
})
};

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

Response Examples

200200 FINISHED

{
  "status": "FINISHED",
  "formId": "form_xxx",
  "sendStatus": "SENT",
  "proposalId": "prop_xxx"
}

200200 UNFINISHED

{
  "status": "UNFINISHED",
  "formId": "form_xxx",
  "pendingFields": [
    "financialDetails.declaredIncome"
  ]
}

400400

{
  "code": "INVALID_DOCUMENT",
  "message": "CPF inválido"
}

← Anterior

Gerar Token

Criar Proposta PJ