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

# Ramps

> Entendendo on-ramps e off-ramps para conversão cripto

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

<Info>
  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.
</Info>

## Tipos de Ramp

<Tabs>
  <Tab title="On-Ramp">
    **Fiat → Criptomoeda**

    Converta 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

    ```mermaid theme={null}
    graph LR
        A[Conta Bancária do Usuário] -->|COP/MXN/USD| B[KillB]
        B -->|Converter| C[Cripto]
        C -->|USDC/USDT| D[Carteira do Usuário]
    ```
  </Tab>

  <Tab title="Off-Ramp">
    **Criptomoeda → Fiat**

    Converta stablecoins (USDC, USDT) de volta em moeda local (COP, MXN, USD).

    **Fluxo:**

    1. Usuário obtém uma cotação (ex: 100 USDC → 420.000 COP)
    2. Usuário cria ramp com conta bancária
    3. Usuário envia USDC/USDT para endereço fornecido
    4. KillB processa conversão
    5. COP/MXN/USD enviado para banco do usuário

    **Casos de Uso Comuns:**

    * Sacar participações em cripto
    * Pagar despesas locais
    * Pagamentos de salário em cripto
    * Liquidações de negócios

    ```mermaid theme={null}
    graph LR
        A[Carteira do Usuário] -->|USDC/USDT| B[KillB]
        B -->|Converter| C[Fiat]
        C -->|COP/MXN/USD| D[Conta Bancária do Usuário]
    ```
  </Tab>
</Tabs>

## Ciclo de Vida do Ramp

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

```mermaid theme={null}
graph TD
    A[CREATED] --> B[CASH_IN_REQUEST]
    B --> C[CASH_IN_PROCESSING]
    C --> D[CASH_IN_COMPLETED]
    D --> E[CONVERSION_PROCESSING]
    E --> F[CONVERSION_COMPLETED]
    F --> G[CASH_OUT_PROCESSING]
    G --> H[CASH_OUT_COMPLETED]
    H --> I[COMPLETED]
    
    B -.-> J[FAILED]
    C -.-> J
    E -.-> J
    G -.-> J
    
    A -.-> K[CANCELED]
    B -.-> K
```

## Status do Ramp

<AccordionGroup>
  <Accordion title="Status de Processamento" icon="spinner" defaultOpen>
    **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
  </Accordion>

  <Accordion title="Status Finais" icon="flag-checkered">
    **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
  </Accordion>
</AccordionGroup>

## Criando um Ramp

### Pré-requisitos

Antes de criar um ramp, você precisa:

<Steps>
  <Step title="Usuário">
    Um usuário verificado com nível KYC apropriado
  </Step>

  <Step title="Conta">
    Uma conta ativa (banco ou carteira) como destino
  </Step>

  <Step title="Cotação">
    Uma cotação válida e não expirada
  </Step>
</Steps>

### Criação Básica de Ramp

```bash theme={null}
POST /api/v2/ramps
```

**Requisição:**

```json theme={null}
{
  "quotationId": "quot-9f8e7d6c-5b4a-3c2d-1e0f",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "accountId": "7c8b9a3d-2f1e-4b5c-9d8e-1a2b3c4d5e6f"
}
```

**Resposta:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "quotationId": "quot-id",
  "userId": "user-id",
  "accounts": [
    {
      "id": "account-1",
      "amount": 50
    },
    {
      "id": "account-2",
      "amount": 50
    }
  ]
}
```

<Tip>
  Útil para dividir pagamentos, diversificar entre carteiras ou gerenciar múltiplos beneficiários.
</Tip>

## Informações de Pagamento

Com base no método de pagamento, diferentes informações de pagamento são retornadas:

<Tabs>
  <Tab title="PSE (Colômbia)">
    ```json theme={null}
    {
      "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
  </Tab>

  <Tab title="SPEI (México)">
    ```json theme={null}
    {
      "paymentInfo": [{
        "network": "SPEI",
        "Bank": "BBVA",
        "Beneficiary": "KillB SA de CV",
        "CLABE": "012345678901234567",
        "concepto": "REF123ABC"
      }]
    }
    ```

    * Usuário inicia transferência SPEI para CLABE
    * Deve incluir `concepto` como referência
    * KillB corresponde pagamento via referência
  </Tab>

  <Tab title="Carteira Cripto">
    ```json theme={null}
    {
      "paymentInfo": [{
        "network": "POLYGON",
        "address": "0x123..."
      }]
    }
    ```

    * Usuário envia cripto para endereço fornecido
    * KillB detecta depósito via blockchain
    * Transação confirmada após confirmações da rede
  </Tab>
</Tabs>

## Melhores Práticas

<AccordionGroup>
  <Accordion title="Sempre Use Cotações" icon="chart-line">
    * 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
  </Accordion>

  <Accordion title="Implemente Polling de Status" icon="rotate">
    * 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
  </Accordion>

  <Accordion title="Lide com Casos Extremos" icon="triangle-exclamation">
    * 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
  </Accordion>

  <Accordion title="Use IDs Externos" icon="fingerprint">
    * Forneça `externalId` único por ramp
    * Previne transações duplicadas
    * Habilita retries idempotentes
    * Simplifica reconciliação
  </Accordion>
</AccordionGroup>

## Testando Ramps

### Testes no Sandbox

No sandbox, use endpoints faker:

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

<CardGroup cols={2}>
  <Card title="Guia On-Ramp" icon="arrow-up" href="/pt/guides/ramps/on-ramp">
    Guia completo para implementar on-ramps
  </Card>

  <Card title="Guia Off-Ramp" icon="arrow-down" href="/pt/guides/ramps/off-ramp">
    Guia completo para implementar off-ramps
  </Card>

  <Card title="Cotações" icon="calculator" href="/pt/concepts/quotations">
    Aprenda sobre preços e cotações
  </Card>

  <Card title="Referência da API" icon="code" href="/api-reference/endpoint/ramps-create">
    Veja a documentação da API de Ramps
  </Card>
</CardGroup>