Conceptos Clave

Órdenes y Tipos de Orden

Comprendiendo los seis tipos de orden y cuándo usar cada uno

Órdenes y Tipos de Orden

Las órdenes son las entidades de transacción centrales en Koywe Pagos. Cada tipo de orden sirve un propósito específico en tus operaciones de pago.

Resumen de Tipos de Orden

Koywe Pagos soporta seis tipos distintos de orden:

TipoPropósitoOrigenDestinoCaso de Uso
PAYINAceptar pagos de clientesExterna (cliente)Saldo virtualCheckout e-commerce
PAYOUTPagar proveedoresSaldo virtualExterna (banco proveedor)Pagos a vendedores
BALANCE_TRANSFERCambio de divisaSaldo virtual (moneda A)Saldo virtual (moneda B)Convertir COP a USD
ONRAMPComprar criptoSaldo virtual (fiat)Billetera criptoComprar USDC con COP
OFFRAMPVender criptoBilletera criptoSaldo virtual (fiat)Vender BTC por COP
PAYMENT_LINKEnlace de pagoExterna (cliente)Saldo virtualPago de factura

Ciclo de Vida del Estado de Orden

Todas las órdenes siguen una progresión de estado similar:

Descripciones de Estados:

EstadoDescripciónAcciones Disponibles
PENDINGOrden creada, esperando pagoCancelar, Verificar estado
PROCESSINGPago siendo procesadoVerificar estado
PAIDPago confirmado, liquidación en progresoVerificar estado
COMPLETEDFondos entregados, orden completaVer detalles
FAILEDPago o liquidación fallóReintentar, Contactar soporte
CANCELLEDOrden canceladaVer detalles
EXPIREDVentana de pago expiróCrear nueva orden

PAYIN - Aceptar Pagos de Clientes

Acepta pagos de clientes en tu saldo virtual.

Cuándo Usar

  • Checkout e-commerce
  • Pagos de servicios
  • Facturación de suscripciones
  • Pagos de facturas
  • Recolección de donaciones

Diagrama de Flujo

Campos Requeridos

1{
2 "type": "PAYIN", // Tipo de orden
3 "originCurrencySymbol": "COP", // Moneda fiat
4 "destinationCurrencySymbol": "COP", // Misma que origen
5 "amountIn": 50000, // Monto a cobrar
6 "description": "Pago por Orden #12345", // Descripción visible para cliente
7 "paymentMethods": [ // Al menos un método de pago
8 {
9 "method": "PSE", // Código de método de pago
10 "extra": "BANCOLOMBIA" // Datos adicionales (ej., banco)
11 }
12 ],
13 "successUrl": "https://tusitio.com/exitoso", // Redirección después de éxito
14 "failedUrl": "https://tusitio.com/fallido" // Redirección después de fallo
15}

Campos Opcionales

1{
2 "contactId": "cnt_abc123", // Vincular a contacto cliente
3 "externalId": "order-12345", // Tu referencia interna
4 "metadata": { "orderId": "12345" }, // Datos personalizados
5 "dueDate": "2025-11-14T23:59:59Z" // Fecha límite de pago
6}

Ejemplo

Node.js
1async function createPayinOrder(token, orgId, merchantId) {
2 const response = await axios.post(
3 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
4 {
5 type: 'PAYIN',
6 originCurrencySymbol: 'COP',
7 destinationCurrencySymbol: 'COP',
8 amountIn: 50000,
9 description: 'Pago por Orden #12345',
10 externalId: `order-${Date.now()}`,
11 paymentMethods: [
12 {
13 method: 'PSE',
14 extra: 'BANCOLOMBIA'
15 }
16 ],
17 successUrl: 'https://tusitio.com/exitoso',
18 failedUrl: 'https://tusitio.com/fallido'
19 },
20 {
21 headers: {
22 'Authorization': `Bearer ${token}`,
23 'Content-Type': 'application/json'
24 }
25 }
26 );
27
28 return response.data;
29}
30
31const order = await createPayinOrder(token, orgId, merchantId);
32console.log('URL de Pago:', order.paymentUrl);
33// Redirige al cliente a order.paymentUrl

Guía Completa de Integración PAYIN →


PAYOUT - Pagar Proveedores

Envía pagos desde tu saldo virtual a cuentas bancarias externas.

Cuándo Usar

  • Pagos a vendedores
  • Pagos a contratistas
  • Reembolsos a clientes
  • Comisiones de afiliados
  • Liquidaciones con socios

Diagrama de Flujo

Campos Requeridos

1{
2 "type": "PAYOUT", // Tipo de orden
3 "originCurrencySymbol": "COP", // Moneda fiat
4 "destinationCurrencySymbol": "COP", // Misma que origen
5 "amountIn": 100000, // Monto a enviar
6 "destinationAccountId": "ba_xyz789", // ID cuenta bancaria proveedor
7 "description": "Pago por Factura #456" // Descripción interna
8}

