KYC

Os endpoints de KYC são chamados pelo seu backend com credenciais de parceiro (Bearer API key ou HMAC), nunca com um JWT de usuário final. Há dois modos: consulta de documento (100% via API, usando apenas o número do documento, sem imagens) e sessões completas de onboarding (a API retorna uma webViewUrl que seu app abre em um webview para o provedor capturar documento, selfie e liveness).

O KYC roda sobre um provedor configurado (BigDataCorp está ativo; ZKPassport é o alvo futuro). Se nenhum provedor estiver configurado na instância, as chamadas retornam 503 no momento da chamada.

Gate de acesso: o gate de KYC é binário. Apenas kycStatus === APPROVED libera as operações de pagamento (cash-out, cash-in). Não há níveis de KYC nem limites por nível. O gate é aplicado nas rotas de pagamento, não nas próprias rotas de KYC.

Todos os endpoints de KYC ficam sob /api/v1/users/kyc.

Consulta e verificação de documento

POST /api/v1/users/kyc/lookup retorna os dados cadastrais de um documento; POST /api/v1/users/kyc/verify retorna uma checagem de validade. Ambos recebem o mesmo corpo.

string

obrigatório

Credenciais do parceiro: Bearer sk_live_... ou o cabeçalho HMAC.

string

obrigatório

Um de CPF, CNPJ, RG, PASSPORT, SSN, DNI, CURP, RUT, CC, NIT, OTHER.

string

obrigatório

O número do documento (mínimo 3 caracteres).

string

obrigatório

Código de país ISO 3166-1 alpha-2, por exemplo BR ou US.

curl -X POST https://sandbox.brlp.io/api/v1/users/kyc/lookup \
  -H "Authorization: Bearer sk_live_<hex>" \
  -H "Content-Type: application/json" \
  -d '{ "documentType": "CPF", "documentNumber": "00000000000", "country": "BR" }'

{
  "success": true,
  "error": null,
  "data": { },
  "meta": { }
}

Um documento não encontrado retorna 404. Uma falha no provedor retorna 502.

Sessões de onboarding

Iniciar uma sessão de pessoa física (PF)

POST /api/v1/users/kyc/sessions/natural-person

string

obrigatório

O id do usuário no seu sistema (1 a 128 caracteres).

string

obrigatório

CPF (11 a 14 caracteres).

string

obrigatório

Nome legal completo.

string

obrigatório

Data de nascimento.

string

obrigatório

Nome da mãe.

string

obrigatório

E-mail de contato.

boolean

obrigatório

Se a pessoa é politicamente exposta (PEP).

string

padrão:"BR"

Código de país ISO 3166-1 alpha-2.

object

Endereço opcional (postalCode, street, number, neighborhood, city, state).

string

Telefone opcional.

curl -X POST https://sandbox.brlp.io/api/v1/users/kyc/sessions/natural-person \
  -H "Authorization: Bearer sk_live_<hex>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user-123",
    "documentNumber": "00000000000",
    "fullName": "Ana Souza",
    "birthDate": "1990-01-01",
    "motherName": "Maria Souza",
    "email": "ana@example.com",
    "isPoliticallyExposedPerson": false
  }'

{
  "success": true,
  "error": null,
  "data": {
    "sessionId": "kyc_ab12...",
    "externalUserId": "user-123",
    "type": "PF",
    "provider": "bigdatacorp",
    "status": "PENDING",
    "webViewUrl": "https://provider.example/session/...",
    "createdAt": "2026-08-03T12:00:00.000Z"
  }
}

Iniciar uma sessão de pessoa jurídica (PJ)

POST /api/v1/users/kyc/sessions/legal-person

string

obrigatório

O id da empresa no seu sistema.

string

obrigatório

CNPJ (14 a 18 caracteres).

string

obrigatório

Razão social.

string

obrigatório

Nome fantasia.

string

obrigatório

Um de MEI, EI, EIRELI, LTDA, SA, SLU.

string

obrigatório

Telefone de contato.

string

obrigatório

E-mail comercial.

object

obrigatório

O endereço da empresa (postalCode, street, number, neighborhood, city, state).

array

obrigatório

Um ou mais sócios, cada um com ownerType (PARTNER, LEGAL_REPRESENTATIVE ou BOTH), documentNumber, fullName, birthDate, motherName, phoneNumber, email e address.

Gerenciar sessões

lista

Lista as sessões do parceiro. Query: limit (1 a 200), status, externalUserId.

consulta

Obtém uma sessão pelo id.

atualização

Força uma atualização de status junto ao provedor.

reabertura

Obtém uma webViewUrl de documentoscopia fresca, reabrindo a sessão se ela expirou.

status

A última sessão de um dos seus usuários. Retorna hasSession: false quando não há nenhuma.

Status da sessão

Uma sessão passa por estes status (também entregues como webhooks KYC_*):

`status`	Significado
`PENDING`	Sessão criada, aguardando documentoscopia.
`IN_PROGRESS`	Documentoscopia em análise.
`APPROVED`	KYC aprovado.
`REJECTED`	KYC rejeitado (motivo em `rejectionReason`).
`EXPIRED`	Sessão expirada.
`ERROR`	Erro no provedor.

Seja notificado das mudanças de status pelos webhooks KYC_*, ou faça polling em GET /api/v1/users/kyc/sessions/:sessionId. O payload da sessão nunca expõe o hash cru do documento nem a resposta crua do provedor.

Comece Aqui

Usuários

Parceiros e API Keys

Taxas e repasse

Preços

Cash-out (offramp)

Cash-in (onramp)

Recibos

Links

BRLP

Webhooks

KYC

Consulta e verificação de documento

Sessões de onboarding

Iniciar uma sessão de pessoa física (PF)

Iniciar uma sessão de pessoa jurídica (PJ)

Gerenciar sessões

Status da sessão

​Consulta e verificação de documento

​Sessões de onboarding

​Iniciar uma sessão de pessoa física (PF)

​Iniciar uma sessão de pessoa jurídica (PJ)

​Gerenciar sessões

​Status da sessão

Consulta e verificação de documento

Sessões de onboarding

Iniciar uma sessão de pessoa física (PF)

Iniciar uma sessão de pessoa jurídica (PJ)

Gerenciar sessões

Status da sessão