Onramp - Comprar Cripto

Convertir fiat a criptomoneda

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:

  1. Creas un deal ONRAMP por X cantidad de cripto
  2. El deal requiere Y fiat en tu cuenta virtual
  3. Cuando tu cuenta virtual recibe fondos (PAYIN, etc.), el deal se ejecuta automáticamente
  4. 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

Node.js
1// Comprar 10 USDC con COP
2
3// 1. Obtener cotización
4const quote = await axios.post(
5 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
6 {
7 type: 'ONRAMP',
8 originCurrencySymbol: 'COP',
9 destinationCurrencySymbol: 'USDC',
10 amountIn: 50000, // 50,000 COP
11 network: 'ETHEREUM' // Requerido para cotizaciones cripto
12 },
13 { headers: { 'Authorization': `Bearer ${token}` } }
14);
15
16console.log('Recibirás:', quote.data.amountOut, 'USDC'); // ej., 12.34 USDC
17console.log('Comisión de red:', quote.data.networkFee, 'COP');
18
19// 2. Crear deal (¡no orden!)
20const deal = await axios.post(
21 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
22 {
23 type: 'ONRAMP',
24 destinationAccountId: wallet.data.addresses.USDC,
25 quoteId: quote.data.id
26 },
27 { headers: { 'Authorization': `Bearer ${token}` } }
28);
29
30console.log('Deal ONRAMP creado:', deal.id);
31console.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:

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

Paso 2: Verificar Saldo Fiat

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

Paso 3: Obtener Cotización

Obtener Cotización
1const quote = await axios.post(
2 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
3 {
4 type: 'ONRAMP',
5 originCurrencySymbol: 'COP',
6 destinationCurrencySymbol: 'USDC',
7 amountIn: 50000,
8 network: 'ETHEREUM' // Requerido para cotizaciones cripto
9 },
10 { headers: { 'Authorization': `Bearer ${token}` } }
11);
12
13// Mostrar al usuario
14console.log('Tasa de cambio:', quote.data.exchangeRate);
15console.log('Recibirás:', quote.data.amountOut, 'USDC');
16console.log('Comisión Koywe:', quote.data.koyweFee, 'COP');
17console.log('Comisión de red:', quote.data.networkFee, 'COP');
18console.log('Costo total:', quote.data.amountIn + quote.data.koyweFee + quote.data.networkFee, 'COP');
19console.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.

Crear Deal
1const deal = await axios.post(
2 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
3 {
4 type: 'ONRAMP',
5 destinationAccountId: wallet.data.addresses.USDC, // Solo necesitas destino
6 quoteId: quote.data.id,
7 externalId: `onramp-${Date.now()}`
8 },
9 { headers: { 'Authorization': `Bearer ${token}` } }
10);
11
12console.log('Deal creado:', deal.data.id);
13console.log('Estado:', deal.data.status); // "PENDING"
14console.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

1// Vía webhooks (recomendado)
2app.post('/webhooks/koywe', (req, res) => {
3 const event = JSON.parse(req.body);
4
5 // Actualizaciones de estado del deal
6 if (event.type === 'deal.completed' && event.data.type === 'ONRAMP') {
7 console.log('¡Deal completado!');
8 console.log('ID del Deal:', event.data.id);
9 }
10
11 // Órdenes creadas por el deal
12 if (event.type === 'order.completed' && event.data.type === 'ONRAMP') {
13 console.log('¡Cripto recibida!');
14 console.log('ID de Orden:', event.data.id);
15 console.log('Monto:', event.data.amountOut, event.data.destinationCurrencySymbol);
16 }
17
18 res.status(200).send('OK');
19});

Redes Soportadas

CriptomonedaRedes
USDCEthereum, Polygon, BSC
USDTEthereum, Polygon, BSC, Tron
ETHEthereum
BTCBitcoin
MATICPolygon
BNBBSC

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


Ejemplo Completo

Comprar USDC
1async function buyUSDC(amount) {
2 try {
3 const token = await authenticate();
4
5 // 1. Verificar saldo COP
6 const balances = await getBalances(token, orgId, merchantId);
7 const copBalance = balances.find(b => b.currencySymbol === 'COP');
8
9 if (copBalance.availableBalance < amount) {
10 throw new Error('Saldo COP insuficiente');
11 }
12
13 // 2. Obtener dirección de billetera
14 const wallet = await axios.get(
15 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/wallet`,
16 { headers: { 'Authorization': `Bearer ${token}` } }
17 );
18
19 // 3. Obtener cotización
20 const quote = await axios.post(
21 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
22 {
23 type: 'ONRAMP',
24 originCurrencySymbol: 'COP',
25 destinationCurrencySymbol: 'USDC',
26 amountIn: amount,
27 network: 'ETHEREUM' // Requerido para cotizaciones cripto
28 },
29 { headers: { 'Authorization': `Bearer ${token}` } }
30 );
31
32 console.log(`Convirtiendo ${amount} COP a ${quote.data.amountOut} USDC`);
33 console.log(`Tasa: 1 USDC = ${quote.data.exchangeRate} COP`);
34 console.log('Cotización válida por:', quote.data.validFor || '10-15', 'segundos');
35
36 // 4. Crear deal (¡no orden!)
37 const deal = await axios.post(
38 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
39 {
40 type: 'ONRAMP',
41 destinationAccountId: wallet.data.addresses.USDC, // Solo necesitas destino
42 quoteId: quote.data.id
43 },
44 { headers: { 'Authorization': `Bearer ${token}` } }
45 );
46
47 console.log('Deal ONRAMP creado:', deal.data.id);
48 console.log('Se ejecutará automáticamente cuando haya saldo suficiente');
49
50 return deal.data;
51
52 } catch (error) {
53 console.error('Error:', error.response?.data || error.message);
54 throw error;
55 }
56}
57
58// Uso
59await buyUSDC(50000); // Comprar USDC con 50,000 COP

Próximos Pasos