Pular para o conteúdo principal

​
O que é um Ramp?

Um Ramp é uma transação que converte entre moeda fiat e criptomoeda. A KillB suporta tanto on-ramps (fiat → cripto) quanto off-ramps (cripto → fiat).
Pense em ramps como a ponte entre bancos tradicionais e criptomoeda. Eles lidam com todo o processo de conversão desde a cotação até a liquidação.

​
Tipos de Ramp

Fiat → CriptomoedaConverta moeda local (COP, MXN, USD) em stablecoins (USDC, USDT).Fluxo:
  1. Usuário obtém uma cotação (ex: 100.000 COP → 23,8 USDC)
  2. Usuário cria ramp com endereço da carteira
  3. Usuário paga via PSE/SPEI/ACH
  4. KillB processa conversão
  5. USDC/USDT enviado para carteira do usuário
Casos de Uso Comuns:
  • Comprar cripto com moeda local
  • Financiar posições DeFi
  • Remessas transfronteiriças
  • Investimento em cripto

​
Ciclo de Vida do Ramp

Um ramp passa por múltiplos estágios de status durante o processamento:

​
Status do Ramp

Status de Processamento

CREATED
  • Ramp inicializado, aguardando pagamento
  • Instruções de pagamento fornecidas ao usuário
CASH_IN_REQUEST / CASH_IN_REQUESTED
  • Solicitação de pagamento enviada ao provedor
  • Aguardando pagamento do usuário
CASH_IN_PROCESSING
  • Pagamento recebido, sendo verificado
  • Confirmação em andamento
CASH_IN_COMPLETED
  • Pagamento confirmado
  • Pronto para conversão
CONVERSION_PROCESSING
  • Convertendo fiat ↔ cripto
  • Executando negociação
CONVERSION_COMPLETED
  • Conversão finalizada
  • Pronto para desembolso
CASH_OUT_PROCESSING
  • Enviando fundos para destino
  • Transação em andamento
CASH_OUT_COMPLETED
  • Fundos enviados para destino
  • Aguardando confirmação final
COMPLETED ✅
  • Transação totalmente concluída
  • Fundos entregues ao usuário
  • Recibo disponível
FAILED ❌
  • Transação falhou em algum estágio
  • Verifique o campo details para o motivo
  • Pode ser elegível para retry
CANCELED 🚫
  • Cancelado por usuário ou sistema
  • Nenhum fundo transferido
  • Reembolso iniciado se aplicável
REJECTED ⛔
  • Rejeitado por compliance ou provedor
  • Verifique note para detalhes
  • Pode exigir verificação adicional
ERROR ⚠️
  • Erro do sistema ocorreu
  • Contate suporte com ID do ramp
  • Será investigado e resolvido

​
Criando um Ramp

​
Pré-requisitos

Antes de criar um ramp, você precisa:
1

Usuário

Um usuário verificado com nível KYC apropriado
2

Conta

Uma conta ativa (banco ou carteira) como destino
3

Cotação

Uma cotação válida e não expirada

​
Criação Básica de Ramp

POST /api/v2/ramps
Requisição: 
{
  "quotationId": "quot-9f8e7d6c-5b4a-3c2d-1e0f",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "accountId": "7c8b9a3d-2f1e-4b5c-9d8e-1a2b3c4d5e6f"
}
Resposta: 
{
  "id": "ramp-1a2b3c4d-5e6f-7g8h-9i0j",
  "status": "CREATED",
  "type": "ON",
  "fromCurrency": "COP",
  "toCurrency": "USDC",
  "fromAmount": 100000,
  "toAmount": 23.81,
  "cashInMethod": "PSE",
  "cashOutMethod": "POLYGON",
  "paymentInfo": [{
    "url": "https://checkout.pse.com.co/payment/123456"
  }],
  "isPreFunded": false,
  "externalId": null,
  "createdAt": "2024-01-15T10:30:00.000Z"
}

​
Múltiplas Contas de Destino

Você pode dividir um ramp entre múltiplas contas de destino: 
{
  "quotationId": "quot-id",
  "userId": "user-id",
  "accounts": [
    {
      "id": "account-1",
      "amount": 50
    },
    {
      "id": "account-2",
      "amount": 50
    }
  ]
}
Útil para dividir pagamentos, diversificar entre carteiras ou gerenciar múltiplos beneficiários.

​
Informações de Pagamento

Com base no método de pagamento, diferentes informações de pagamento são retornadas: 
{
  "paymentInfo": [{
    "url": "https://checkout.pse.com.co/payment/abc123"
  }]
}
  • Redirecione o usuário para a url
  • Usuário completa pagamento através do PSE
  • Webhook notifica sobre conclusão do pagamento

​
Melhores Práticas

  • Nunca codifique taxas de câmbio
  • Crie cotação nova para cada ramp
  • Respeite expiração da cotação (30 segundos)
  • Mostre aos usuários os valores exatos
  • Faça polling do status do ramp a cada 10-30 segundos
  • Use webhooks como notificação primária
  • Polling como mecanismo de backup
  • Mostre aos usuários o status atual
  • Pagamento leva mais tempo que o esperado
  • Usuário fecha navegador durante pagamento
  • Problemas de conectividade de rede
  • Cotação expira antes da criação
  • Cenários de fundos insuficientes
  • Forneça externalId único por ramp
  • Previne transações duplicadas
  • Habilita retries idempotentes
  • Simplifica reconciliação

​
Testando Ramps

​
Testes no Sandbox

No sandbox, use endpoints faker: 
// Criar ramp
const ramp = await createRamp(quoteId, userId, accountId);

// Simular pagamento (somente sandbox)
await fetch('/api/v2/faker/cash-in', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: JSON.stringify({ rampId: ramp.id })
});

// Fazer polling para conclusão
const completed = await waitForStatus(ramp.id, 'COMPLETED');

​
Próximos Passos

Guia On-Ramp

Guia completo para implementar on-ramps

Guia Off-Ramp

Guia completo para implementar off-ramps

Cotações

Aprenda sobre preços e cotações

Referência da API

Veja a documentação da API de Ramps