Campos Opcionales

1{
2 "contactId": "cnt_provider123", // Vincular a contacto proveedor
3 "externalId": "invoice-456", // Tu referencia interna
4 "metadata": { "invoiceId": "456" } // Datos personalizados
5}

Ejemplo

Node.js
1async function createPayoutOrder(token, orgId, merchantId, contactId, bankAccountId) {
2 // 1. Verificar saldo primero
3 const balances = await getMerchantBalances(token, orgId, merchantId);
4 const copBalance = balances.find(b => b.currencySymbol === 'COP');
5
6 if (copBalance.availableBalance < 100000) {
7 throw new Error('Saldo insuficiente');
8 }
9
10 // 2. Crear orden de payout
11 const response = await axios.post(
12 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
13 {
14 type: 'PAYOUT',
15 originCurrencySymbol: 'COP',
16 destinationCurrencySymbol: 'COP',
17 amountIn: 100000,
18 contactId: contactId,
19 destinationAccountId: bankAccountId,
20 description: 'Pago por Factura #456',
21 externalId: `invoice-456-${Date.now()}`
22 },
23 {
24 headers: {
25 'Authorization': `Bearer ${token}`,
26 'Content-Type': 'application/json'
27 }
28 }
29 );
30
31 return response.data;
32}
33
34const payout = await createPayoutOrder(token, orgId, merchantId, 'cnt_provider', 'ba_xyz789');
35console.log('Payout creado:', payout.id);

Importante: Siempre verifica el saldo de tu cuenta virtual antes de crear órdenes PAYOUT. La orden fallará si tienes fondos insuficientes.

Guía Completa de Integración PAYOUT →


BALANCE_TRANSFER - Cambio de Divisa

Transfiere fondos entre diferentes cuentas virtuales de moneda (cambio de divisa instantáneo).

Cuándo Usar

  • Convertir COP a USD para pagos internacionales
  • Rebalancear tenencias de moneda
  • Bloquear tasas de cambio
  • Preparar fondos para pagos en moneda específica

Diagrama de Flujo

Campos Requeridos

1{
2 "type": "BALANCE_TRANSFER", // Tipo de orden
3 "originCurrencySymbol": "COP", // Moneda origen
4 "destinationCurrencySymbol": "USD", // Moneda destino
5 "amountIn": 1000000 // Monto a convertir (1M COP)
6}

Ejemplo

Node.js
1async function transferCurrency(token, orgId, merchantId) {
2 // 1. Obtener cotización para tasa de cambio
3 const quote = await axios.post(
4 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
5 {
6 type: 'BALANCE_TRANSFER',
7 originCurrencySymbol: 'COP',
8 destinationCurrencySymbol: 'USD',
9 amountIn: 1000000
10 },
11 { headers: { 'Authorization': `Bearer ${token}` } }
12 );
13
14 console.log('Tasa de cambio:', quote.data.exchangeRate);
15 console.log('Recibirás:', quote.data.amountOut, 'USD');
16
17 // 2. Crear orden de transferencia
18 const response = await axios.post(
19 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
20 {
21 type: 'BALANCE_TRANSFER',
22 originCurrencySymbol: 'COP',
23 destinationCurrencySymbol: 'USD',
24 amountIn: 1000000,
25 quoteId: quote.data.id // Usar cotización para bloquear tasa
26 },
27 { headers: { 'Authorization': `Bearer ${token}` } }
28 );
29
30 return response.data;
31}
32
33const transfer = await transferCurrency(token, orgId, merchantId);
34console.log('Transferencia completada instantáneamente:', transfer.status); // "COMPLETED"

Liquidación Instantánea: Las órdenes BALANCE_TRANSFER se completan instantáneamente. Sin esperar confirmaciones externas.

Guía Completa de Transferencias de Saldo →


ONRAMP - Comprar Criptomoneda

Convierte moneda fiat a criptomoneda.

Usa Endpoint de Deals: Las operaciones ONRAMP usan el endpoint /deals. Los deals pueden pagarse completa o parcialmente, y cada pago crea órdenes que ejecutan la compra de cripto.

Cuándo Usar

  • Comprar cripto para tesorería
  • Ofrecer compras de cripto a usuarios
  • Cobertura con stablecoins
  • Pagar proveedores nativos en cripto

Criptomonedas Soportadas

SímboloNombreRedes
USDCUSD CoinEthereum, Polygon, BSC
USDTTetherEthereum, Polygon, BSC
ETHEthereumEthereum
BTCBitcoinBitcoin
MATICPolygonPolygon
BNBBNBBSC

Campos Requeridos para Cotización

