Saltar al contenido principal

​
¿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).
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.

​
Tipos de Ramp

Fiat → CriptomonedaConvierte 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

​
Ciclo de Vida del Ramp

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

​
Estado del Ramp

Estados de Procesamiento

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

​
Creando un Ramp

​
Prerrequisitos

Antes de crear un ramp, necesitas:
1

Usuario

Un usuario verificado con nivel KYC apropiado
2

Cuenta

Una cuenta activa (banco o billetera) como destino
3

Cotización

Una cotización válida y no expirada

​
Creación Básica de Ramp

POST /api/v2/ramps
Solicitud: 
{
  "quotationId": "quot-9f8e7d6c-5b4a-3c2d-1e0f",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "accountId": "7c8b9a3d-2f1e-4b5c-9d8e-1a2b3c4d5e6f"
}
Respuesta: 
{
  "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: 
{
  "quotationId": "quot-id",
  "userId": "user-id",
  "accounts": [
    {
      "id": "account-1",
      "amount": 50
    },
    {
      "id": "account-2",
      "amount": 50
    }
  ]
}
Útil para dividir pagos, diversificar entre billeteras o gestionar múltiples beneficiarios.

​
Información de Pago

Basado en el método de pago, se retorna diferente información de pago: 
{
  "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

​
Mejores Prácticas

  • 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
  • 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
  • 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
  • Proporciona externalId único por ramp
  • Previene transacciones duplicadas
  • Habilita reintentos idempotentes
  • Simplifica reconciliación

​
Probando Ramps

​
Pruebas en Sandbox

En sandbox, usa endpoints faker: 
// 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

Guía On-Ramp

Guía completa para implementar on-ramps

Guía Off-Ramp

Guía completa para implementar off-ramps

Cotizaciones

Aprende sobre precios y cotizaciones

Referencia API

Ve la documentación de la API de Ramps