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

> Comprendiendo on-ramps y off-ramps para conversión cripto

## ¿Qué es un Ramp?

Un **Ramp** es una transacción que convierte entre moneda fiat y criptomoneda. KillB soporta tanto **on-ramps** (fiat → cripto) como **off-ramps** (cripto → fiat).

<Info>
  Piensa en los ramps como el puente entre la banca tradicional y las criptomonedas. Manejan todo el proceso de conversión desde la cotización hasta la liquidación.
</Info>

## Tipos de Ramp

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

    Convierte moneda local (COP, MXN, USD) en stablecoins (USDC, USDT).

    **Flujo:**

    1. Usuario obtiene una cotización (ej: 100.000 COP → 23,8 USDC)
    2. Usuario crea ramp con dirección de billetera
    3. Usuario paga vía PSE/SPEI/ACH
    4. KillB procesa conversión
    5. USDC/USDT enviado a billetera del usuario

    **Casos de Uso Comunes:**

    * Comprar cripto con moneda local
    * Financiar posiciones DeFi
    * Remesas transfronterizas
    * Inversión en cripto

    ```mermaid theme={null}
    graph LR
        A[Cuenta Bancaria del Usuario] -->|COP/MXN/USD| B[KillB]
        B -->|Convertir| C[Cripto]
        C -->|USDC/USDT| D[Billetera del Usuario]
    ```
  </Tab>

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

    Convierte stablecoins (USDC, USDT) de vuelta a moneda local (COP, MXN, USD).

    **Flujo:**

    1. Usuario obtiene una cotización (ej: 100 USDC → 420.000 COP)
    2. Usuario crea ramp con cuenta bancaria
    3. Usuario envía USDC/USDT a dirección proporcionada
    4. KillB procesa conversión
    5. COP/MXN/USD enviado al banco del usuario

    **Casos de Uso Comunes:**

    * Retirar tenencias de cripto
    * Pagar gastos locales
    * Pagos de salario en cripto
    * Liquidaciones de negocios

    ```mermaid theme={null}
    graph LR
        A[Billetera del Usuario] -->|USDC/USDT| B[KillB]
        B -->|Convertir| C[Fiat]
        C -->|COP/MXN/USD| D[Cuenta Bancaria del Usuario]
    ```
  </Tab>
</Tabs>

## Ciclo de Vida del Ramp

Un ramp pasa por múltiples etapas de estado durante el procesamiento:

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

## Estado del Ramp

<AccordionGroup>
  <Accordion title="Estados de Procesamiento" icon="spinner" defaultOpen>
    **CREATED**

    * Ramp inicializado, esperando pago
    * Instrucciones de pago proporcionadas al usuario

    **CASH\_IN\_REQUEST / CASH\_IN\_REQUESTED**

    * Solicitud de pago enviada al proveedor
    * Esperando pago del usuario

    **CASH\_IN\_PROCESSING**

    * Pago recibido, siendo verificado
    * Confirmación en progreso

    **CASH\_IN\_COMPLETED**

    * Pago confirmado
    * Listo para conversión

    **CONVERSION\_PROCESSING**

    * Convirtiendo fiat ↔ cripto
    * Ejecutando trade

    **CONVERSION\_COMPLETED**

    * Conversión finalizada
    * Listo para desembolso

    **CASH\_OUT\_PROCESSING**

    * Enviando fondos a destino
    * Transacción en progreso

    **CASH\_OUT\_COMPLETED**

    * Fondos enviados a destino
    * Esperando confirmación final
  </Accordion>

  <Accordion title="Estados Finales" icon="flag-checkered">
    **COMPLETED** ✅

    * Transacción totalmente completada
    * Fondos entregados al usuario
    * Recibo disponible

    **FAILED** ❌

    * Transacción falló en alguna etapa
    * Verifica el campo `details` para el motivo
    * Puede ser elegible para reintento

    **CANCELED** 🚫

    * Cancelado por usuario o sistema
    * Ningún fondo transferido
    * Reembolso iniciado si aplica

    **REJECTED** ⛔

    * Rechazado por compliance o proveedor
    * Verifica `note` para detalles
    * Puede requerir verificación adicional

    **ERROR** ⚠️

    * Error del sistema ocurrió
    * Contacta soporte con ID del ramp
    * Será investigado y resuelto
  </Accordion>
