Pular para o conteúdo principal

​
O que é um Usuário?

Um Usuário na KillB representa um indivíduo ou entidade empresarial que pode realizar transações ramp. Os usuários são obrigados a completar a verificação Know Your Customer (KYC) ou Know Your Business (KYB) antes de transacionar.
Toda transação na KillB deve estar associada a um usuário verificado para cumprir requisitos regulatórios.

​
Tipos de Usuário

Usuários individuais (pessoas físicas)Informações Requeridas:
  • Nome completo (primeiro, meio, último)
  • Data de nascimento
  • Email e telefone
  • Endereço físico
  • ID emitido pelo governo
  • Nacionalidade e cidadania
Casos de Uso:
  • Remessas pessoais
  • Investimentos individuais
  • Compras de cripto pessoais
Exemplo:
{
  "type": "PERSON",
  "data": {
    "firstName": "João",
    "lastName": "Silva",
    "dateOfBirth": "1990-05-15",
    "email": "[email protected]",
    "phone": "+5511987654321",
    "document": {
      "type": "CPF",
      "number": "12345678900",
      "issuedCountryCode": "BR"
    }
  }
}

​
Status do Usuário

Os usuários podem ter diferentes status:
StatusDescriçãoPode Transacionar?
ACTIVEUsuário verificado e aprovado✅ Sim
PENDINGDocumentos KYC sob revisão❌ Não
REJECTEDVerificação KYC falhou❌ Não
Controle todas as operações com status === ACTIVE. Se um usuário estiver PENDING, envie-o para complianceUrl para completar a verificação.

​
Documentos Requeridos

​
Documentos de Pessoa

  • NUIP (Número Único de Identificación Personal)
  • Cédula de Ciudadanía (CC)
  • Passaporte
  • Carteira de Motorista

​
Documentos da Empresa

  • NIT (Colômbia) - Número de identificação fiscal
  • RFC (México) - Registro federal de contribuintes
  • EIN (EUA) - Número de identificação do empregador
  • CNPJ (Brasil) - Cadastro Nacional da Pessoa Jurídica
  • CUIT (Argentina) - Código único de identificação tributária

​
ID Externo

O campo externalId permite que você vincule usuários KillB ao seu próprio sistema de usuários: 
{
  "type": "PERSON",
  "externalId": "user_abc123_do_meu_sistema",
  "data": { ... }
}
Benefícios:
  • Mapear usuários KillB para seu banco de dados
  • Evitar criação de usuário duplicado
  • Simplificar buscas de usuário
  • Manter integridade referencial
Use seu ID de usuário interno como externalId para fácil mapeamento entre sistemas.

​
Propriedades do Usuário

​
Campos Principais

CampoTipoObrigatórioDescrição
idUUIDAutoID do usuário gerado pela KillB
typeEnum✅PERSON ou COMPANY
statusEnumAutoACTIVE, PENDING, REJECTED
customerIdUUIDAutoSeu ID de cliente
externalIdStringOpcionalID do usuário no seu sistema
complianceUrlURLAutoPortal de verificação KYC

​
Campos Específicos de Pessoa

  • firstName, middleName, lastName
  • dateOfBirth
  • nationality, citizenship
  • employmentStatus, occupation
  • employerName, employmentDescription

​
Campos Específicos de Empresa

  • companyName, tradeName
  • registeredNumber
  • legalStructure (LLC, C_CORP, S_CORP, etc.)
  • establishedOn
  • naics, naicsDescription
  • mainOwnerUser, ownerUsers[]

​
Perfil de Investimento

Os usuários devem fornecer um perfil de investimento para fins de compliance: 
{
  "investmentProfile": {
    "primarySourceOfFunds": "EMPLOYMENT",
    "primarySourceOfFundsDescription": "Software engineer salary",
    "totalAssets": "TEN_TO_100K",
    "usdValueOfFiat": "TEN_TO_100K",
    "monthlyDeposits": "UPTO_5",
    "monthlyWithdrawals": "UPTO_5",
    "monthlyInvestmentDeposit": "ONE_TO_100K",
    "monthlyInvestmentWithdrawal": "UPTO_1K",
    "usdValueOfCrypto": "TEN_TO_100K",
    "monthlyCryptoDeposits": "UPTO_5",
    "monthlyCryptoWithdrawals": "UPTO_5"
  }
}

​
Opções de Origem de Fundos

  • EMPLOYMENT - Salário/remuneração
  • SAVINGS - Poupança pessoal
  • INVESTMENT - Renda de investimentos
  • COMPANY - Receita empresarial
  • REAL_ESTATE - Renda imobiliária
  • TRUST - Fundo fiduciário
  • OTHER - Outras fontes

​
Perfil KYC

Informações de prevenção à lavagem de dinheiro e compliance: 
{
  "kycProfile": {
    "fundsSendReceiveJurisdictions": ["CO", "US", "MX"],
    "engageInActivities": ["NONE"]
  }
}

​
Atividades Proibidas

Os usuários devem confirmar que não participam de:
  • ADULT_ENTERTAINMENT
  • DRUGS
  • FIREARMS
  • GAMBLING
  • MARIJUANA
  • TUMBLING (mistura de criptoativos)

​
Gerenciando Usuários

​
Criar um Usuário

POST /api/v2/users
Veja o Guia de Criação de Usuário para exemplos detalhados.

​
Consultar Usuários

GET /api/v2/users?type=PERSON&email=[email protected]
Opções de Filtro:
  • type - PERSON ou COMPANY
  • firstName, lastName, email
  • externalId - Seu ID de sistema
  • customerId - Filtrar por cliente

​
Atualizar Usuário

PATCH /api/v2/users/{userId}
Atualize informações do usuário, faça upload de documentos adicionais ou modifique dados de perfil.

​
Excluir Usuário

DELETE /api/v2/users/{userId}
A exclusão de usuário é uma exclusão suave. Os dados do usuário são retidos para compliance mas marcados como inativos.

​
Melhores Práticas

  • Valide formatos de dados antes do envio
  • Garanta que os nomes correspondam exatamente aos IDs do governo
  • Use formato correto de número de telefone (+[código do país][número])
  • Verifique endereços de email
  • Confirme que os endereços estão completos e precisos
  • Sempre forneça um externalId
  • Use seu ID de usuário interno
  • Permite buscas e reconciliação fáceis
  • Previne criação de usuário duplicado
  • Verifique status antes de permitir transações
  • Guie usuários para o próximo passo de verificação
  • Monitore complianceUrl para atualizações KYC
  • Armazene o userId da KillB no seu banco de dados
  • Faça o mapeamento com o seu externalId
  • Faça cache dos dados do usuário de forma adequada
  • Sincronize mudanças de status via webhooks

​
Perguntas Comuns

Não. Cada indivíduo único deve ter apenas um perfil de usuário. Use o mesmo ID de usuário para todas as transações.
  • L0-L1: Instantâneo (automatizado)\n - L2: 1-24 horas (automatizado + revisão manual)\n - L3-L4: 1-5 dias úteis (due diligence aprimorada)
Sim, use o endpoint PATCH /api/v2/users/{id}. Alguns campos exigem nova verificação.
O status do usuário se torna REJECTED e ele não pode transacionar. Verifique o campo note para os motivos da rejeição. O usuário pode reenviar as informações corrigidas.

​
Próximos Passos

Crie Seu Primeiro Usuário

Siga o guia passo a passo para criar usuários

Entendendo Contas

Aprenda sobre contas bancárias e carteiras

Referência da API

Veja a documentação completa da API de Usuários