Pular para o conteúdo principal

​
O que é uma Conta?

Uma Conta na KillB representa um destino ou origem de fundos em uma transação ramp. As contas podem ser contas bancárias, carteiras cripto ou contas custodiais.
Os usuários podem ter múltiplas contas de diferentes tipos. Cada conta está vinculada a um usuário específico.

​
Tipos de Conta

Contas bancárias fiat tradicionais para receber moeda localTipos:
  • PSE - Contas bancárias colombianas
  • SPEI - Contas bancárias mexicanas (CLABE)
  • ACH - Contas bancárias dos EUA
  • WIRE - Transferências wire internacionais
  • TRANSFIYA - Carteiras móveis colombianas
Casos de Uso:
  • Destinos de off-ramp (cripto → fiat)
  • Recebimento de moeda local
  • Saques bancários

​
Status da Conta

StatusDescriçãoPode Transacionar?
ACTIVEConta verificada e pronta✅ Sim
PENDINGAguardando verificação❌ Não
REJECTEDVerificação falhou❌ Não
INACTIVEDesabilitada por usuário/admin❌ Não

​
Criando Contas

​
Conta PSE (Colômbia)

Conta bancária colombiana para receber COP: 
{
  "type": "PSE",
  "userId": "user-id-aqui",
  "externalId": "account-123",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "[email protected]",
    "phone": "+573001234567",
    "accountNumber": "1234567890",
    "bankCode": "0001",
    "type": "savings",
    "countryCode": "CO",
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}

​
Conta SPEI (México)

Conta bancária mexicana usando CLABE: 
{
  "type": "SPEI",
  "userId": "user-id-aqui",
  "externalId": "account-456",
  "data": {
    "firstName": "María",
    "lastName": "López",
    "email": "[email protected]",
    "phone": "+525512345678",
    "clabe": "012345678901234567",
    "clabeType": "CLABE",
    "countryCode": "MX",
    "document": {
      "type": "RFC",
      "number": "LOMM900515ABC",
      "issuedCountryCode": "MX"
    }
  }
}
SPEI suporta três tipos de CLABE: CLABE padrão de 18 dígitos, DEBIT_CARD de 16 dígitos ou PHONE_NUMBER de 10 dígitos

​
Conta de Carteira

Carteira cripto para receber USDC/USDT: 
{
  "type": "WALLET",
  "userId": "user-id-aqui",
  "externalId": "wallet-789",
  "data": {
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "phone": "+5511987654321",
    "currency": "USDC",
    "network": "POLYGON",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "countryCode": "BR",
    "document": {
      "type": "PASSPORT",
      "number": "AB123456",
      "issuedCountryCode": "BR"
    }
  }
}

​
Conta ACH (EUA)

Conta bancária dos EUA para USD: 
{
  "type": "ACH",
  "userId": "user-id-aqui",
  "externalId": "ach-001",
  "data": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "phone": "+12125551234",
    "bankName": "Chase Bank",
    "routingNumber": "021000021",
    "accountNumber": "123456789",
    "type": "checking",
    "countryCode": "US",
    "document": {
      "type": "SSN",
      "number": "123-45-6789",
      "issuedCountryCode": "US"
    }
  }
}

​
Validação de Conta

A KillB valida contas antes de permitir transações:

​
Validação de Conta Bancária

  • Código do banco existe nos bancos suportados
  • Formato do número da conta está correto
  • Número de roteamento é válido (para ACH/Wire)
  • CLABE é formato válido de 18 dígitos (para SPEI)
  • Nome do titular da conta corresponde ao usuário

​
Validação de Carteira

  • Endereço é válido para a rede especificada
  • Checksum do endereço está correto (para chains EVM)
  • Rede é suportada para a moeda
  • Endereço não é um contrato inteligente (a menos que permitido)

​
Consultando Contas

​
Obter Todas as Contas do Usuário

GET /api/v2/accounts/userId/{userId}

​
Pesquisar Contas

GET /api/v2/accounts?type=WALLET&userId=user-id
Opções de Filtro:
  • ids - IDs de conta específicos
  • userId - Filtrar por usuário
  • type - Tipo de conta
  • accountNumber - Número da conta bancária
  • address - Endereço da carteira

​
Atualizando Contas

Atualizar informações da conta (campos limitados): 
PATCH /api/v2/accounts/{accountId}
Campos Atualizáveis:
  • Informações de documento
  • Número CLABE (SPEI)
  • Endereço da carteira
  • Número da conta
  • Código do banco
Algumas atualizações podem exigir re-verificação e definir temporariamente o status da conta como PENDING.

​
Excluindo Contas

DELETE /api/v2/accounts/{accountId}
Contas usadas em ramps pendentes ou em processamento não podem ser excluídas até que essas transações sejam concluídas.

​
Melhores Práticas

  • Valide códigos bancários usando o endpoint /api/v2/banks
  • Verifique o formato do endereço da carteira no lado do cliente
  • Confirme que o usuário possui a conta
  • Teste com uma transação pequena primeiro
  • Forneça um externalId único para cada conta
  • Use seu identificador de conta interno
  • Permite pesquisa fácil de conta
  • Previne contas duplicadas
  • Permita que os usuários salvem múltiplas contas
  • Deixe os usuários definirem contas padrão/preferidas
  • Suporte troca de conta
  • Mostre o status de verificação da conta
  • Nunca armazene detalhes bancários sensíveis
  • Use IDs de conta da KillB em seu banco de dados
  • Implemente verificações de propriedade de conta
  • Valide o acesso à conta em cada uso

​
Próximos Passos

Guia de Gerenciamento de Contas

Guia completo para gerenciar contas

Configuração de Contas Bancárias

Configure contas bancárias para diferentes países

Carteiras Cripto

Configure contas de carteira de criptomoeda

Contas Pré-Financiadas

Aprenda sobre execução instantânea com liquidez pré-depositada

Referência da API

Veja a documentação da API de Contas