Pular para o conteúdo principal

​
Visão Geral

O ambiente Sandbox da KillB permite que você teste sua integração sem processar transações reais ou movimentar fundos reais.
Todas as transações no sandbox usam dinheiro falso. Nenhum fundo real será transferido ou cobrado.

​
Ambientes

URL Base: https://teste-94u93qnn.uc.gateway.devRecursos:
  • Teste com dinheiro falso
  • Simule fluxos de pagamento
  • Verificação KYC real não é necessária
  • Processamento instantâneo de transações
  • Funcionalidade completa da API
Use para:
  • Desenvolvimento e testes
  • Verificação de integração
  • Aplicações de demonstração
  • Testes CI/CD

​
Começando com o Sandbox

​
Passo 1: Obter Credenciais do Sandbox

  1. Cadastre-se em otc.killb.com
  2. Navegue até Configurações → Chaves de API
  3. Crie uma Chave de API Sandbox
  4. Anote seu email e senha do sandbox

​
Passo 2: Definir Variáveis de Ambiente

.env
KILLB_ENV=sandbox
KILLB_BASE_URL=https://teste-94u93qnn.uc.gateway.dev
KILLB_EMAIL=[email protected]
KILLB_PASSWORD=sua-senha-sandbox
KILLB_API_KEY=sua-chave-api-sandbox

​
Passo 3: Autenticar

curl --request POST \
  --url https://teste-94u93qnn.uc.gateway.dev/api/v2/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]",
    "password": "sua-senha-sandbox"
  }'

​
Recursos de Teste

​
Endpoints Faker

O Sandbox fornece endpoints especiais para simular eventos de pagamento:

Cash-In Falso

Simule um usuário completando um pagamento fiat (PSE, SPEI, etc.)
POST /api/v2/faker/cash-in
Requisição:
{
  "rampId": "ramp-id-da-criacao"
}
O que faz:
  • Marca o cash-in como concluído
  • Aciona o processo de conversão
  • Move o ramp para o próximo status
Exemplo:
curl --request POST \
  --url https://teste-94u93qnn.uc.gateway.dev/api/v2/faker/cash-in \
  --header 'Authorization: Bearer SEU_TOKEN_DE_ACESSO' \
  --header 'Content-Type: application/json' \
  --data '{"rampId": "seu-ramp-id"}'
Simule a conclusão da conversão cripto para fiat
POST /api/v2/faker/cash-out
Requisição:
{
  "rampId": "ramp-id-da-criacao"
}
O que faz:
  • Completa o processo de cash-out
  • Marca o ramp como COMPLETED
  • Aciona webhooks
Exemplo:
curl --request POST \
  --url https://teste-94u93qnn.uc.gateway.dev/api/v2/faker/cash-out \
  --header 'Authorization: Bearer SEU_TOKEN_DE_ACESSO' \
  --header 'Content-Type: application/json' \
  --data '{"rampId": "seu-ramp-id"}'

​
Fluxos de Teste

​
Teste Completo de On-Ramp

1

Criar Usuário de Teste

Use qualquer dado com aparência válida - nenhuma verificação real no sandbox
{
  "firstName": "Teste",
  "lastName": "Usuário",
  "email": "[email protected]",
  "document": { "type": "PASSPORT", "number": "TEST123" }
}
2

Criar Conta de Carteira

Use qualquer formato de endereço de carteira válido
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "network": "POLYGON",
  "currency": "USDC"
}
3

Criar Cotação

Obtenha uma cotação de teste com taxas do sandbox
4

Criar Ramp

Execute a transação ramp
5

Simular Pagamento

Use /api/v2/faker/cash-in para simular o pagamento do usuário
6

Verificar Conclusão

Verifique se o status do ramp muda para COMPLETED

​
Teste Completo de Off-Ramp

1

Criar Usuário de Teste

O mesmo que o fluxo de on-ramp
2

Criar Conta Bancária

Use detalhes bancários de teste
{
  "type": "PSE",
  "accountNumber": "1234567890",
  "bankCode": "0001"
}
3

Criar Cotação

Cotação de USDC para COP/MXN
4

Criar Ramp

Execute o ramp com fonte cripto
5

Simular Conclusão

Use /api/v2/faker/cash-out para completar o processo
6

Verificar Status

Confirme que o status é COMPLETED e os webhooks foram disparados