</AccordionGroup>

## Creando un Ramp

### Prerrequisitos

Antes de crear un ramp, necesitas:

<Steps>
  <Step title="Usuario">
    Un usuario verificado con nivel KYC apropiado
  </Step>

  <Step title="Cuenta">
    Una cuenta activa (banco o billetera) como destino
  </Step>

  <Step title="Cotización">
    Una cotización válida y no expirada
  </Step>
</Steps>

### Creación Básica de Ramp

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

**Solicitud:**

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

**Respuesta:**

```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últiples Cuentas de Destino

Puedes dividir un ramp entre múltiples cuentas 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 pagos, diversificar entre billeteras o gestionar múltiples beneficiarios.
</Tip>

## Información de Pago

Basado en el método de pago, se retorna diferente información de pago:

<Tabs>
  <Tab title="PSE (Colombia)">
    ```json theme={null}
    {
      "paymentInfo": [{
        "url": "https://checkout.pse.com.co/payment/abc123"
      }]
    }
    ```

    * Redirige al usuario a la `url`
    * Usuario completa pago a través de PSE
    * Webhook notifica sobre finalización del pago
  </Tab>

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

    * Usuario inicia transferencia SPEI a CLABE
    * Debe incluir `concepto` como referencia
    * KillB empareja pago vía referencia
  </Tab>

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

    * Usuario envía cripto a dirección proporcionada
    * KillB detecta depósito vía blockchain
    * Transacción confirmada después de confirmaciones de red
  </Tab>
</Tabs>

## Mejores Prácticas

<AccordionGroup>
  <Accordion title="Siempre Usa Cotizaciones" icon="chart-line">
    * Nunca codifiques tasas de cambio
    * Crea cotización nueva para cada ramp
    * Respeta expiración de cotización (30 segundos)
    * Muestra a los usuarios los montos exactos
  </Accordion>

  <Accordion title="Implementa Polling de Estado" icon="rotate">
    * Haz polling del estado del ramp cada 10-30 segundos
    * Usa webhooks como notificación primaria
    * Polling como mecanismo de respaldo
    * Muestra a los usuarios el estado actual
  </Accordion>

  <Accordion title="Maneja Casos Extremos" icon="triangle-exclamation">
    * Pago toma más tiempo del esperado
    * Usuario cierra navegador durante pago
    * Problemas de conectividad de red
    * Cotización expira antes de creación
    * Escenarios de fondos insuficientes
  </Accordion>

  <Accordion title="Usa IDs Externos" icon="fingerprint">
    * Proporciona `externalId` único por ramp
    * Previene transacciones duplicadas
    * Habilita reintentos idempotentes
    * Simplifica reconciliación
  </Accordion>
</AccordionGroup>

## Probando Ramps

### Pruebas en Sandbox

En sandbox, usa endpoints faker:

```javascript theme={null}
// Crear ramp
const ramp = await createRamp(quoteId, userId, accountId);

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

// Hacer polling para finalización
const completed = await waitForStatus(ramp.id, 'COMPLETED');
```

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Guía On-Ramp" icon="arrow-up" href="/es/guides/ramps/on-ramp">
    Guía completa para implementar on-ramps
  </Card>

  <Card title="Guía Off-Ramp" icon="arrow-down" href="/es/guides/ramps/off-ramp">
    Guía completa para implementar off-ramps
  </Card>

  <Card title="Cotizaciones" icon="calculator" href="/es/concepts/quotations">
    Aprende sobre precios y cotizaciones
  </Card>

  <Card title="Referencia API" icon="code" href="/api-reference/endpoint/ramps-create">
    Ve la documentación de la API de Ramps
  </Card>
</CardGroup>