Eventos de Conta v2

Formato enriquecido de notificação de status de conta. Inclui detalhamento por sócio (entities) e suporte ao novo status BIOMETRIC_REJECTED.

Para receber este formato, cadastre um webhook com eventType: account_holder_status.update.

Status da Conta

Status	Descrição	Ação recomendada
KYC_APPROVED	KYC aprovado	Chamar POST /activate (PAYFAC)
KYC_REPROVED	Dados do KYC rejeitados (ex: nome divergente, sócios ausentes)	Corrigir dados via PUT
BIOMETRIC_REJECTED	Verificação biométrica rejeitada (ex: selfie não reconhecida)	Solicitar nova sessão biométrica

Estrutura do Payload

Campo	Tipo	Descrição
event	String	Tipo específico do evento (account.kyc.approved, account.kyc.reproved, account.biometric.rejected)
processedAt	String (ISO 8601)	Data e hora do processamento
data.accountId	String (UUID)	ID interno da conta
data.accountType	String	Tipo da conta (business)
data.status	String	Status resultante (KYC_APPROVED, KYC_REPROVED, BIOMETRIC_REJECTED)
data.reasons	Array<String>	Códigos de motivo das análises reprovadas
data.entities	Array<Object>	Detalhamento por sócio — presente apenas quando há reprovações
data.entities[].document	String	CPF do sócio
data.entities[].analysisType	String	Tipo de análise que reprovou (kyc ou identity)
data.entities[].status	String	Status da entidade (REJECTED)
data.entities[].reasons	Array<String>	Motivos específicos da reprovação do sócio

Exemplos de Payload

KYC Aprovado

{
  "event": "account.kyc.approved",
  "processedAt": "2026-01-30T16:00:00Z",
  "data": {
    "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "accountType": "business",
    "status": "KYC_APPROVED",
    "reasons": [],
    "entities": []
  }
}

KYC Rejeitado

{
  "event": "account.kyc.reproved",
  "processedAt": "2026-01-30T16:00:00Z",
  "data": {
    "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "accountType": "business",
    "status": "KYC_REPROVED",
    "reasons": ["PARTNERS_ARE_MISSING"],
    "entities": [
      {
        "document": "12345678901",
        "analysisType": "kyc",
        "status": "REJECTED",
        "reasons": ["NAME_MISMATCH"]
      }
    ]
  }
}

Biometria Rejeitada

{
  "event": "account.biometric.rejected",
  "processedAt": "2026-01-30T16:00:00Z",
  "data": {
    "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "accountType": "business",
    "status": "BIOMETRIC_REJECTED",
    "reasons": ["FACE_MISMATCH"],
    "entities": [
      {
        "document": "12345678901",
        "analysisType": "identity",
        "status": "REJECTED",
        "reasons": ["FACE_MISMATCH"]
      }
    ]
  }
}

Múltiplas reprovações (KYC e biometria em sócios diferentes)

Quando sócios distintos falham em análises diferentes, todas as entidades reprovadas aparecem no mesmo payload. O campo event indica o tipo primário de reprovação (KYC tem prioridade sobre biometria).

{
  "event": "account.kyc.reproved",
  "processedAt": "2026-01-30T16:00:00Z",
  "data": {
    "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "accountType": "business",
    "status": "KYC_REPROVED",
    "reasons": ["NAME_MISMATCH", "FACE_MISMATCH"],
    "entities": [
      {
        "document": "12345678901",
        "analysisType": "kyc",
        "status": "REJECTED",
        "reasons": ["NAME_MISMATCH"]
      },
      {
        "document": "98765432100",
        "analysisType": "identity",
        "status": "REJECTED",
        "reasons": ["FACE_MISMATCH"]
      }
    ]
  }
}