Pular para o conteúdo principal

​
Visão Geral

Um on-ramp converte moeda fiat (COP, MXN, USD) em criptomoeda (USDC, USDT). Os usuários pagam com métodos de pagamento locais e recebem cripto em sua carteira.

​
Fluxo Completo de On-Ramp

1

Criar Usuário e Carteira

Configure perfil do usuário e carteira de destino
2

Obter Cotação

Solicite cotação de preço para conversão
3

Criar Ramp

Execute ramp com ID da cotação
4

Usuário Paga

Usuário completa pagamento via PSE/SPEI/etc
5

Conversão

KillB converte fiat para cripto
6

Cripto Entregue

USDC/USDT enviado para carteira do usuário

​
Exemplo de Implementação

const executeOnRamp = async (userId, walletAddress, amount) => {
  try {
    // 1. Criar conta de carteira se necessário
    let wallet = await findWalletAccount(userId, 'POLYGON', 'USDC');
    
    if (!wallet) {
      wallet = await createWalletAccount(userId, walletAddress, 'USDC', 'POLYGON');
    }
    
    // 2. Obter cotação
    const quote = await fetch('/api/v2/quotations', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        fromCurrency: 'COP',
        toCurrency: 'USDC',
        amount: amount,
        amountIsToCurrency: false,
        cashInMethod: 'PSE',
        cashOutMethod: 'POLYGON'
      })
    }).then(r => r.json());
    
    console.log(`Você receberá: ${quote.toAmount} USDC`);
    
    // 3. Criar ramp
    const ramp = await fetch('/api/v2/ramps', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        quotationId: quote.id,
        userId: userId,
        accountId: wallet.id,
        externalId: `onramp-${Date.now()}`
      })
    }).then(r => r.json());
    
    // 4. Redirecionar para pagamento
    return {
      rampId: ramp.id,
      paymentUrl: ramp.paymentInfo[0].url,
      expectedAmount: quote.toAmount
    };
    
  } catch (error) {
    console.error('On-ramp falhou:', error);
    throw error;
  }
};

// Uso
const result = await executeOnRamp('user-id', '0x742d35...', 100000);
window.location.href = result.paymentUrl;

​
Métodos de Pagamento

Usuário redirecionado para checkout PSE:
// Resposta do ramp inclui URL de pagamento
const paymentUrl = ramp.paymentInfo[0].url;

// Redirecionar usuário
window.location.href = paymentUrl;

// Usuário completa pagamento no PSE
// Webhook notifica quando pagamento confirmado
Fluxo:
  1. Redirecionar para URL PSE
  2. Usuário seleciona banco
  3. Usuário autentica
  4. Usuário confirma pagamento
  5. Webhook recebido

​
Monitorando Progresso

const monitorRamp = async (rampId) => {
  const pollInterval = setInterval(async () => {
    const ramp = await fetch(`/api/v2/ramps/${rampId}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    }).then(r => r.json());
    
    console.log('Status:', ramp.status);
    
    if (ramp.status === 'COMPLETED') {
      console.log('Cripto entregue!');
      console.log('Transação:', ramp.transferProof);
      clearInterval(pollInterval);
    } else if (['FAILED', 'CANCELED'].includes(ramp.status)) {
      console.error('Ramp falhou:', ramp.details);
      clearInterval(pollInterval);
    }
  }, 10000); // Verificar a cada 10 segundos
};
Use webhooks como método de notificação primário, com polling como backup.

​
Próximos Passos

Guia Off-Ramp

Implemente conversão cripto para fiat

Rastreamento de Status

Monitore o progresso do ramp