> ## Documentation Index
> Fetch the complete documentation index at: https://docs.killb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Implementação On-Ramp

> Converta moeda fiat para criptomoeda

## 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

<Steps>
  <Step title="Criar Usuário e Carteira">
    Configure perfil do usuário e carteira de destino
  </Step>

  <Step title="Obter Cotação">
    Solicite cotação de preço para conversão
  </Step>

  <Step title="Criar Ramp">
    Execute ramp com ID da cotação
  </Step>

  <Step title="Usuário Paga">
    Usuário completa pagamento via PSE/SPEI/etc
  </Step>

  <Step title="Conversão">
    KillB converte fiat para cripto
  </Step>

  <Step title="Cripto Entregue">
    USDC/USDT enviado para carteira do usuário
  </Step>
</Steps>

## Exemplo de Implementação

<CodeGroup>
  ```javascript Fluxo Completo theme={null}
  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;
  ```

  ```python Fluxo Completo theme={null}
  def execute_onramp(user_id, wallet_address, amount, access_token):
      """Execute fluxo completo de on-ramp"""
      base_url = 'https://sandbox.killb.app'
      headers = {
          'Authorization': f'Bearer {access_token}',
          'Content-Type': 'application/json'
      }
      
      # 1. Criar conta de carteira
      wallet_response = requests.post(
          f'{base_url}/api/v2/accounts',
          headers=headers,
          json={
              'type': 'WALLET',
              'userId': user_id,
              'externalId': f'{user_id}-wallet',
              'data': {
                  # ... dados da carteira
                  'currency': 'USDC',
                  'network': 'POLYGON',
                  'address': wallet_address
              }
          }
      )
      wallet = wallet_response.json()
      
      # 2. Obter cotação
      quote_response = requests.post(
          f'{base_url}/api/v2/quotations',
          headers=headers,
          json={
              'fromCurrency': 'COP',
              'toCurrency': 'USDC',
              'amount': amount,
              'amountIsToCurrency': False,
              'cashInMethod': 'PSE',
              'cashOutMethod': 'POLYGON'
          }
      )
      quote = quote_response.json()
      
      # 3. Criar ramp
      ramp_response = requests.post(
          f'{base_url}/api/v2/ramps',
          headers=headers,
          json={
              'quotationId': quote['id'],
              'userId': user_id,
              'accountId': wallet['id']
          }
      )
      ramp = ramp_response.json()
      
      return {
          'ramp_id': ramp['id'],
          'payment_url': ramp['paymentInfo'][0]['url'],
          'expected_amount': quote['toAmount']
      }
  ```
</CodeGroup>

## Métodos de Pagamento

<Tabs>
  <Tab title="PSE (Colômbia)">
    Usuário redirecionado para checkout PSE:

    ```javascript theme={null}
    // 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
  </Tab>

  <Tab title="SPEI (México)">
    Usuário transfere para CLABE fornecida:

    ```javascript theme={null}
    const paymentInfo = ramp.paymentInfo[0];

    // Mostrar ao usuário:
    console.log('Banco:', paymentInfo.Bank);
    console.log('CLABE:', paymentInfo.CLABE);
    console.log('Beneficiário:', paymentInfo.Beneficiary);
    console.log('Referência:', paymentInfo.concepto);

    // Usuário completa transferência SPEI com referência
    ```

    **Importante:** Usuário DEVE incluir `concepto` como referência de pagamento
  </Tab>
</Tabs>

## Monitorando Progresso

```javascript theme={null}
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
};
```

<Tip>
  Use webhooks como método de notificação primário, com polling como backup.
</Tip>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Guia Off-Ramp" icon="arrow-down" href="/pt/guides/ramps/off-ramp">
    Implemente conversão cripto para fiat
  </Card>

  <Card title="Rastreamento de Status" icon="chart-line" href="/pt/guides/ramps/ramp-status">
    Monitore o progresso do ramp
  </Card>
</CardGroup>