Onramp - Comprar Criptomoneda

Convierte moneda fiat a criptomoneda usando tu saldo virtual.

¿Qué es ONRAMP?

ONRAMP te permite comprar criptomoneda usando fondos fiat de tu cuenta virtual.

Criptomonedas soportadas:

USDC (USD Coin)
USDT (Tether)
ETH (Ethereum)
BTC (Bitcoin)
Y más…

Deals vs Órdenes

Importante: Las operaciones ONRAMP usan el endpoint /deals, no /orders. Un deal representa la intención de comprar cripto y puede pagarse completa o parcialmente. Cada pago crea una o más órdenes que ejecutan la compra.

Diferencias clave:

Deal: La intención de compra de cripto (puede financiarse parcialmente)
Orden: La ejecución real de la compra (creada automáticamente por el deal)
Pagos parciales: Puedes pagar un deal en múltiples cuotas para ONRAMP
Destino: Los deals solo necesitan la billetera/cuenta de destino

Ejecución Automática de Pagos

Saldo Requerido: Por defecto, necesitas saldo suficiente en tu cuenta virtual para cerrar un deal ONRAMP. Los pagos ONRAMP se ejecutan automáticamente cuando hay un crédito a tu saldo de moneda.

Cómo funciona:

Creas un deal ONRAMP por X cantidad de cripto
El deal requiere Y fiat en tu cuenta virtual
Cuando tu cuenta virtual recibe fondos (PAYIN, etc.), el deal se ejecuta automáticamente
Se crean órdenes y se compra el cripto

Comercios Pre-aprobados:

Algunos comercios pueden operar deals sin requerir saldo inicial
Esto permite crear deals antes de que los fondos estén disponibles
Contacta a Koywe para solicitar pre-aprobación de esta función

Ejemplo Rápido


// Comprar 10 USDC con COP
 
