Conceptos Clave

Antes de integrar con Koywe Pagos, es importante comprender los conceptos clave que forman la base de nuestro sistema.

La Jerarquía

Koywe Pagos está construido sobre una estructura jerárquica que te permite gestionar múltiples unidades de negocio y monedas eficientemente:

Esta estructura te permite:

• Gestionar múltiples unidades de negocio (comercios) bajo una organización
• Mantener cuentas virtuales separadas para cada moneda
• Rastrear todas las transacciones y órdenes por comercio
• Asignar diferentes permisos y niveles de acceso

---

Entidades Clave

Organizaciones

Tu Organización es la entidad de nivel superior que representa tu empresa en el sistema Koywe.

• Una organización puede contener múltiples comercios
• Gestiona configuraciones y usuarios a nivel empresa
• Controla credenciales API y permisos
• Maneja facturación y reportes a nivel organización

Aprende más sobre Organizaciones →

Comercios

Un Comercio representa una unidad de negocio individual o marca dentro de tu organización.

• Cada comercio tiene sus propias cuentas virtuales
• Seguimiento de transacciones separado por comercio
• Procesamiento de pagos independiente
• Útil para empresas multi-marca o franquicias

Aprende más sobre Comercios →

Cuentas Virtuales

Cuentas Virtuales son cuentas de saldo multi-moneda que mantienen tus fondos dentro del sistema Koywe.

• Una cuenta virtual por moneda por comercio
• Creadas automáticamente cuando creas un comercio
• Usadas para operaciones PAYIN, PAYOUT y transferencias
• Seguimiento de saldo en tiempo real

Aprende más sobre Cuentas Virtuales →

Contactos

Contactos representan a tus clientes o proveedores en el sistema.

• Almacenar información de cliente/proveedor
• Vincular cuentas bancarias para pagos
• Rastrear historial de pagos
• Gestionar datos KYC/cumplimiento

Aprende más sobre Contactos →

Órdenes

Órdenes son las entidades de transacción centrales en Koywe Pagos.

• Seis tipos de orden: PAYIN, PAYOUT, BALANCE_TRANSFER, ONRAMP, OFFRAMP, PAYMENT_LINK
• Rastrear estado del pago a través del ciclo de vida
• Vincular a contactos y cuentas virtuales
• Generar webhooks para cambios de estado

Aprende más sobre Órdenes →

Cotizaciones

Cotizaciones proporcionan bloqueos de tasa de cambio para conversiones de moneda.

• Obtener tasas de cambio en tiempo real
• Bloquear tasas por un período de tiempo específico
• Usar en órdenes para precios transparentes
• Opcional pero recomendado para transparencia con el cliente

Aprende más sobre Cotizaciones →

---

Cómo Trabajan Juntos

Ejemplo: Aceptar un Pago

El flujo:

1. Tu aplicación crea una orden para un Comercio específico
2. La orden se vincula a un Contacto (el cliente)
3. El cliente paga usando un Método de Pago
4. Los fondos se acreditan a la Cuenta Virtual del comercio
5. Recibes notificaciones webhook sobre los cambios de estado de la Orden

Ejemplo: Pagar a un Proveedor

El flujo:

1. Verificas el saldo de tu Cuenta Virtual
2. Creas una orden PAYOUT para un Contacto (proveedor)
3. Los fondos se debitan de tu Cuenta Virtual
4. Transferidos a la cuenta bancaria del proveedor
5. Recibes confirmación por webhook

---

Flujo de Integración Típico

Cuando integras Koywe Pagos, típicamente seguirás estos pasos:

---

Comprendiendo Tipos de Orden

Cada tipo de orden sirve un propósito específico en el flujo de pago:

Guía detallada para cada tipo de orden →

---

Flujo de Saldo de Cuenta Virtual

Comprendiendo cómo se mueve el dinero a través de las cuentas virtuales:

Las cuentas virtuales actúan como el hub central para todas tus operaciones de pago:

• Recibir fondos de pagos de clientes (PAYIN)
• Mantener saldos en múltiples monedas
• Fuente para pagos a proveedores (PAYOUT)
• Fuente para compras de cripto (ONRAMP)
• Destino para ventas de cripto (OFFRAMP)
• Habilitar transferencias de moneda instantáneas

---

Relaciones de Datos

Comprendiendo cómo las entidades se relacionan entre sí:

---

Próximos Pasos

Ahora que comprendes los conceptos clave, profundiza en cada tema: