Subcontas ValidaPay

Eventos de Onboarding

Ao criar uma subconta (PF ou PJ), o processo de onboarding passa por diversas etapas. A cada etapa, um evento webhook é disparado para a URL configurada, permitindo que você acompanhe o progresso em tempo real.

Fluxo de Eventos

Background Check

PENDING → APPROVED

Cópia Documental

PENDING → APPROVED

Proposta

APPROVED

Conta Criada

Dados da conta

Detalhes dos Eventos

onboarding.backgroundcheck

Verificação cadastral (background check) da subconta. Esse evento é disparado duas vezes: primeiro com status PENDING (análise iniciada) e depois com o resultado (APPROVED ou REPROVED).

Status possíveis:PENDINGAPPROVEDREPROVED

Campos em data

Campo	Tipo	Descrição
`formId`	string	Identificador do formulário na ValidaPay, para consultas via API
`proposalId`	string	Identificador da proposta de criação da subconta
`documentNumber`	string	CPF ou CNPJ da subconta
`proposalType`	string	Tipo da proposta: PF ou PJ
`status`	string	Status do background check: PENDING, APPROVED ou REPROVED

Exemplo de payload

{
  "event": "onboarding.backgroundcheck",
  "timestamp": "2026-03-16T17:33:55.238Z",
  "accountId": "4231833",
  "data": {
    "formId": "4f7f7c90-1e86-4be3-ab26-ee4e3ab7dfe9",
    "proposalId": "7dd3956b-4cb0-4b78-9bc8-f2a4073d34d4",
    "documentNumber": "93246629960",
    "proposalType": "PF",
    "status": "APPROVED"
  }
}

onboarding.documentscopy

Envio e validação de documentos (cópia documental). Quando o status é PENDING, o campo url contém o link para envio dos documentos. Quando APPROVED, a etapa foi concluída.

Status possíveis:PENDINGAPPROVEDREPROVED

Campos em data

Campo	Tipo	Descrição
`formId`	string	Identificador do formulário na ValidaPay, para consultas via API
`proposalId`	string	Identificador da proposta de criação da subconta
`documentNumber`	string	CPF ou CNPJ da subconta
`proposalType`	string	Tipo da proposta: PF ou PJ
`status`	string	Status da cópia documental: PENDING, APPROVED ou REPROVED
`url`	string \| null	URL para envio dos documentos (presente apenas quando PENDING)

Exemplo de payload

{
  "event": "onboarding.documentscopy",
  "timestamp": "2026-03-16T17:34:01.937Z",
  "accountId": "4231833",
  "data": {
    "formId": "4f7f7c90-1e86-4be3-ab26-ee4e3ab7dfe9",
    "proposalId": "7dd3956b-4cb0-4b78-9bc8-f2a4073d34d4",
    "documentNumber": "93246629960",
    "proposalType": "PF",
    "status": "PENDING",
    "url": "https://…/153ece225709906db8c3656b91536f22"
  }
}

onboarding.proposal

Resultado final da proposta de criação da subconta. Quando APPROVED, a subconta foi aprovada e será criada em seguida.

Status possíveis:APPROVEDREPROVED

Campos em data

Campo	Tipo	Descrição
`formId`	string	Identificador do formulário na ValidaPay, para consultas via API
`proposalId`	string	Identificador da proposta de criação da subconta
`documentNumber`	string	CPF ou CNPJ da subconta
`proposalType`	string	Tipo da proposta: PF ou PJ
`status`	string	Status da proposta: APPROVED ou REPROVED

Exemplo de payload

{
  "event": "onboarding.proposal",
  "timestamp": "2026-03-16T17:38:56.788Z",
  "accountId": "4231833",
  "data": {
    "formId": "4f7f7c90-1e86-4be3-ab26-ee4e3ab7dfe9",
    "proposalId": "7dd3956b-4cb0-4b78-9bc8-f2a4073d34d4",
    "documentNumber": "93246629960",
    "proposalType": "PF",
    "status": "APPROVED"
  }
}

onboarding.create

Após a aprovação da proposta, a conta é efetivamente criada. Este payload contém os dados da nova subconta em data.account, o formId para consultas futuras e o status CONFIRMED.

Status possíveis:CONFIRMED

Campos em data

Campo	Tipo	Descrição
`formId`	string	Identificador do formulário para consultas via API
`proposalId`	string	Identificador da proposta de criação da subconta
`documentNumber`	string	CPF ou CNPJ da subconta
`status`	string	Status da criação da conta: CONFIRMED
`account.number`	string	Número da conta criada
`account.branch`	string	Agência da conta
`account.name`	string	Nome do titular da subconta

Exemplo de payload

{
  "event": "onboarding.create",
  "timestamp": "2026-03-16T14:38:58.817Z",
  "accountId": "4231833",
  "data": {
    "formId": "4f7f7c90-1e86-4be3-ab26-ee4e3ab7dfe9",
    "proposalId": "7dd3956b-4cb0-4b78-9bc8-f2a4073d34d4",
    "documentNumber": "93246629960",
    "status": "CONFIRMED",
    "account": {
      "number": "4971289",
      "branch": "0001",
      "name": "BLAISE PASCAL"
    }
  }
}

Eventos do MED

O MED é o Mecanismo Especial de Devolução do Pix, o processo do Banco Central para contestação de transações. Estes eventos avisam sobre bloqueios de saldo e devoluções determinadas por ele. Todos trazem event, timestamp, accountId, caseId e originalEndToEndId, mais os campos de cada etapa.

Evento	Quando	Campos adicionais
`med.infraction.updated`	Infração do MED registrada ou atualizada	infractionId, status, analysisResult, chargeId
`med.balance.blocked`	Saldo bloqueado por ordem do MED	blockId, infractionId, blockedAmount, blockStatus, balanceAfter, blockedBalanceAfter
`med.balance.unblocked`	Saldo desbloqueado	blockId, infractionId, unblockedAmount, balanceAfter, blockedBalanceAfter
`med.refund.opened`	Processo de devolução do MED aberto	medRefundId, refundAmount
`med.refund.closed`	Processo de devolução do MED encerrado	medRefundId, refundAmount, analysisResult, returnIdentification, chargeId, balanceResult

Exemplo de payload

{
  "event": "med.balance.blocked",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountId": "4231833",
  "caseId": "med_1786746837248_gsoosg37y",
  "blockId": "b4b0c9de-2f18-4a55-9f31-7c0d9a1e2b34",
  "infractionId": "3f8c1d92-5b21-4e77-9a0c-1f2b3c4d5e6f",
  "originalEndToEndId": "E18236120202608142232s0290d93572",
  "blockedAmount": 150,
  "blockStatus": "BLOCKED",
  "balanceAfter": 320.55,
  "blockedBalanceAfter": 150
}

balanceAfter é o saldo livre depois da operação e blockedBalanceAfter, o total retido. Um bloqueio pode fazer um saque falhar mesmo com saldo aparente — trate med.balance.blocked na sua conciliação. Os eventos med.* só podem ser assinados via POST /v1/users/webhooks; a tela de webhooks do painel ainda não os lista.

Observações importantes

Os eventos são enviados via webhook para a URL configurada no painel em app.validapay.com.br/integracao/webhooks
O campo accountId no nível raiz identifica a conta master que criou a subconta — eventos de onboarding e MED usam accountId, não accountNumber
O proposalId é o mesmo em todos os eventos de uma mesma subconta
Quando onboarding.documentscopy retorna com status PENDING, o campo url contém o link para envio da documentação
O payload final de conta criada retorna o formId, necessário para consultar o status da subconta via API