// 1. Obtener cotización
const quote = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
  {
    type: 'ONRAMP',
    originCurrencySymbol: 'COP',
    destinationCurrencySymbol: 'USDC',
    amountIn: 50000,  // 50,000 COP
    network: 'ETHEREUM'  // Requerido para cotizaciones cripto
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Recibirás:', quote.data.amountOut, 'USDC'); // ej., 12.34 USDC
console.log('Comisión de red:', quote.data.networkFee, 'COP');
 
// 2. Crear deal (¡no orden!)
const deal = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
  {
    type: 'ONRAMP',
    destinationAccountId: wallet.data.addresses.USDC,
    quoteId: quote.data.id
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Deal ONRAMP creado:', deal.id);
console.log('El deal puede pagarse completa o parcialmente');

Integración Paso a Paso

Paso 1: Obtener Billetera Cripto

Necesitas una dirección de billetera para recibir la criptomoneda:


// Opción 1: Obtener billetera del comercio
const wallet = await axios.get(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/wallet`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Dirección USDC:', wallet.data.addresses.USDC);

Paso 2: Verificar Saldo Fiat


const balances = await axios.get(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/accounts/balances`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
const copBalance = balances.data.find(b => b.currencySymbol === 'COP');
 
if (copBalance.availableBalance < 50000) {
  throw new Error('Saldo COP insuficiente');
}

Paso 3: Obtener Cotización


const quote = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
  {
    type: 'ONRAMP',
    originCurrencySymbol: 'COP',
    destinationCurrencySymbol: 'USDC',
    amountIn: 50000,
    network: 'ETHEREUM'  // Requerido para cotizaciones cripto
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
// Mostrar al usuario
console.log('Tasa de cambio:', quote.data.exchangeRate);
console.log('Recibirás:', quote.data.amountOut, 'USDC');
console.log('Comisión Koywe:', quote.data.koyweFee, 'COP');
console.log('Comisión de red:', quote.data.networkFee, 'COP');
console.log('Costo total:', quote.data.amountIn + quote.data.koyweFee + quote.data.networkFee, 'COP');
console.log('Cotización expira en:', quote.data.validFor || '10-15', 'segundos');

Paso 4: Crear Deal

Saldo Requerido: A menos que tu comercio esté pre-aprobado, necesitas saldo suficiente para cerrar el deal. El deal se ejecutará automáticamente cuando los fondos estén disponibles.


const deal = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
  {
    type: 'ONRAMP',
    destinationAccountId: wallet.data.addresses.USDC,  // Solo necesitas destino
    quoteId: quote.data.id,
    externalId: `onramp-${Date.now()}`
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Deal creado:', deal.data.id);
console.log('Estado:', deal.data.status); // "PENDING"
console.log('Los deals pueden pagarse completa o parcialmente');

Qué sucede después: El deal creará órdenes automáticamente conforme se procesan los pagos. Puedes financiar el deal en un pago o múltiples pagos parciales.

Paso 5: Monitorear Deal y Órdenes


// Vía webhooks (recomendado)
app.post('/webhooks/koywe', (req, res) => {
  const event = JSON.parse(req.body);
  
  // Actualizaciones de estado del deal
  if (event.type === 'deal.completed' && event.data.type === 'ONRAMP') {
    console.log('¡Deal completado!');
    console.log('ID del Deal:', event.data.id);
  }
  
  // Órdenes creadas por el deal
  if (event.type === 'order.completed' && event.data.type === 'ONRAMP') {
    console.log('¡Cripto recibida!');
    console.log('ID de Orden:', event.data.id);
    console.log('Monto:', event.data.amountOut, event.data.destinationCurrencySymbol);
  }
  
  res.status(200).send('OK');
});


// O consultar estado del deal
async function checkDealStatus(dealId) {
  const deal = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals/${dealId}`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  console.log('Estado del deal:', deal.data.status);
  console.log('Órdenes creadas:', deal.data.orders); // Array de IDs de orden
  
  return deal.data;
}

Redes Soportadas

Criptomoneda	Redes
USDC	Ethereum, Polygon, BSC
USDT	Ethereum, Polygon, BSC, Tron
ETH	Ethereum
BTC	Bitcoin
MATIC	Polygon
BNB	BSC

Selección de Red: Especifica la red al crear la dirección de billetera o usar cuenta de destino.

Ejemplo Completo


async function buyUSDC(amount) {
  try {
    const token = await authenticate();
    
    // 1. Verificar saldo COP
    const balances = await getBalances(token, orgId, merchantId);
    const copBalance = balances.find(b => b.currencySymbol === 'COP');
    
    if (copBalance.availableBalance < amount) {
      throw new Error('Saldo COP insuficiente');
    }
    
    // 2. Obtener dirección de billetera
    const wallet = await axios.get(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/wallet`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    // 3. Obtener cotización
    const quote = await axios.post(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
      {
        type: 'ONRAMP',
        originCurrencySymbol: 'COP',
        destinationCurrencySymbol: 'USDC',
        amountIn: amount,
        network: 'ETHEREUM'  // Requerido para cotizaciones cripto
      },
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    console.log(`Convirtiendo ${amount} COP a ${quote.data.amountOut} USDC`);
    console.log(`Tasa: 1 USDC = ${quote.data.exchangeRate} COP`);
    console.log('Cotización válida por:', quote.data.validFor || '10-15', 'segundos');
    
    // 4. Crear deal (¡no orden!)
    const deal = await axios.post(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
      {
        type: 'ONRAMP',
        destinationAccountId: wallet.data.addresses.USDC,  // Solo necesitas destino
        quoteId: quote.data.id
      },
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    console.log('Deal ONRAMP creado:', deal.data.id);
    console.log('Se ejecutará automáticamente cuando haya saldo suficiente');
    
    return deal.data;
    
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}
 
// Uso
await buyUSDC(50000); // Comprar USDC con 50,000 COP

Próximos Pasos

money-billOfframp - Vender Cripto

Vender criptomoneda por fiat

🧾Órdenes y Tipos

Comprender tipos de orden cripto

🧪Pruebas

Probar operaciones cripto en sandbox

📖Referencia API

Documentación completa de API