Integración del método de pago
9 min
A continuación, se describe el flujo de comunicación y las reglas de negocio para integrar Addi como método de pago en un e-commerce.
Notas generales:
- Ambientes: Addi cuenta con entornos de Staging y Producción. Las credenciales de Staging se solicitan a [email protected]. Las de Producción son únicas e intransferibles y se entregan tras la certificación de la integración.
- Idempotencia: Los recursos HTTP de la API son idempotentes (garantizan que un crédito se origina solo una vez) y permiten reintentos seguros en caso de fallos 5xx.
- Moneda y Documento: Solo se opera en Pesos Colombianos (COP) y con personas naturales (Tipo de documento CC).
Flujo de la Integración
1. Verificación de Montos y Descuentos (Config Endpoint)
En el checkout, al listar los métodos de pago, se debe consumir este endpoint para determinar si Addi debe estar disponible y si aplica algún descuento visual.
- Endpoint: GET https://channels-public-api.addi.com/allies/ally_slug/config?requestedamount=xxxx (Reemplazar ally_slug y xxxx con los datos correspondientes del comercio).
- Ejemplo
Get Config
Obtener configuración del comercio con el ally slug y el monto para solicitar el crédito
GET
https://channels-public-api.addi.com/allies/ally_slug/config?requestedamount=xxxx
curl --location 'https://channels-public-api.addi.com/allies/miallyslug/config?requestedamount=80000' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'- Manejo de topes: Si el monto del carrito está fuera del rango permitido (minAmount y maxAmount), no se recomienda ocultar el método de pago. Lo ideal es deshabilitarlo y mostrar un disclaimer (ej. "Aplica solo para compras entre X y Y"). Esta práctica es directa, resuelve dudas y fomenta que el cliente agregue más productos al carrito para alcanzar el monto mínimo.
- Manejo de descuentos: El valor de discount es puramente visual (ej. 0.02 = 2%). No se debe modificar el valor total aplicando el descuento antes de enviar la petición. Se debe enviar el monto original en la solicitud de transacción; Addi se encarga de aplicar el descuento internamente según la negociación.
2. Autenticación
La seguridad se maneja vía Addi Auth con autenticación OAuth(IdaaS). Se requiere obtener un JSON Web Token (JWT) antes de consumir los demás endpoints.
- Documentación: API Auth Docs
- Mejor práctica: Se debe generar un token nuevo por cada intento de transacción. Reutilizar un mismo token para múltiples transacciones simultáneas puede causar errores debido a tiempos de expiración cruzados.
3. Creación de la Aplicación (Transacción)
Este endpoint se utiliza para iniciar el proceso de pago. La transacción se creará inicialmente en estado "pendiente".
- Documentación: Create Online Loan Application
- Order ID: Es posible usar cualquier formato (UUID, números, letras), pero debe ser único por cada intento de compra. Si una persona falla o abandona el proceso y vuelve a intentar con el mismo carrito, se debe generar y enviar un Order ID distinto.
- Redirección (Status 301): El endpoint devuelve un estado HTTP 301 (sin body) con un header Location que contiene la URL de Addi.
🛑 Importante sobre la redirección: Muchos frameworks siguen el redireccionamiento 301 de manera automática, lo que suele resultar en pérdida de parámetros o en un falso status 200. Para un comportamiento estable, se sugiere desactivar la redirección automática en el código, capturar el status 301 y usar la URL provista para redirigir al cliente manualmente.
4. Reporte de Resultado (Webhook / Callback) y Redirección
Addi notificará al servidor del comercio el estado final de la transacción de forma asíncrona, previo a devolver al cliente al e-commerce. Los tiempos de decisión toman generalmente entre 20 segundos y 10 minutos (depende de cada usuario).
- Configuración de URLs: Tanto la URL de respuesta para el Webhook como la URL de redirección del cliente no son estáticas ni se configuran en un panel global. Deben definirse dinámicamente por cada transacción enviando las llaves callbackUrl y redirectionUrl dentro del body (JSON) de la petición al momento de crear la transacción (descrito en el punto 3).
- Documentación: Online Application Callback
- Estados posibles (Enum): approved, rejected, declined, abandoned.
- Redirección dinámica (redirectionUrl): Una vez finalizado el proceso en Addi, el cliente es retornado a la tienda. Esta URL debe ser dinámica: si el estado fue approved, se debe dirigir al cliente a la página de agradecimiento (Thank You Page). Para cualquier otro estado, se le debe redirigir a la página del carrito para permitir un nuevo intento de compra con Addi o con otro método de pago.
- Monto aprobado: Addi no realiza aprobaciones parciales. El campo approvedAmount siempre será 0, a menos que la transacción sea aprobada; en dicho escenario, el monto será exactamente igual al valor solicitado.
- Tiempo máximo de expiración de una transacción: 2 horas.
- Requisitos del Webhook (callbackUrl):
- Debe contar con autenticación básica (Basic Auth). Las credenciales deben ser obtenidas del portal de aliados y configuradas en su sistema previo al paso a Producción.
- Estas credenciales las pueden encontrar en la sección de integraciones, en el modulo Credenciales de notificación
- Para que los sistemas de Addi marquen la notificación de la transacción como exitosa, el endpoint del comercio debe responder con un status HTTP 200 y retornar exactamente el mismo cuerpo (body) en formato JSON que recibió en la petición.
- Reintentos: En caso de que el Webhook falle o la comunicación no se pueda establecer, Addi marcará el envío como incompleto y realizará reintentos cada 30 minutos durante 24 horas. Si el problema persiste, el equipo de soporte puede forzar el envío de forma semi-automática.
5. Cancelaciones / Reembolsos
Proveemos un endpoint dedicado para reversar compras previamente aprobadas (requiere autenticación con JWT).
- Documentación: Online application cancellation
- Total vs Parcial: Si se envía un monto que coincide con el valor original de la transacción, el sistema asumirá una cancelación total. Si el monto es menor, se procesará como una cancelación parcial.
- Límites: Solo se permite realizar una (1) solicitud de cancelación por transacción, ya sea total o parcial.
- Soporte: En caso de requerir una corrección o necesitar más de una cancelación parcial sobre una misma orden, se debe realizar una solicitud formal contactando al equipo de soporte a través de [email protected].