Ó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:
Ciclo de Vida del Estado de Orden
Todas las órdenes siguen una progresión de estado similar:
Descripciones de Estados:
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
Campos Opcionales
Ejemplo
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
Campos Opcionales
Ejemplo
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
Ejemplo
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
Campos Requeridos para Cotización
Campos Requeridos para Deal
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
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.
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
Campos Requeridos para Deal
Solo Pago Completo: Los deals OFFRAMP deben financiarse completamente. No se soportan pagos parciales.
Ejemplo
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.
PAYMENT_LINK - Enlaces de Pago
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!
¿Qué Hace Especial a PAYMENT_LINK?
El cliente ingresa su propia información en el checkout
El cliente selecciona su método de pago preferido
Hermoso checkout seguro alojado por Koywe
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
Campos Mínimos Requeridos
¡Eso es todo! Sin contacto, sin método de pago, sin detalles del cliente necesarios. Solo monto y descripción.
Campos Opcionales
Ejemplo Completo
Respuesta:
Experiencia del Cliente: Cuando los clientes abren el enlace de pago, verán un checkout de marca Koywe donde pueden:
- Revisar detalles del pago
- Ingresar su información personal
- Seleccionar su método de pago preferido (PSE, PIX, Nequi, etc.)
- Completar el pago
Metadata de Orden e IDs Externos
ID Externo (Idempotencia)
Usa externalId para asegurar creación de orden idempotente:
Beneficios:
- Seguro reintentar solicitudes fallidas
- Previene órdenes duplicadas
- Vincula a tus sistemas internos
Metadata
Almacena datos personalizados con órdenes:
Casos de uso:
- Rastrear origen de orden
- Almacenar información de campaña
- Vincular a sistemas internos
- Campos de reportes personalizados