​
Dados de Teste

​
Contas Bancárias de Teste (Colômbia)

Nome do BancoCódigo do BancoTipo de Conta
Bancolombia0001poupança, corrente
Banco de Bogotá0002poupança, corrente
Davivienda0003poupança, corrente

​
Contas Bancárias de Teste (México)

Nome do BancoCódigo do BancoFormato CLABE
BBVA012012XXXXXXXXXXXXXXXXX
Santander014014XXXXXXXXXXXXXXXXX
Banorte072072XXXXXXXXXXXXXXXXX

​
Endereços de Carteira de Teste

Polygon (MATIC):
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Solana:
5FHwkrdxntdK24hgQU8qgBjn35Y1zwhz1GZwCkP4UJnC

Ethereum:
0x71C7656EC7ab88b098defB751B7401B5f6d8976F

Tron:
TXYZopYRdj2D9XRtbG4uXyrFPRw6sM3pjN
Estes são endereços de exemplo para testes. No sandbox, qualquer endereço formatado corretamente funcionará.

​
Limitações do Sandbox

Esteja ciente destas diferenças entre sandbox e produção:
RecursoSandboxProdução
Dinheiro real❌ Não✅ Sim
Verificação KYC❌ Simulada✅ Verificação real
Processamento de pagamento⚡ Instantâneo⏱️ Tempo real
Limites de transação♾️ Sem limites✅ Baseado em KYC
Webhooks✅ Sim✅ Sim
Limites de taxa da API🔓 Relaxados🔒 Aplicados

​
Depuração no Sandbox

​
Habilitar Log Detalhado

const DEBUG = process.env.KILLB_ENV === 'sandbox';

async function makeRequest(endpoint, options) {
  if (DEBUG) {
    console.log('Requisição:', endpoint, options);
  }
  
  const response = await fetch(endpoint, options);
  const data = await response.json();
  
  if (DEBUG) {
    console.log('Resposta:', data);
  }
  
  return data;
}

​
Monitorar Status do Ramp

async function waitForRampCompletion(rampId, maxAttempts = 30) {
  for (let i = 0; i < maxAttempts; i++) {
    const ramp = await fetch(`/api/v2/ramps/${rampId}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    }).then(r => r.json());
    
    console.log(`Tentativa ${i + 1}: Status = ${ramp.status}`);
    
    if (ramp.status === 'COMPLETED') {
      return ramp;
    }
    
    if (['FAILED', 'CANCELED', 'REJECTED'].includes(ramp.status)) {
      throw new Error(`Ramp ${ramp.status}: ${ramp.details}`);
    }
    
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
  
  throw new Error('Timeout de conclusão do ramp');
}

​
Mudando para Produção

Quando estiver pronto para ir ao vivo:
1

Atualizar URL Base

Mude de teste-94u93qnn.uc.gateway.dev para killb.app
const baseUrl = 'https://killb.app';
2

Usar Credenciais de Produção

Substitua as credenciais do sandbox pelas chaves de API de produção
3

Remover Chamadas Faker

Remova todas as chamadas aos endpoints /api/v2/faker/*
4

Implementar KYC Real

Lide com verificação KYC real e uploads de documentos
5

Adicionar Tratamento de Erros

Implemente tratamento de erros e logs de nível de produção
6

Habilitar Monitoramento

Configure monitoramento e alertas para sua integração

​
Lista de Verificação de Testes

Antes de ir para produção, teste estes cenários:
  • Criação de usuário e KYC
  • Criação de conta (banco e carteira)
  • Geração de cotação
  • Conclusão de on-ramp
  • Conclusão de off-ramp
  • Recepção de webhook
  • Geração de recibo
  • Tratamento de cotação expirada
  • Detalhes de conta inválidos
  • Saldo insuficiente
  • Simulação de pagamento com falha
  • Erros de rede
  • Expiração de token
  • Assinaturas de webhook inválidas
  • Valores muito pequenos (< $1)
  • Valores muito grandes (> $10,000)
  • Transações concorrentes
  • Limitação de taxa
  • Prevenção de duplicatas (externalId)
  • Múltiplas contas por usuário

​
Precisa de Ajuda?

Junte-se ao Discord

Obtenha ajuda da comunidade

Contatar Suporte

Entre em contato com nossa equipe