Comienza Acá con Koywe Payments API

Esta guía proporciona un recorrido completo para integrar con la API de Koywe Payments. El proceso de integración sigue un enfoque de dos fases para acomodar tanto a usuarios de dashboard como a desarrolladores.

Resumen

El proceso de integración de Koywe involucra dos fases principales:

Dashboard/Frontend Setup - Los usuarios de dashboard reciben acceso a la organización y gestionan comercios a través de nuestra interfaz web
API Integration - Los desarrolladores implementan acceso programático utilizando credenciales proporcionadas y endpoints recomendados

Flujo de Integración

Parte 1: Configuración de Dashboard/Frontend

Esta sección guía a los usuarios de dashboard a través del proceso de configuración inicial utilizando la interfaz de dashboard de Koywe.

Requisitos Previos

Correo electrónico de invitación de organización del equipo de Koywe
Acceso a tu correo electrónico de organización para recibir y aceptar invitaciones
Comprensión básica de las necesidades de la estructura de comercios de tu organización

Paso 1: Configuración de Usuario Root de Organización

Recibir y Aceptar la Invitación de Organización

El equipo de Koywe enviará una invitación de organización a tu dirección de correo electrónico principal. Esta invitación proporciona acceso root a toda tu organización dentro de la plataforma Koywe.

Proceso:

Recibir correo electrónico de invitación del equipo de Koywe
Hacer clic en el enlace de invitación y completar el registro/inicio de sesión
Aceptar la invitación de organización para obtener acceso
Acceder al dashboard de Koywe con permisos root

Comprender los Permisos Root de Organización

Como usuario root de organización, tienes acceso administrativo completo, incluyendo:

Gestión de comercios (crear, ver, editar, eliminar)
Gestión de usuarios en todos los comercios
Configuración de ajustes a nivel de organización
Generación y gestión de credenciales de API

Paso 2: Creación y Gestión de Comercios/Merchants

Crear Comercios/Merchants a través del Dashboard

Proceso:

Navegar a la sección de gestión de comercios/merchants
Crear nuevo comerciante/merchant con detalles comerciales
Configurar ajustes específicos del comerciante/merchant
Revisar recursos creados automáticamente por defecto

Comprender los Recursos Por Defecto

Cuando creas un comercio/merchant, el sistema crea automáticamente:

Cuentas Virtuales:

Cuentas de pago para mantener temporalmente los pagos entrantes
Cuentas de pago para gestionar los pagos salientes
Cuentas de liquidación para el procesamiento final de fondos

Contacto Por Defecto:

Información de contacto que coincide con los detalles del comerciante
Utilizado para el informe de transacciones y cumplimiento
Representa al comerciante en informes y comunicaciones

Paso 3: Gestión de Usuarios

Invitar Usuarios a Comercios/Merchants

Proceso:

Seleccionar el comercio/merchant objetivo
Navegar a la gestión de usuarios
Enviar invitaciones con asignaciones de roles apropiadas
Monitorizar el estado de la invitación y el acceso del usuario

Asignación de Permisos

Conceptos Clave:

Crear usuario automáticamente recibe permisos root sobre el nuevo comerciante
Esto evita que los comercios sin permisos de usuario tengan acceso a ningún comerciante
Los usuarios root de organización mantienen acceso a todos los comercios
Los permisos pueden modificarse posteriormente a través del dashboard o de la API

Parte 2: Integración de API

Esta sección proporciona orientación para los desarrolladores implementando la integración de API con el sistema de Koywe Payments.

Requisitos Previos

Antes de comenzar la integración de API, asegúrate de tener:

Clave y secreto de API proporcionados por el equipo de Koywe
ID de Organización proporcionado por el equipo de Koywe
Entorno de desarrollo configurado para pruebas de API

Paso 1: Configuración de Autenticación

Credenciales de API

Tu integración usará:

Clave y secreto de API para la autenticación
ID de Organización para el ámbito de las operaciones
Token de portador para solicitudes de API

Flujo de Autenticación

Proceso:

Usar la clave y secreto de API para autenticarse
Recibir token de portador para solicitudes posteriores
Incluir token en todas las solicitudes de API
Implementar lógica de actualización de token según sea necesario

Paso 2: Flujo de Integración de API Recomendado

El equipo de Koywe recomienda seguir esta secuencia para una integración óptima:

Gestión de Invitaciones de Organización

Propósito: Invitar a usuarios a tu organización programáticamente

Enviar invitaciones a usuarios root de organización
Proporcionar acceso al dashboard para la gestión frontend
Asignar roles apropiados a nivel de organización

Creación de Comercios/Merchants

Propósito: Crear comercios/merchants bajo tu organización a través de la API

Definir detalles comerciales del comerciante/merchant
Configurar ajustes del comerciante/merchant programáticamente
Crear cuentas virtuales y contactos por defecto automáticamente

Invitaciones de Usuarios a Comercios/Merchants

Propósito: Invitar a usuarios a comercios/merchants específicos

Enviar invitaciones dirigidas para el acceso específico a comercios
Asignar roles y permisos a nivel de comerciante
Habilitar la gestión de comercios enfocada

Generación de Credenciales de API

Propósito: Generar credenciales de API para comercios

Crear claves API específicas para comercios
Habilitar operaciones API con ámbito de comerciante
Soportar diferentes tipos y permisos de credenciales

Paso 3: Comprender la Creación de Recursos Por Defecto

Creación Automática de Recursos

Cuando creas comercios/merchants a través de la API, el sistema proporciona automáticamente:

Cuentas Virtuales:

Múltiples tipos de cuenta para diferentes flujos de pago
Soporte para múltiples monedas
Seguimiento y generación de informes de balance automáticos

Contactos Por Defecto:

Información de contacto del comerciante
Integración con el informe de transacciones
Documentación de cumplimiento y regulación

Herencia de Permisos

Conceptos Clave:

Las operaciones de API heredan los permisos de usuario
El acceso a nivel de organización permite la creación de comercios
Los creadores de comercios reciben automáticamente permisos de comerciante
Los permisos pueden modificarse posteriormente después de la creación

Paso 4: Consideraciones de Implementación

Configuración del Entorno

Entorno de Desarrollo:

Usar entorno de pruebas para pruebas
Separar credenciales de producción
Probar el flujo de integración completo

Entorno de Producción:

Usar credenciales de API de producción
Implementar manejo de errores apropiado
Monitorizar el uso y rendimiento de la API

Mejores Prácticas

Seguridad:

Almacenar credenciales de forma segura
Usar HTTPS para todas las comunicaciones de API
Implementar manejo de tokens apropiado

Manejo de Errores:

Manejar fallas de autenticación
Gestionar límites de tasa de API
Implementar lógica de reintento para fallas transitorias

Testing:

Probar el flujo de integración completo
Verificar la creación de recursos y permisos
Validar escenarios de error

Próximos Pasos

Después de completar esta guía de configuración:

Procesamiento de Pagos: Revisar los endpoints específicos de creación y procesamiento de pagos
Integración de Webhook: Configurar manejadores de webhook para notificaciones en tiempo real
Configuración Avanzada: Explorar características y opciones de personalización adicionales de la API
Implementación en Producción: Implementar medidas de seguridad y monitoreo para el uso en producción

Recursos Adicionales

Documentación de API Reference

Para soporte adicional, contacta al equipo de desarrollo de Koywe a través de Slack o a contacto@koywe.com o consulta nuestra documentación de API completa.