1{
2 "type": "ONRAMP",
3 "originCurrencySymbol": "COP", // Moneda fiat
4 "destinationCurrencySymbol": "USDC", // Moneda cripto
5 "amountIn": 50000 // Monto fiat
6}

Campos Requeridos para Deal

1{
2 "type": "ONRAMP",
3 "destinationAccountId": "wallet_abc123", // ID billetera cripto
4 "quoteId": "quote_xyz789" // ID cotización
5}

Simplificado: Los deals solo necesitan la cuenta de destino y el ID de cotización. Los montos y monedas vienen de la cotización.

Ejemplo

Node.js
1async function buyUSDC(token, orgId, merchantId, walletId) {
2 // 1. Obtener cotización
3 const quote = await axios.post(
4 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
5 {
6 type: 'ONRAMP',
7 originCurrencySymbol: 'COP',
8 destinationCurrencySymbol: 'USDC',
9 amountIn: 50000
10 },
11 { headers: { 'Authorization': `Bearer ${token}` } }
12 );
13
14 console.log('Recibirás:', quote.data.amountOut, 'USDC');
15 console.log('Tasa de cambio:', quote.data.exchangeRate);
16 console.log('Comisión de red:', quote.data.networkFee);
17
18 // 2. Crear deal (¡no orden!)
19 const response = await axios.post(
20 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
21 {
22 type: 'ONRAMP',
23 destinationAccountId: walletId,
24 quoteId: quote.data.id
25 },
26 { headers: { 'Authorization': `Bearer ${token}` } }
27 );
28
29 return response.data;
30}
31
32const deal = await buyUSDC(token, orgId, merchantId, 'wallet_abc123');
33console.log('Deal ONRAMP creado:', deal.id);
34console.log('El deal puede pagarse completa o parcialmente');

Pagos Parciales: Los deals ONRAMP pueden pagarse en múltiples cuotas. Cada pago crea una orden que compra la cantidad proporcional de cripto. ¡Ideal para promedio de costo en dólares!

Saldo Requerido: Por defecto, se requiere saldo suficiente en tu cuenta virtual para cerrar un deal ONRAMP. Los deals se ejecutan automáticamente cuando se acreditan fondos a tu cuenta. Los comercios pre-aprobados pueden operar sin saldo inicial.

Guía Completa ONRAMP →


OFFRAMP - Vender Criptomoneda

Convierte criptomoneda a moneda fiat.

Usa Endpoint de Deals: Las operaciones OFFRAMP usan el endpoint /deals. A diferencia de ONRAMP, los deals OFFRAMP deben pagarse completamente (sin pagos parciales). El deal crea órdenes cuando está completamente financiado.

Cuándo Usar

  • Vender tenencias de cripto
  • Convertir pagos cripto a fiat
  • Realizar ganancias cripto
  • Preparar fiat para operaciones

Campos Requeridos para Cotización

1{
2 "type": "OFFRAMP",
3 "originCurrencySymbol": "USDC", // Moneda cripto
4 "destinationCurrencySymbol": "COP", // Moneda fiat
5 "amountIn": 10 // Monto cripto (10 USDC)
6}

Campos Requeridos para Deal

1{
2 "type": "OFFRAMP",
3 "destinationAccountId": "va_cop_12345", // ID cuenta virtual
4 "quoteId": "quote_xyz789" // ID cotización
5}

Solo Pago Completo: Los deals OFFRAMP deben financiarse completamente. No se soportan pagos parciales.

Ejemplo

Node.js
1async function sellUSDC(token, orgId, merchantId) {
2 // 1. Obtener cotización
3 const quote = await axios.post(
4 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
5 {
6 type: 'OFFRAMP',
7 originCurrencySymbol: 'USDC',
8 destinationCurrencySymbol: 'COP',
9 amountIn: 10 // 10 USDC
10 },
11 { headers: { 'Authorization': `Bearer ${token}` } }
12 );
13
14 console.log('Recibirás:', quote.data.amountOut, 'COP');
15
16 // 2. Crear deal (¡no orden!)
17 const response = await axios.post(
18 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
19 {
20 type: 'OFFRAMP',
21 destinationAccountId: 'va_cop_12345', // Cuenta virtual para COP
22 quoteId: quote.data.id
23 },
24 { headers: { 'Authorization': `Bearer ${token}` } }
25 );
26
27 return response.data;
28}
29
30const deal = await sellUSDC(token, orgId, merchantId);
31console.log('Deal OFFRAMP creado:', deal.id);
32console.log('Dirección de depósito:', deal.depositAddress);
33console.log('Envía el monto completo de cripto para completar');
34// Los fondos se acreditarán a la cuenta virtual COP después de recibir el cripto

Financiamiento Completo: Después de crear el deal, debes enviar el monto completo de cripto a la dirección de depósito proporcionada. Una vez recibido, el deal crea órdenes y acredita tu cuenta virtual con fiat.

Guía Completa OFFRAMP →


Genera enlaces de pago compartibles con un flujo de checkout completo de marca Koywe - ¡sin necesidad de contacto o método de pago por adelantado!

Sin Contacto Requerido

El cliente ingresa su propia información en el checkout

Sin Método de Pago

El cliente selecciona su método de pago preferido

UI de Marca Koywe

Hermoso checkout seguro alojado por Koywe

Compartir en Cualquier Lugar

Envía vía email, WhatsApp, SMS o código QR

Cuándo Usar

  • Checkout e-commerce: Colección de pagos simple sin integración compleja
  • Pagos de facturas: Envía enlace de pago para facturas emitidas
  • Email/WhatsApp: Comparte solicitudes de pago directamente
  • Pagos con QR: Genera QR para pagos en persona
  • Colecciones únicas: Solicitudes de pago rápidas sin almacenar datos del cliente

Cómo Funciona

Diferencias con PAYIN

CaracterísticaPAYINPAYMENT_LINK
ContactoOpcional pero recomendadoNo necesario - cliente ingresa datos
Método de PagoDebe especificarseCliente selecciona de todos disponibles
UI de CheckoutRedirige a proveedor de pagoFlujo de checkout de marca Koywe
Recolección de DatosTú recolectas datos del clienteKoywe recolecta datos del cliente
Mejor ParaExperiencia de checkout integradaSolicitudes de pago independientes

Campos Mínimos Requeridos

¡Eso es todo! Sin contacto, sin método de pago, sin detalles del cliente necesarios. Solo monto y descripción.

1{
2 "type": "PAYMENT_LINK", // Tipo de orden
3 "originCurrencySymbol": "COP", // Moneda
4 "destinationCurrencySymbol": "COP", // Igual que origen
5 "amountIn": 75000, // Monto a cobrar
6 "description": "Factura #789" // Muestra al cliente
7}

Campos Opcionales

1{
2 "dueDate": "2025-11-14T23:59:59Z", // Expiración del enlace
3 "externalId": "invoice-789", // Tu referencia
4 "successUrl": "https://tusite.com/exitoso", // Redireccionar después de pago
5 "failedUrl": "https://tusite.com/fallido" // Redireccionar en fallo
6}

Ejemplo Completo

1// Ejemplo mínimo - ¡solo crear y compartir!
2async function createPaymentLink(amount, description) {
3 const response = await axios.post(
4 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
5 {
6 type: 'PAYMENT_LINK',
7 originCurrencySymbol: 'COP',
8 destinationCurrencySymbol: 'COP',
9 amountIn: amount,
10 description: description
11 },
12 { headers: { 'Authorization': `Bearer ${token}` } }
13 );
14
15 return response.data;
16}
17
18// Uso
19const link = await createPaymentLink(75000, 'Factura #789 - Diseño Web');
20console.log('Comparte este enlace:', link.paymentUrl);
21
22// Enviar vía email, WhatsApp, SMS o generar código QR
23await sendEmail(customerEmail, {
24 subject: 'Solicitud de Pago - Factura #789',
25 body: `Por favor paga aquí: ${link.paymentUrl}`
26});

Respuesta:

1{
2 "id": "ord_abc123",
3 "type": "PAYMENT_LINK",
4 "status": "PENDING",
5 "paymentUrl": "https://checkout.koywe.com/pay/ord_abc123",
6 "amountIn": 75000,
7 "originCurrencySymbol": "COP",
8 "description": "Factura #789 - Diseño Web",
9 "createdAt": "2025-11-13T15:00:00Z"
10}

Experiencia del Cliente: Cuando los clientes abren el enlace de pago, verán un checkout de marca Koywe donde pueden:

  1. Revisar detalles del pago
  2. Ingresar su información personal
  3. Seleccionar su método de pago preferido (PSE, PIX, Nequi, etc.)
  4. Completar el pago

Metadata de Orden e IDs Externos

ID Externo (Idempotencia)

Usa externalId para asegurar creación de orden idempotente:

1{
2 "externalId": "order-12345-20251113" // Tu identificador único
3}

Beneficios:

  • Seguro reintentar solicitudes fallidas
  • Previene órdenes duplicadas
  • Vincula a tus sistemas internos

Metadata

Almacena datos personalizados con órdenes:

1{
2 "metadata": {
3 "orderId": "12345",
4 "customerId": "cust_67890",
5 "source": "mobile_app",
6 "campaign": "summer_sale"
7 }
8}

Casos de uso:

  • Rastrear origen de orden
  • Almacenar información de campaña
  • Vincular a sistemas internos
  • Campos de reportes personalizados

Próximos Pasos