Pasos de Integración

Esta documentación describe los elementos clave para la integración fluida con la plataforma de Adquirencia como Servicio (AaaS) de Akua. El proceso abarca desde el acuerdo inicial hasta las operaciones técnicas de autenticación y conectividad, asegurando un correcto funcionamiento para su empresa.

1- Firma del contrato y Kickoff del Proyecto

En primer lugar, se formaliza el acuerdo con Akua para acceder a todos los servicios.
Posteriormente, se inicia la colaboración con una reunión de Kickoff, cuyo objetivo es alinear expectativas, objetivos y equipos, y definir el alcance preciso del proyecto. Esta etapa es el punto de partida para asegurar un inicio exitoso, con una ruta acelerada de kickoff a producción de aproximadamente 14 días.

2- Acceso al Dashboard y Configuración de Administrador

Para comenzar con el onboarding, el equipo de Akua enviará un correo electrónico de invitación con un enlace para registrarse como administrador en nuestro Dashboard de Autogestión.
Este paso es clave para garantizar un acceso seguro y centralizado a la plataforma por parte de su equipo, y le permitirá registrarse como administrador para configurar su cuenta.
Una vez que acceda a la URL del Dashboard, deberá ingresar su Company ID (que generalmente es su dominio) y podrá iniciar sesión con el usuario y contraseña que haya creado.
Desde el Dashboard, podrá gestionar usuarios y definir roles como Administrador, Developer, Finanzas, Fraude y Operaciones.

3- Obtención de API Keys y Generación de Tokens

Las credenciales necesarias para interactuar con la API (los API Keys) se obtienen directamente desde el Dashboard de Akua, en la sección Developers > API Keys.
Allí generará un par de credenciales: el Client ID y el Client Secret, además de seleccionar los permisos (scopes) requeridos para su integración.
Estos datos son esenciales para la autenticación. Para poder consumir nuestros servicios y APIs, deberá utilizar el endpoint de autenticación (POST https://sandbox.akua.la/oauth/token) para generar un token JWT con estas credenciales.
Este token de acceso se debe pasar como Bearer Token en el header de cada solicitud API posterior. Recuerde implementar la lógica de refresh del token, ya que el token generado tiene una duración de 24 horas.

4- Entornos de Desarrollo y Homologación

La plataforma Akua está diseñada para una integración sencilla a través de APIs, utilizando dos entornos principales:
- Sandbox: Es el entorno pre-productivo. Se utiliza para realizar todas las pruebas durante la fase de implementación. Las operaciones en este ambiente no afectan los datos en vivo, la contabilidad ni las métricas (los datos utilizados son simulados/falsos). La Base URL para este entorno es https://sandbox.akua.la.
- Producción: Es el entorno donde ocurren las operaciones reales y se afecta la contabilidad. Una vez completadas todas las pruebas y validado el checklist de homologación, se migra a este ambiente. La Base URL es https://api.akua.la.
Durante el proceso de integración, se valida un checklist de homologación que cubre la Base Técnica (JWT, API Keys, Webhooks), E-commerce (Autorizaciones, Capturas, Reembolsos) y Tarjeta Presente (si aplica).
Es importante configurar timeouts (20s recomendado) y utilizar el header Idempotency-Key en todos los requests para gestionar duplicidades y reintentos.

Elementos claves de la Integración

La plataforma de Akua opera bajo una estructura jerárquica modular:

Clientes: Representan a las empresas u organizaciones que utilizan las soluciones de adquirencia financiera de Akua, buscando simplificar sus operaciones y aprovechar el avance tecnológico.
Organizaciones: Es una forma lógica de organizar los diferentes merchants. Por defecto, cada cliente tendrá una organización "default" para agrupar a sus comercios.
Merchants/Submerchants: Los merchants representan los comercios principales que recibirán los pagos electrónicos. Un merchant puede gestionar varios submerchants (comercios más específicos, como sucursales o franquicias).
Instrumentos: Representan las tarjetas y otros instrumentos de pago. La creación de un instrumento genera un identificador único e irreversible, asociado a la tarjeta, lo cual permite acceder y ejecutar acciones sobre la misma de forma segura (tokenización).
Payments/Transacciones: El Payment es el ciclo de vida completo de una transacción, englobando todas las operaciones asociadas (autorización, captura, cancelación o devolución). Los comercios reciben los pagos iniciados por consumidores a través de tarjetas de crédito/débito o métodos digitales.

Herramientas y Soporte

Para facilitar la integración, ofrecemos una plataforma 100% accesible a través de APIs, documentación completamente en línea, y un Sandbox gratuito.

Herramientas para Desarrolladores: Ponemos a su disposición colecciones de Postman (Postman Collections) y herramientas como nuestro Módulo de Integración Rápida (MCP) para acelerar el tiempo de lanzamiento al mercado.
Guía de Pruebas: Proporcionamos números de Tarjetas de Prueba que simulan escenarios reales de autorización, aprobación y rechazo para que pueda validar el comportamiento del flujo de pagos antes de salir a producción.
Soporte Proactivo 24/7: Nuestro modelo de soporte comienza con la Autogestión a través de la documentación y el Help Center, seguida por nuestro Agente de Inteligencia Artificial (FIN), que tiene contexto de todos los recursos y es el primero en responder las consultas. Si es necesario, puede escalar a Agentes humanos y, en casos críticos, se activa una Escalación interna para garantizar la celeridad en la resolución.