Solución Flexible para el Procesamiento de Pagos

Akua es una plataforma de procesamiento de pagos que se adapta a los requisitos de cada negocio. Puede operar como procesador y adquirente completo o como solo procesador, según la estructura del cliente.

---

Modelos operativos

Akua como Procesador y Adquirente

Akua opera bajo su propia licencia de adquirencia con Visa y Mastercard. Pasarelas de pago, facilitadores y orquestadores integran pagos de comerciantes directamente con las redes de tarjetas sin depender de adquirentes locales. Akua asume la responsabilidad total del flujo de pago.

---

Akua como Solo Procesador

Akua provee la infraestructura y el soporte técnico a otro adquirente que mantiene la relación de licencia con las redes de tarjetas. Akua maneja la tecnología y la logística sin interacción directa con comerciantes ni licencias propias de red.

---

Comparación

Los ciclos de transacción y el flujo de información son consistentes en ambos modelos.

Tipos de clientes

¿Qué tipo de clientes pueden integrarse con Akua?

Akua ofrece un proceso adaptable para diferentes tipos de clientes. La plataforma reconoce que las necesidades varían según el perfil del integrado, por lo que proporciona experiencias personalizadas y eficientes.

Adquirente

Instituciones financieras que procesan pagos de tarjetas o soluciones de pago electrónico:

• Adquiriente Financiero: Regulados por entidades gubernamentales
• Adquiriente No Vigilado: Operan bajo un modelo flexible

Proceso de Integración:

Adquiriente Financiero:

1. Presentación de licencias y certificaciones regulatorias
2. Sincronización directa con sistemas de pago diario

Adquiriente No Vigilado:

1. Validación contractual y revisión de políticas internas
2. Pruebas intensivas para garantizar estabilidad

Facilitadores de pago | PayFacs

Empresas intermediarias entre comerciantes y adquirientes que permiten la aceptación de pagos electrónicos. Akua actúa como adquiriente en estos casos.

Proceso de Integración:

1. Validación regulatoria: Licencias para operar como facilitador, información sobre sub-merchants gestionados
2. Configuración técnica: Acceso a API para registrar sub-merchants, implementación de herramientas de split payments
3. Soporte avanzado: Resolución continua de disputas y contracargos

Pasarelas de pago | Gateways

Proveedores de infraestructura que conectan comerciantes con adquirientes.

Proceso de Integración:

1. Validación: Cumplimiento con normativas internacionales (PCI DSS)
2. Configuración técnica: Sincronización de flujos transaccionales, configuración de redundancia
3. Reportes: Dashboards para monitoreo en tiempo real

Billeteras | Wallets | SDWOs

Plataformas que permiten almacenar dinero digitalmente y realizar pagos seguros, operando con modelos "stored value" u "open loop".

Proceso de Integración:

1. Carga de documentación: Licencias como billetera electrónica, certificaciones de cumplimiento (PCI DSS si aplica)
2. Configuración técnica: Acceso a API para gestión de transacciones y saldo, implementación de Webhooks para notificaciones
3. Pruebas: Escenarios simulados (carga y retiro de saldo)

Comercios | Merchants

Negocios que aceptan pagos electrónicos, desde pequeñas tiendas hasta grandes cadenas retail.

Proceso de Integración:

1. Registro: Documentos de identidad empresarial, validación de cuenta bancaria
2. Configuración técnica: Integración con POS o sistema e-commerce, configuración de tasas y límites
3. Pruebas: Tutoriales para dashboard y gestión de reportes

Conclusión

El proceso de integración de Akua busca ser flexible y adaptarse a necesidades específicas de cada cliente, con enfoque en experiencia del usuario y cumplimiento normativo para implementación segura y eficiente.

Clientes, Organizaciones, Agregadores & Comercios

Esta sección describe las entidades del ecosistema Akua, sus relaciones y cómo se estructuran jerárquicamente.

Jerarquía de cuentas

Las cuentas en Akua se organizan en cuatro niveles:

Cliente
└── Organización
    └── Agregador
        └── Merchant

---

Clientes

Representan a las empresas u organizaciones que utilizan las soluciones de adquirencia financiera de Akua para gestionar pagos. Pueden ser desde pequeñas operaciones hasta grandes organizaciones que buscan simplificar sus procesos de cobro.

---

Organizaciones

Ofrecen una forma lógica de agrupar y estructurar los agregadores y comercios dentro de un cliente. Cada cliente recibe una organización "default" al registrarse, pero puede crear múltiples organizaciones según su modelo de negocio.

---

Agregadores

El Agregador es la entidad que contiene el payfacID — el identificador que lo acredita como facilitador de pagos ante las redes. Todos los merchants que procesan transacciones deben pertenecer a un agregador.

---

Comercios

Los merchants pertenecen a un agregador y son quienes reciben los pagos electrónicos de los consumidores mediante tarjetas de crédito, débito u otros métodos digitales. Un Comercio es una unidad principal de procesamiento. Puede representar una marca, razón social o una línea de negocio específica. Ejemplo: Tienda A, Tienda B

Cada comercio puede tener:

• Subcomercios
• Sucursales o puntos de venta
• Terminales

Subcomercios

Un Subcomercio representa una división más específica dentro de un comercio. Ideal para casos como franquicias, unidades independientes o regiones. Ejemplo: Tienda A - Franquicia Córdoba

Cada subcomercio puede tener:

• Puntos de venta
• Terminales

Venta Presente

Entidades POS y Terminales

La gestión de Puntos de Venta y terminales representa un proceso clave para asegurar que las transacciones ocurran de manera eficiente y segura. Esta sección describe las relaciones entre POS y terminales y los procedimientos de integración.

¿Qué es un Point of Sale?

Un Point of Sale (POS) es una representación de ubicación física o digital donde ocurren las transacciones. El POS incluye:

• Detalles completos de dirección
• Nombre de sucursal o tienda
• Coordenadas geográficas
• Capacidad máxima de terminales asignables

¿Qué es un Terminal?

Un terminal es un dispositivo físico que procesa pagos electrónicos en un POS, que incluye:

• Modelo y número de serie
• Métodos de pago soportados (VISA, Mastercard, QR)
• Estado operacional (Activo/Inactivo)

Venta Presente con POS

Para transacciones desde terminales POS, la jerarquía sigue: Organization > Merchant > POS > Terminal.

Adherir un Point y un Terminal

La asociación de terminales requiere primero crear un POS. El POS funciona como el punto de referencia que organiza las transacciones.

Por qué esta relación importa:

• Organización: Gestión de terminales por POS específico
• Trazabilidad: Seguimiento de transacciones hasta el POS de origen
• Escalabilidad: Fácil adición de terminales en múltiples ubicaciones

Paso 1: Crear un Point of Sale (POS)

Datos requeridos:

• Nombre del punto de venta
• Dirección completa (calle, número, ciudad, país, código postal)
• Coordenadas opcionales (latitud/longitud)

{
  "name": "Sucursal Palermo",
  "address": {
    "street": "Av. Santa Fe",
    "number": "3250",
    "city": "Buenos Aires",
    "state": "CABA",
    "country": "Argentina",
    "zip_code": "1425",
    "coordinates": {
      "latitude": -34.5886,
      "longitude": -58.4061
    }
  },
  "merchant_id": "mer-12345",
  "max_active_pos": 10
}

Paso 2: Registrar un Terminal

Información requerida:

• Modelo y número de serie del terminal
• ID del POS asociado
• Métodos de pago soportados y estado inicial

{
  "model": "Verifone VX520",
  "serial_number": "SN123456789",
  "status": "ACTIVE",
  "point_id": "point-8clm7v3hqjt0k8e9g1f",
  "supported_payment_methods": ["VISA", "MASTERCARD"],
  "firmware_version": "1.2.3",
  "remote_management": {
    "ota_updates_enabled": true
  }
}

Paso 3: Asignar el Terminal al POS

Asocia el terminal creado al POS deseado, vinculando transacciones a las ubicaciones apropiadas.

{
  "terminal_id": "trm-xidn01b5cq5t2rf7gk4m",
  "point_id": "point-8clm7v3hqjt0k8e9g1f"
}

Instrumentos / Tarjetas

Las tarjetas son instrumentos que representan de forma virtual una tarjeta física. Al registrar una nueva tarjeta, el sistema genera automáticamente un identificador único con el prefijo ins- seguido de 20 caracteres alfanuméricos.

---

Atributos principales

---

Detalle de atributos

ID

Se genera automáticamente al crear la tarjeta. Identifica al instrumento de forma exclusiva en el sistema.

ins-a1b2c3d4e5f6g7h8i9j0

---

Fingerprint

Valor alfanumérico generado a partir de los datos de la tarjeta. Permite identificar la tarjeta física subyacente sin exponer información sensible, incluso cuando existen múltiples instrumentos asociados a una misma cuenta.

El fingerprint nunca expone datos privados fuera de un entorno seguro (PCI).

---

Payment Method

Describe el tipo de instrumento con un formato compuesto de tres partes:

TIPO_INSTRUMENTO_MARCA_TIPO_TARJETA

Ejemplo:

---

Status y Validation

---

Datos del número de tarjeta

El número completo (PAN) nunca se expone fuera de un entorno PCI. Solo se pueden visualizar partes no sensibles:

Akua es una plataforma de Adquirencia como Servicio (AaaS). Esta guía cubre todo lo que necesitás saber para integrarte: desde el acuerdo inicial hasta la autenticación y los entornos de desarrollo.

Tiempo estimado de kickoff a producción: ~14 días.

---

Pasos de integración

1. Firma del contrato y Kickoff

Se formaliza el acuerdo con Akua y se coordina una reunión de Kickoff para alinear equipos, expectativas y definir el alcance del proyecto. Es el punto de partida para una integración ordenada y ágil.

---

2. Acceso al Dashboard

El equipo de Akua enviará un correo de invitación con un link para registrarte como administrador en el Dashboard de Autogestión.

Una vez dentro:

• Ingresá tu Company ID (generalmente tu dominio) para acceder
• Iniciá sesión con el usuario y contraseña que hayas creado
• Gestioná usuarios y asigná roles según el área:

---

3. API Keys y Autenticación

Las credenciales se generan desde el Dashboard en Developers > API Keys.

Credenciales a generar:

• Client ID
• Client Secret
• Permisos (scopes) según la integración

Flujo de autenticación:

1. Envía tus credenciales al endpoint /oauth/token para obtener un JWT token
2. Usa ese token como Bearer Token en el header de cada request
3. El token tiene duración de 24 horas — será necesaria una lógica de refresh

---

4. Entornos disponibles

La migración a producción se realiza una vez validado el checklist de homologación, que cubre:

• Base técnica (JWT, API Keys, Webhooks)
• E-commerce (Autorizaciones, Capturas, Reembolsos)
• Tarjeta Presente (si aplica)

---

⏱️ Timeout recomendado: 40 segundos

El tiempo de timeout recomendado es de 40 segundos para requests de pagos.

Los tiempos de respuesta de Akua son sólidos: p95 de 3 segundos y p99 de 8 segundos. El timeout de 40 segundos no refleja la latencia de Akua, sino el margen necesario para cubrir casos borde en la red de franquicia. Timeouts más ajustados generan rechazos innecesarios que pueden escalar a contracargos.

🔁 Idempotency-Key

Es necesario incluir el header Idempotency-Key en todos los requests para manejar reintentos de forma segura y evitar transacciones duplicadas.

---

Herramientas y soporte

Soporte disponible 24/7:

• Autogestión vía documentación y Help Center
• Agente de IA (FIN)
• Agentes humanos
• Escalación interna para casos críticos

¿Qué es PCI DSS?

PCI DSS (Payment Card Industry Data Security Standards) es el conjunto de requisitos de seguridad establecidos por el PCI Security Standards Council para organizaciones que manejan datos de tarjetas de pago. Su cumplimiento es exigido por Visa, Mastercard, Discover y American Express.

Cualquier entidad que almacene, procese o transmita datos de tarjetas de crédito puede estar sujeta a estos requisitos.

Akua está certificado como Proveedor de Servicios Nivel 1 en cumplimiento con PCI DSS.

---

Niveles de cumplimiento

Los niveles se definen según el volumen anual de transacciones:

---

Validación — Cuestionarios SAQ

Los comerciantes de niveles 2 a 4 validan su cumplimiento mediante Cuestionarios de Auto-Evaluación (SAQ). El tipo aplicable depende del modelo de integración:

Akua pre-llena la información del SAQ basándose en los detalles de integración del comerciante y monitorea el cumplimiento de forma continua, notificando ante cambios o incidencias.

Seguridad y Cumplimiento

Akua cuenta con certificación PCI DSS Nivel 1 — el nivel de seguridad más estricto disponible en el ecosistema de pagos.

La documentación de Attestation of Compliance (AoC) está disponible bajo solicitud en trust.akua.la.

---

Prácticas de seguridad

---

Evaluaciones y auditorías

Dual Encryption — Datos de Tarjeta

Descripción general

Akua permite enviar datos sensibles de tarjeta encriptados usando RSA-OAEP-256. Esto permite a los integradores encriptar los campos de tarjeta del lado del cliente antes de enviarlos en una solicitud de autorización, de forma que el PAN y el CVV nunca viajen en texto plano.

El merchant solo necesita trabajar con RSA. El proceso es directo: cada campo sensible se cifra de forma independiente con la clave pública RSA del cliente y el resultado en Base64 se envía en el campo encrypted_* correspondiente.

Nota sobre la arquitectura interna: Internamente, el servicio de encriptación también utiliza AES-256-GCM, pero exclusivamente para proteger las claves privadas RSA en reposo (en base de datos). Esto es completamente transparente para el integrador y no forma parte del flujo de encriptación del request.

---

¿Cómo funciona?

El objeto card en una solicitud de autorización acepta cinco campos en texto plano o en forma encriptada. Las variantes encriptadas usan el prefijo encrypted_:

Los campos se pueden combinar — por ejemplo, se puede enviar encrypted_number junto con expiration_month en texto plano.

Regla de precedencia: Si se envía un campo en texto plano y su equivalente encrypted_* al mismo tiempo, el campo en texto plano tiene prioridad. Para evitar confusión, se recomienda enviar solo uno de los dos por campo.

---

Referencia del objeto card

Sin encriptación (9 campos)

{
  "card": {
    "number": "4111111111111111",
    "expiration_month": "12",
    "expiration_year": "2027",
    "holder_name": "John Doe",
    "cvv": "123",
    "discretionary_data": "...",
    "sequence_number": "...",
    "service_code": "...",
    "pin_block_data": "..."
  }
}

Con encriptación (reemplazando los 5 campos sensibles — 9 campos)

{
  "card": {
    "encrypted_number": "<base64-encriptado>",
    "encrypted_expiration_month": "<base64-encriptado>",
    "encrypted_expiration_year": "<base64-encriptado>",
    "encrypted_holder_name": "<base64-encriptado>",
    "encrypted_cvv": "<base64-encriptado>",
    "discretionary_data": "...",
    "sequence_number": "...",
    "service_code": "...",
    "pin_block_data": "..."
  }
}

---

Ambientes

Los endpoints de gestión de claves viven en la MISMA base que el resto de la API del comercio (la que ya se usa para /oauth/token, /v1/instruments, /v1/users, etc.):

---

Gestión de claves

El flujo de integración requiere dos pasos: primero obtener la clave pública activa (creándola si aún no existe), luego usarla para encriptar los campos de tarjeta.

Ambos endpoints se autentican con el mismo Bearer token client_credentials que ya se usa para el resto de la API. No hace falta enviar el header client-id — el servicio resuelve el cliente a partir del JWT.

---

Paso 1 — Crear o rotar el par de claves

Antes de poder encriptar, el cliente debe generar su par de claves RSA en el sistema. Este paso se realiza una sola vez (o cada vez que se quiera rotar la clave).

⚠️ Este endpoint reemplaza la clave activa si ya existe una — no llamarlo en cada arranque de tu app. Hacé GET primero y solo POST si no hay clave.

Endpoint

POST /v1/encryption/keys

Ejemplo

TOKEN=$(curl -s -X POST https://sandbox.akua.la/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"<CLIENT_ID>","client_secret":"<CLIENT_SECRET>","audience":"https://sandbox.akua.la"}' \
  | jq -r '.access_token')

curl -X POST https://sandbox.akua.la/v1/encryption/keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Respuesta (201)

{
  "client_id": "cli-d6g4fk97st004b10ai70",
  "kid": "key_d965l7hg7c83rpt50pag",
  "algorithm": "RSA-OAEP-256",
  "key_size": 2048,
  "status": "active",
  "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
  "valid_from": "2026-07-07T01:47:11.151315844Z",
  "valid_until": "2027-07-07T01:47:11.151315844Z",
  "created_at": "2026-07-07T01:47:11.151315844Z",
  "updated_at": "2026-07-07T01:47:11.151315844Z"
}

---

Paso 2 — Obtener la clave pública activa

Una vez creada, se obtiene la clave pública para encriptar los campos de tarjeta. Este endpoint devuelve la clave existente sin rotarla.

Endpoint

GET /v1/encryption/keys

Ejemplo — Descargar y guardar como .pem

curl https://sandbox.akua.la/v1/encryption/keys \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '.public_key' > pub.pem

Devuelve el mismo shape que el POST, con la clave ya existente.

---

Encriptar un campo de tarjeta

Una vez guardada la clave pública como pub.pem, se usa RSA-OAEP con SHA-256 para encriptar cada campo. El resultado debe estar codificado en Base64.

Ejemplo — Encriptar un PAN por línea de comandos

echo -n "4111111111111111" | openssl pkeyutl -encrypt \
  -pubin -inkey pub.pem \
  -pkeyopt rsa_padding_mode:oaep \
  -pkeyopt rsa_oaep_md:sha256 \
  | base64

El string Base64 resultante se coloca en el campo encrypted_* correspondiente del objeto card.

Repetir este proceso para cada campo que se desee encriptar (number, expiration_month, expiration_year, holder_name, cvv).

---

Rotación de claves

• Las claves se rotan anualmente.
• Solo se permite una clave activa por cliente a la vez — llamar a POST /v1/encryption/keys reemplaza la clave activa existente.
• Los integradores deben siempre obtener la clave activa desde GET /v1/encryption/keys antes de encriptar, para asegurarse de usar la clave vigente.

Transacciones CIT / MIT — Guía de Integración

Endpoint: POST /v1/payments/authorizations

Las redes de tarjetas (Visa, Mastercard) exigen identificar quién inicia cada transacción y qué tipo de cobro es. Akua resuelve esto con dos campos en el request de autorización: initiator y order_type.

---

Conceptos clave

CIT (Customer Initiated Transaction): el tarjetahabiente está presente (física o digitalmente) y autoriza el cobro de forma activa. Ejemplos: una compra en un e-commerce, el primer pago de una suscripción, guardar una tarjeta para uso futuro.

MIT (Merchant Initiated Transaction): el comercio cobra sin presencia del cliente, basándose en un acuerdo previo que el cliente autorizó en una CIT. Ejemplos: el cobro mensual de una suscripción, un cargo por no-show en un hotel, un reintento de cobro.

La regla fundamental es: toda MIT debe vincularse a la CIT que le dio origen. Esto se hace enviando parent_transaction_data con los identificadores de red que Akua devuelve en la respuesta de la CIT original.

---

Los campos

initiator

order_type

Este campo le dice a la red de tarjetas qué tipo de cobro se está haciendo. Dependiendo del valor, puede usarse como CIT, como MIT, o como ambos en distintos momentos del flujo.

Valores que aplican como CIT y como MIT:

Cuando se usan como CIT, estos valores actúan como CIT-Initial: la credencial se almacena (card-on-file) y se activa la tokenización y el Account Updater (ABU) para mantener los datos de la tarjeta vigentes.

Valores solo CIT:

purchase es el único tipo CIT que no funciona como CIT-Initial. Es una transacción aislada sin relación con cobros posteriores.

Valores solo MIT:

---

Flujo completo: CIT → MIT

El patrón siempre es el mismo, sin importar el order_type:

1. Se hace una CIT (el cliente autoriza)
2. En la respuesta, Akua devuelve network_data dentro de la transacción, con los identificadores de la red
3. El comercio guarda esos identificadores
4. Cuando toca cobrar sin el cliente, se envía una MIT incluyendo parent_transaction_data con esos identificadores

Paso 1 — CIT inicial

El cliente autoriza el primer cobro. En este ejemplo, es una suscripción (recurring):

POST /v1/payments/authorizations

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "recurring",
    "initiator": "customer",
    "capture": {
        "mode": "AUTOMATIC"
    },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": {
        "value": 29900,
        "currency": "COP"
    },
    "instrument": {
        "type": "CARD",
        "card": {
            "number": "53830400xxxx0002",
            "cvv": "917",
            "expiration_month": "12",
            "expiration_year": "30",
            "holder_name": "Juan Rodriguez"
        }
    },
    "customer_data": {
        "billing_address": {
            "street": "Calle 26",
            "number": "45A-60",
            "city": "Bogotá",
            "state": "Cundinamarca",
            "zip_code": "110911",
            "country": "COL"
        }
    }
}

Respuesta de la CIT (extracto relevante)

La respuesta incluye los datos de red dentro de transaction.network_data. Lo importante es guardar estos valores para usarlos en las MIT posteriores:

{
    "payment_id": "pay-abc123xxxxxxxxxx",
    "transaction": {
        "id": "trx-xyz789xxxxxxxxxx",
        "status": "APPROVED",
        "network_data": {
            "approval_code": "772886",
            "response_code": "00",
            "financial_network_code": "MCC",
            "banknet_reference_number": "000UNB",
            "settlement_date": "0315",
            "transmission_date_time": "0315143000"
        }
    },
    "instrument_id": "ins-xxxxxxxxxx"
}

Importante: guardar el payment_id o transaction.id devuelto. Estos se usan para construir parent_transaction_data en las MIT posteriores. Adicionalmente, dependiendo de la red, la respuesta puede incluir campos específicos como mastercard_economic_tlid o visa_initial_transaction_identifier dentro de network_data.

Paso 2 — MIT posterior

Cuando llega el momento de cobrar sin presencia del cliente, se envía la misma autorización pero con initiator: "merchant" y parent_transaction_data para vincularla a la CIT original.

Con datos de Mastercard:

POST /v1/payments/authorizations

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "recurring",
    "initiator": "merchant",
    "capture": {
        "mode": "AUTOMATIC"
    },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": {
        "value": 29900,
        "currency": "COP"
    },
    "instrument": {
        "id": "ins-xxxxxxxxxx"
    },
    "parent_transaction_data": {
        "network_data": {
            "mastercard_economic_tlid": "AABB1234CCDD5678EEFF01"
        }
    }
}

Con datos de Visa:

POST /v1/payments/authorizations

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "recurring",
    "initiator": "merchant",
    "capture": {
        "mode": "AUTOMATIC"
    },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": {
        "value": 29900,
        "currency": "COP"
    },
    "instrument": {
        "id": "ins-xxxxxxxxxx"
    },
    "parent_transaction_data": {
        "network_data": {
            "visa_initial_transaction_identifier": "012345678901234"
        }
    }
}

Notas sobre las MIT:

• Se usa instrument.id (el instrumento almacenado), no los datos crudos de la tarjeta. El CVV no se almacena ni se reenvía.
• No se envía customer_data — el cliente no está presente.
• parent_transaction_data.network_data lleva el identificador de red correspondiente a la marca de la tarjeta.

---

Vinculación por red (parent_transaction_data)

El campo que se envía dentro de parent_transaction_data.network_data depende de la red de la tarjeta:

Estos valores los devuelve Akua en la respuesta de la CIT aprobada. El comercio debe almacenarlos y enviarlos sin modificar en cada MIT posterior de la misma serie.

Opcionalmente, parent_transaction_data también acepta first_payment_id y first_transaction_id para vincular usando los identificadores internos de Akua en lugar de (o además de) los de red.

---

Ejemplos por caso de uso

En todos los ejemplos de MIT se omiten los campos que no cambian respecto al flujo general (la estructura completa se mostró arriba). Solo se muestran los campos relevantes para cada caso.

Suscripción — recurring

Caso: streaming, SaaS, membresías. Monto fijo, frecuencia fija.

CIT (el cliente se suscribe):

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "recurring",
    "initiator": "customer",
    "capture": { "mode": "AUTOMATIC" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 29900, "currency": "COP" },
    "instrument": {
        "type": "CARD",
        "card": {
            "number": "53830400xxxx0002",
            "cvv": "917",
            "expiration_month": "12",
            "expiration_year": "30",
            "holder_name": "Juan Rodriguez"
        }
    }
}

MIT (cobro mensual automático):

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "recurring",
    "initiator": "merchant",
    "capture": { "mode": "AUTOMATIC" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 29900, "currency": "COP" },
    "instrument": { "id": "ins-xxxxxxxxxx" },
    "parent_transaction_data": {
        "network_data": {
            "mastercard_economic_tlid": "AABB1234CCDD5678EEFF01"
        }
    }
}

---

Cuotas — installment

Caso: el cliente compra un producto y paga en N cuotas. La primera cuota es CIT, las siguientes son MIT.

CIT (primera cuota):

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "installment",
    "initiator": "customer",
    "capture": { "mode": "AUTOMATIC" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 150000, "currency": "COP" },
    "instrument": {
        "type": "CARD",
        "card": {
            "number": "53830400xxxx0002",
            "cvv": "917",
            "expiration_month": "12",
            "expiration_year": "30",
            "holder_name": "Juan Rodriguez"
        }
    },
    "installments": {
        "type": "issuer-financed",
        "quantity": 6
    }
}

MIT (cuota siguiente):

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "installment",
    "initiator": "merchant",
    "capture": { "mode": "AUTOMATIC" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 25000, "currency": "COP" },
    "instrument": { "id": "ins-xxxxxxxxxx" },
    "parent_transaction_data": {
        "network_data": {
            "visa_initial_transaction_identifier": "012345678901234"
        }
    }
}

---

Débito automático variable — standing_order

Caso: servicios públicos, seguros, membresías donde el monto varía cada periodo.

CIT (autorización inicial):

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "standing_order",
    "initiator": "customer",
    "capture": { "mode": "AUTOMATIC" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 85000, "currency": "COP" },
    "instrument": {
        "type": "CARD",
        "card": {
            "number": "53830400xxxx0002",
            "cvv": "917",
            "expiration_month": "12",
            "expiration_year": "30",
            "holder_name": "Juan Rodriguez"
        }
    }
}

MIT (cobro del periodo, monto distinto):

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "standing_order",
    "initiator": "merchant",
    "capture": { "mode": "AUTOMATIC" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 92300, "currency": "COP" },
    "instrument": { "id": "ins-xxxxxxxxxx" },
    "parent_transaction_data": {
        "network_data": {
            "mastercard_economic_tlid": "AABB1234CCDD5678EEFF01"
        }
    }
}

---

Cobro no programado — unscheduled

Caso: recarga automática de saldo cuando baja de un umbral, cobro por uso bajo demanda.

CIT (el cliente guarda su tarjeta y autoriza cobros futuros):

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "unscheduled",
    "initiator": "customer",
    "capture": { "mode": "AUTOMATIC" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 50000, "currency": "COP" },
    "instrument": {
        "type": "CARD",
        "card": {
            "number": "53830400xxxx0002",
            "cvv": "917",
            "expiration_month": "12",
            "expiration_year": "30",
            "holder_name": "Juan Rodriguez"
        }
    }
}

MIT (recarga automática):

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "unscheduled",
    "initiator": "merchant",
    "capture": { "mode": "AUTOMATIC" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 50000, "currency": "COP" },
    "instrument": { "id": "ins-xxxxxxxxxx" },
    "parent_transaction_data": {
        "network_data": {
            "visa_initial_transaction_identifier": "012345678901234"
        }
    }
}

---

Autorización diferida — deferred

Caso: el cliente autoriza un monto que se cobrará después (ej: reserva de hotel donde el cobro final se hace al checkout).

CIT (autorización):

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "deferred",
    "initiator": "customer",
    "capture": { "mode": "MANUAL" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 350000, "currency": "COP" },
    "instrument": {
        "type": "CARD",
        "card": {
            "number": "53830400xxxx0002",
            "cvv": "917",
            "expiration_month": "12",
            "expiration_year": "30",
            "holder_name": "Juan Rodriguez"
        }
    }
}

MIT (cobro posterior):

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "deferred",
    "initiator": "merchant",
    "capture": { "mode": "AUTOMATIC" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 350000, "currency": "COP" },
    "instrument": { "id": "ins-xxxxxxxxxx" },
    "parent_transaction_data": {
        "network_data": {
            "mastercard_economic_tlid": "AABB1234CCDD5678EEFF01"
        }
    }
}

---

Cargo posterior al servicio — delayed

Caso: hotel, transporte, servicios donde pueden surgir cargos adicionales después del servicio principal. La CIT es la autorización al inicio del servicio (ej: check-in), y las MIT son los cargos adicionales posteriores (ej: minibar, peajes, daños).

CIT (check-in del hotel, autorización inicial):

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "delayed",
    "initiator": "customer",
    "capture": { "mode": "MANUAL" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 500000, "currency": "COP" },
    "instrument": {
        "type": "CARD",
        "card": {
            "number": "53830400xxxx0002",
            "cvv": "917",
            "expiration_month": "12",
            "expiration_year": "30",
            "holder_name": "Juan Rodriguez"
        }
    }
}

MIT (cargo por minibar post-checkout):

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "delayed",
    "initiator": "merchant",
    "capture": { "mode": "AUTOMATIC" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 15000, "currency": "COP" },
    "instrument": { "id": "ins-xxxxxxxxxx" },
    "parent_transaction_data": {
        "network_data": {
            "visa_initial_transaction_identifier": "012345678901234"
        }
    }
}

---

Cargo por no presentación — no_show

Caso: el cliente reservó y no se presentó. Solo MIT.

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "no_show",
    "initiator": "merchant",
    "capture": { "mode": "AUTOMATIC" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 120000, "currency": "COP" },
    "instrument": { "id": "ins-xxxxxxxxxx" },
    "parent_transaction_data": {
        "network_data": {
            "mastercard_economic_tlid": "AABB1234CCDD5678EEFF01"
        }
    }
}

---

Reenvío de transacción rechazada — resubmission

Caso: un cobro MIT fue rechazado (ej: fondos insuficientes) y se reintenta después. Solo MIT.

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "resubmission",
    "initiator": "merchant",
    "capture": { "mode": "AUTOMATIC" },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": { "value": 29900, "currency": "COP" },
    "instrument": { "id": "ins-xxxxxxxxxx" },
    "parent_transaction_data": {
        "network_data": {
            "visa_initial_transaction_identifier": "012345678901234"
        }
    }
}

---

Validaciones

Combinaciones inválidas retornan 400 Bad Request con error code INVALID_INITIATOR_ORDER_TYPE_COMBINATION:

¿Qué es una autorización?

La autorización es el primer paso en el proceso de pago, donde se presentan los detalles de la tarjeta de crédito del tarjetahabiente al comercio para el pago. El comerciante envía la transacción al banco adquirente, que reenvía la solicitud al emisor de la tarjeta para su autorización a través de la red.

El proceso de un pago incluye tres etapas principales, que se traducen de la siguiente manera:

1. Autorización:

Es el primer paso del proceso, en el cual:

• El titular de la tarjeta proporciona los detalles de pago al comerciante.
• El banco adquirente (el banco del comerciante) envía la solicitud a través de la red de tarjetas al banco emisor (el banco del titular de la tarjeta).
• El banco emisor verifica la validez de la tarjeta, los fondos disponibles y la seguridad de la transacción, y responde aprobando o rechazando la operación.
• Si se aprueba, se genera un código de autorización y se reserva temporalmente el monto en la cuenta del titular, pero aún no se transfiere al comerciante.

2. Compensación

En esta etapa:

• Los detalles de la transacción aprobada se procesan y se preparan para la liquidación.
• El adquirente y la red de tarjetas realizan una reconciliación de la transacción con el emisor para confirmar montos y aplicar cualquier ajuste (como tasas o conversiones de moneda).
• Esta etapa asegura que todos los participantes en la transacción estén alineados con la información registrada.
• No implica transferencia de dinero aún, pero garantiza que los datos sean precisos para la siguiente etapa.

3. Liquidación:

Finalmente:

• Los fondos reservados en la autorización se transfieren del banco emisor al banco adquirente, pasando por la red de tarjetas.
• El banco adquirente acredita el monto al comerciante, menos las comisiones aplicables (como la tasa de descuento).
• En este punto, la transacción se completa y el comerciante recibe su pago.

---

Roles y Responsabilidades

El camino de una transacción

1. El cliente realiza el pago: Usa su tarjeta (física o digital) para realizar una compra en un negocio (tienda física o en línea).
2. El comerciante envía la solicitud: Compartimos los detalles esenciales del pago con el banco del cliente (emisor) para su evaluación.
3. El emisor responde: Aprueba o rechaza la solicitud en función de la validez de la tarjeta, los fondos disponibles y las políticas de seguridad.

¿Qué sucede cuando el banco responde?

APROBACIÓN

Código de Autorización:

• Un número único que confirma la transacción.

Aprobaciones Parciales:

• En algunos casos, el emisor puede aprobar solo una parte del monto (esto se aplica particularmente a ciertos tipos de comerciantes).

RECHAZO

La tarjeta puede ser rechazada por razones como:

• Fondos insuficientes.
• Información incorrecta.
• Sospecha de fraude.
• En casos especiales, si el emisor sospecha fraude, puede ser necesaria una verificación manual (llamada por teléfono).

Flujo de autorización en un pago y sus estados

📘 Cualquier estado puede llevar finalmente a un ERROR. Esto sugiere que puede ocurrir una falla en cualquier etapa del proceso.

Pre-autorización

Descripción

Más allá de la autorización estándar, la pre-autorización permite a los comerciantes reservar un monto estimado de pago sin hacerlo final. Este proceso se usa comúnmente en industrias de hospitalidad y alquiler de vehículos donde los montos finales de transacción pueden fluctuar.

Durante la pre-autorización:

• Una suma se retiene en la cuenta del titular de la tarjeta como garantía
• Se pueden hacer ajustes posteriormente—aumentando o disminuyendo el monto reservado
• Si el monto final es menor, la diferencia se libera automáticamente
• Si es mayor, el comerciante debe solicitar autorización adicional

Flujo de los estados de una Preautorización

Casos de Uso

La pre-autorización proporciona flexibilidad y seguridad tanto para comerciantes como para clientes, asegurando que los fondos estén disponibles para bienes o servicios entregados.

Escenarios comunes incluyen:

• Hoteles: cubriendo costos de habitación más extras potenciales
• Alquiler de autos: cubriendo tarifas de alquiler y posibles cargos por daños
• Aerolíneas: garantizando pago mientras se procesa la emisión de boletos
• E-commerce: asegurando pago antes de confirmar disponibilidad de producto

Requisitos Clave

• La pre-autorización debe liquidarse dentro de 30 días
• En pre-autorizaciones, sólo se acepta modo de captura MANUAL
• Las transacciones deben vincularse usando el Trace ID (DE 48, subelemento 63) para asociación precisa con el emisor

Autorización Parcial

Descripción

Un proceso que ocurre cuando el monto total de una transacción no puede ser aprobado debido a fondos insuficientes o crédito limitado. En lugar de rechazar la transacción completamente, el banco emisor aprueba un monto parcial, permitiendo al titular de la tarjeta usar un método de pago adicional para el saldo restante.

Puntos Clave

El proceso asegura que los titulares de tarjetas puedan completar compras incluso con fondos disponibles limitados. El sistema de pago del comerciante debe soportar autorización parcial para manejar estas transacciones correctamente. El saldo restante puede pagarse usando otra tarjeta, efectivo o método de pago alternativo.

Casos de Uso

Este enfoque resulta especialmente valioso para tarjetas prepago o cuando los clientes combinan múltiples métodos de pago. Ofrece flexibilidad tanto a comerciantes como a clientes, previniendo rechazos de transacción innecesarios.

Flujo del Proceso

1. Solicitud Inicial: El comerciante envía el monto total de la transacción para aprobación
2. Respuesta del Emisor: El banco aprueba el monto parcial y envía respuesta de autorización con la suma aprobada
3. Notificación del Terminal: Muestra el saldo restante; solicita método de pago alternativo
4. Completar o Reversar: Ya sea un mensaje de advice (0120) confirma la aprobación parcial, o un mensaje de reversa (0400) explica la cancelación

Escenarios de Ejemplo

• El titular de tarjeta intenta un pago de $100 con $75 disponibles; recibe aprobación de $75 con $25 pendientes
• El titular de tarjeta paga $50 coincidiendo con el saldo disponible; no se solicitan fondos adicionales
• La continuación envía advice confirmando aprobación; la cancelación envía reversa explicando la razón

Requisitos Clave

• Campo DE 6: Muestra el monto aprobado disponible para compra
• Notificación al Comerciante: El adquirente debe notificar al comerciante si la aprobación parcial iguala el monto solicitado para prevenir cargos adicionales

Compensación

¿Qué es la compensación?

El clearing es el precursor del settlement (liquidación). Ambas partes involucradas (Adquirente y Emisor) comparten y acuerdan los detalles de la transacción. Normalmente, cuando el proceso de clearing de una transacción se completa, el emisor actualiza el saldo del titular de la tarjeta (los fondos aún no se han transferido). En caso de desacuerdo, puede ocurrir un contracargo (chargeback).

Resumen del proceso de clearing

El proceso de clearing implica coordinar datos de pago, validación y liquidación entre los comerciantes, Akua y las redes de tarjetas. Esto asegura una reconciliación eficiente y pagos precisos.

Pasos del proceso:

1. Inicio: Un cliente (a través de un trabajo programado - cron job) inicia una solicitud para activar el proceso de captura basado en el ID de pago. El proceso puede activarse automáticamente (captura instantánea) o programarse.

2. Validación del pago: El orquestador recupera los detalles del pago desde la API de pagos y verifica la elegibilidad del pago para ser capturado.

3. Notificación: El orquestador utiliza SNS (Simple Notification Service) para notificar a otros servicios sobre el proceso de clearing.

4. Preparación del servicio de clearing: Los datos de la transacción se envían al servicio de clearing para su procesamiento. Los metadatos necesarios se almacenan en la base de datos.

5. Creación del archivo: El servicio de clearing compila un archivo de clearing basado en las transacciones pendientes y los ciclos de compensación.

6. Almacenamiento del archivo: El archivo de clearing se guarda en S3 para propósitos de auditoría y luego se envía a las redes de tarjetas.

Captura de un Pago

La captura conecta la autorización con el clearing y la liquidación. Una vez que un pago es autorizado, la captura confirma que la transacción está lista para ser enviada a las redes de tarjetas, reconciliada y liquidada al comerciante.

Solo los pagos con estado AUTHORIZED pueden ser capturados.

---

Modos de captura

---

Flujo de captura

Modos de Captura

Akua soporta tres modos de captura según las necesidades del negocio: AUTOMATIC, SCHEDULED y MANUAL.

Comparación de modos

Importante: una vez que Akua presenta un pago a la red, no es posible cancelarlo, aunque el ciclo de compensación aún no haya corrido. Comercios con alto índice de cancelaciones deben considerar MANUAL o configurar una hora de captura adecuada.

---

Captura Manual — MANUAL

La captura se activa solo cuando el comerciante envía una solicitud explícita. La transacción permanece en estado AUTHORIZED hasta ese momento.

{
  "capture": {
    "mode": "MANUAL"
  }
}

Si no se envía la petición de captura en aproximadamente 7 días, la autorización expira automáticamente. O 30 días para preautorizaciones.

Casos de uso: compras de alto valor que requieren validación, negocios con alto índice de cancelaciones, modelos que verifican entrega del producto antes de cobrar.

---

Captura Automática — AUTOMATIC

Akua presenta el pago en la próxima ronda (~30 min después de la autorización). No requiere ninguna acción del comerciante.

{
  "capture": {
    "mode": "AUTOMATIC"
  }
}

Casos de uso: e-commerce con pagos instantáneos, suscripciones y cargos recurrentes, tiendas con alto volumen de transacciones.

---

Captura Automática con hora configurada en el merchant

El merchant puede tener una hora diaria de captura configurada en su perfil. En ese caso, Akua solo presenta los pagos en la primera ronda posterior a esa hora.

Ejemplo: hora configurada = 21:00. Si Akua presenta a las 21:30, esos pagos recién se incluyen en esa ronda. Los pagos autorizados antes de las 21:00 esperan hasta ese momento para ser elegibles.

{
  "capture": {
    "mode": "AUTOMATIC"
  }
}

La hora se configura a nivel de merchant desde el Dashboard. No requiere cambios en el request de pago.

Casos de uso: comercios que necesitan agrupar capturas en un horario fijo diario, modelos de negocio con cierre de caja a hora determinada.

---

Captura Automática con capture_after

Permite especificar un datetime exacto a partir del cual el pago es elegible para ser presentado. Akua lo incluye en la primera ronda posterior a ese momento.

{
  "capture": {
    "mode": "AUTOMATIC",
    "capture_after": "2026-02-27T21:00:00Z"
  }
}

El campo acepta timezone explícito — la Z indica UTC. Podés especificar cualquier zona horaria usando el offset correspondiente (ej: 2026-02-27T21:00:00-05:00 para Colombia).

Casos de uso: pagos que deben capturarse en una fecha futura específica, reservas donde el cobro se efectúa el día del servicio.

---

Combinación: hora en merchant + capture_after

Si el merchant tiene una hora de captura configurada y el pago incluye capture_after, el campo de la transacción toma precedencia. El datetime enviado en el request es más específico que la configuración general del merchant.

{
  "capture": {
    "mode": "AUTOMATIC",
    "capture_after": "2026-02-27T22:00:00Z"
  }
}

En este caso, aunque el merchant tenga configuradas las 21:00, el pago no será elegible hasta las 22:00 UTC.

Liquidación

¿Cómo funciona la liquidación?

Es el paso final en el que los fondos se transfieren del banco del tarjetahabiente (emisor) al banco del comerciante (adquirente). Las redes de tarjetas facilitan esta transferencia de fondos entre emisor y adquirente, contabilizando las tarifas aplicables. El adquirente entonces acredita la cuenta del comerciante con el monto de la transacción menos las tarifas.

Diferencias entre Clearing y Settlement

Clearing

Esta fase involucra el intercambio de datos de transacción. Las transacciones se mueven del adquirente al emisor para el registro en la cuenta del tarjetahabiente. Los mensajes de clearing contienen datos, pero no involucran el intercambio o transferencia de fondos.

Settlement

Ocurriendo después del clearing, esta fase consiste en las transferencias reales de fondos. Los fondos representan el valor monetario de las transacciones procesadas y se intercambian entre clientes según la posición neta calculada por Mastercard.

Cashouts

¿Qué es un Cashout?

Un cashout representa el proceso mediante el cual un usuario recibe los fondos acumulados en su cuenta, transfiriéndolos a su método de pago predeterminado. Este mecanismo permite a los clientes obtener pagos de manera rápida y con total transparencia.

Características Clave:

• Opera a través de procesamiento automatizado y periódico para asegurar liquidez del usuario
• Proporciona desgloses detallados de montos y descuentos aplicados antes de la transferencia
• Ofrece seguimiento en dashboard para el estado de cada cashout
• Facilita la gestión financiera del usuario con visibilidad y control completos

Acciones del Cliente

Configurar Método de Pago Predeterminado

Los clientes deben establecer un método de pago predeterminado para recibir fondos de Akua, validado y gestionado a través del dashboard por usuarios autorizados.

Visibilidad del Estado del Cashout

Los usuarios pueden ver cashouts con estados PENDING, PROCESSING y PAID en el dashboard. Detalles adicionales incluyendo recibos de pago y comentarios permanecen accesibles para personal autorizado, junto con información de transacciones asociadas.

Pasos de Gestión

• Revisar detalles del cashout
• Validar información sobre montos, descuentos y pagos asociados
• Subir comprobante de pago

Descarga de Recibo de Pago

Los clientes pueden acceder y ver el comprobante de cada transferencia vinculada a un cashout.

Este flujo de trabajo asegura transparencia y control, permitiendo a los clientes gestionar sus fondos eficientemente.

Diferencias

Las devoluciones agrupan todos los procesos para interrumpir, revertir o reembolsar un pago. Dependiendo del estado en que se encuentre el pago, aplica una u otra modalidad.

---

Cancelación vs. Reembolso

---

Cancelación

Detiene el pago antes de que sea capturado. El monto reservado se libera y nunca se debita al cliente. Es útil para gestionar errores o solicitudes de anulación en etapas tempranas del flujo.

Solo disponible en pagos con estado CREATED o AUTHORIZED.

---

Reembolso (Refund)

Cuando el pago ya fue capturado o liquidado, no es posible cancelarlo. El reembolso devuelve el monto al cliente a través de la misma fuente de pago.

Cancelación

Descripción

La cancelación de pagos permite detener el procesamiento de una transacción antes de que alcance las etapas de captura y liquidación. Esta acción está restringida a fases específicas del flujo de pago y debe cumplir con las políticas de autorización y captura.

¿Cuándo Puede Cancelarse un Pago?

Los pagos pueden cancelarse durante estas etapas:

• Created: El pago existe pero no ha pasado por autorización
• Authorized: El pago está aprobado pero aún no capturado

Estados del Proceso de Cancelación

El flujo de cancelación incluye estas etapas:

Estado Created

• El pago está pendiente de autorización
• Cancelación directa posible antes de que comience la autorización
• Transición: Created → Cancelled

Estado Pending Authorization

• El pago espera aprobación de autorización
• Cancelación permitida antes de que inicie la captura
• Transición: Pending authorization → Cancelled

Estado Authorized

• El pago está aprobado y listo para captura
• Cancelación disponible antes de que comience la captura
• Transición: Authorized → Cancelled

Estado Cancelled

• Cancelación exitosa desde estados anteriores
• Marcado como "Cancelled"
• No ocurre procesamiento de captura o liquidación

---

Relación Cancelación vs. Reembolso

Una vez que un pago alcanza captura o liquidación, la cancelación se vuelve imposible. En este punto, debe iniciarse un proceso de reembolso en su lugar.

Escenarios clave:

• Pagos autorizados pero no capturados pueden cancelarse
• Pagos capturados o liquidados requieren procesamiento de reembolso

Errores Comunes de Cancelación

Falla/Rechazo

Causas:

• El estado del pago no permite cancelación
• Restricciones del procesador de pagos

Soluciones:

• Verificar el estado del pago antes de intentar cancelación
• Contactar soporte técnico para fallas recurrentes

Reembolso

Descripción

El proceso de reembolso permite la reversión de pagos previamente capturados. Esta documentación describe las etapas, estados involucrados y posibles transiciones en el flujo de reembolso.

Estados Iniciales para un Reembolso

Un reembolso puede iniciarse desde cualquiera de estos estados de pago:

• Captured: El pago ha sido capturado.
• Settled: El pago ha sido liquidado.

¿Cuándo Puedo Procesar un Reembolso?

Los reembolsos solo pueden ejecutarse si el estado del pago es válido y cumple con las políticas definidas por la plataforma.

---

Estados del Proceso de Reembolso

El flujo de reembolso incluye estos estados clave:

REFUND IN PROCESS / PRESENTED

• Indica que el reembolso ha sido solicitado y está siendo procesado
• Se genera un registro de transacción para seguimiento

REFUND COMPLETED

• Muestra procesamiento exitoso del reembolso
• La transacción asociada se marca como reembolsada
• En algunos casos, el pago regresa a estado Settled una vez liquidado

REFUND FAILED / REJECTED

• Indica reembolso incompleto debido a errores técnicos, fondos insuficientes o restricciones de la plataforma
• El estado del pago permanece sin cambios

NO UPDATE

• Usado cuando la confirmación del resultado del reembolso no está disponible

---

Relaciones de Estado

Los reembolsos interactúan con estados clave del flujo de pago:

• Captured → Reembolso en Proceso: El reembolso inicia después de la captura del pago
• Settled → Reembolso Completado: Un reembolso exitoso puede devolver el pago a estado Settled

Errores Comunes y Soluciones

Reembolso Fallido

• Causa: Restricciones de fondos o fallas técnicas
• Solución: Verificar con el procesador de pagos o reenviar solicitud

Sin Actualización

• Causa: Falla de comunicación con sistema externo
• Solución: Escalar a soporte técnico

Mejores Prácticas

• Verificar el estado del pago antes de iniciar el reembolso
• Mantener registros de todas las transacciones asociadas al reembolso
• Implementar validaciones que prevengan reembolsos en estados inválidos

Contracargos

¿Cómo se administran los Contracargos?

En Akua, el objetivo es ofrecer un mecanismo fácil y sencillo tanto para clientes como para operadores. Los clientes acceden a información detallada sobre cada chargeback, pueden cargar evidencias y realizar seguimientos del estado. Los operadores de Akua monitorean y gestionan el ciclo de vida de los chargebacks, actualizando su estado y comunicándose con clientes.

¿Cómo gestionar los contracargos en dashboard?

Acceso a la Sección de Chargebacks

Para gestionar un chargeback, ingresa a la sección Chargebacks dentro del módulo Risk en el dashboard de Akua. Desde allí, podrás visualizar y administrar todos los casos abiertos.

Visualización de Chargebacks

Cada chargeback registrado incluye:

Detalle del Chargeback

Al seleccionar un chargeback específico, accederás a:

• Información básica: ID, fecha de notificación, motivo, estado
• Historial del caso: Registro cronológico de cambios y evidencias
• Acciones disponibles: Aceptar, disputar, solicitar información, escalar

Subir Evidencia para Disputa

El proceso incluye:

1. Selecciona el chargeback en estado "UNDER REVIEW"
2. Dirígete a la sección Subir Evidencia
3. Adjunta archivos (PDF, JPEG, PNG)
4. Asegúrate de cumplir requisitos de documentación
5. Sigue el indicador de progreso
6. Confirma la acción

Nota: Los tiempos dependen de plazos establecidos por la entidad adquirente y red de pagos.

Manejo de estados en un chargeback

Resumen: guía de Integración

Endpoint: POST /v1/payments/authorizations

Esta guía cubre los distintos escenarios de autorización que soporta la API. Todos los ejemplos usan entry_mode: "not-present" (e-commerce / tarjeta no presente).

---

Campos base

Toda autorización requiere como mínimo estos campos:

0. Verificación de cuenta (account-status)

Transacción de monto cero para verificar que una tarjeta es válida y está activa, sin generar un cobro. Se usa intent: "account-status" y no se envía amount ni capture.

{
    "intent": "account-status",
    "entry_mode": "not-present",
    "order_type": "purchase",
    "initiator": "customer",
    "merchant_id": "mer-xxxxxxxxxx",
    "instrument": {
        "type": "CARD",
        "card": {
            "number": "53830400xxxx0002",
            "cvv": "917",
            "expiration_month": "12",
            "expiration_year": "30",
            "holder_name": "Juan Rodriguez"
        }
    },
    "customer_data": {
        "billing_address": {
            "street": "Calle 26",
            "number": "45A-60",
            "city": "Bogotá",
            "state": "Cundinamarca",
            "zip_code": "110911",
            "country": "COL"
        }
    }
}

Casos de uso típicos: validar tarjeta antes de guardarla en bóveda, confirmar que la tarjeta sigue activa antes de un cobro recurrente, o verificar datos del titular.

1. Pago con PAN directo

El caso más simple: se envían los datos crudos de la tarjeta.

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "purchase",
    "initiator": "customer",
    "capture": {
        "mode": "AUTOMATIC"
    },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": {
        "value": 25000.00,
        "currency": "COP"
    },
    "instrument": {
        "type": "CARD",
        "card": {
            "number": "53830400xxxx0002",
            "cvv": "917",
            "expiration_month": "12",
            "expiration_year": "30",
            "holder_name": "Juan Rodriguez"
        }
    },
    "customer_data": {
        "billing_address": {
            "street": "Calle 26",
            "number": "45A-60",
            "city": "Bogotá",
            "state": "Cundinamarca",
            "zip_code": "110911",
            "country": "COL"
        }
    }
}

customer_data.billing_address es opcional pero recomendado: mejora la tasa de aprobación y alimenta los modelos antifraude.

2. Pago con impuestos (transaction_compliance)

Para jurisdicciones que requieren reportar impuestos en la transacción, se agrega el objeto transaction_compliance con un array de taxes. Hay tres formas de declararlo según la información disponible en el comercio.

---

Caso 1: IVA por porcentaje

El sistema asume que amount.value ya incluye el IVA y calcula la base gravable automáticamente.

"transaction_compliance": {
    "taxes": [
        {
            "code": "IVA",
            "percentage": "19"
        }
    ]
}

Para un monto de 1000 COP, la respuesta descompondría: base gravable = 840.34, IVA = 159.66.

---

Caso 2: IVA como monto fijo

Cuando el comercio ya conoce el monto exacto del impuesto, se declara directamente en tax_amount y se envía percentage: "0".

"transaction_compliance": {
    "taxes": [
        {
            "code": "IVA",
            "percentage": "0",
            "tax_amount": {
                "value": "200",
                "currency": "COP"
            }
        }
    ]
}

Para un monto de 1000 COP, la respuesta descompondría: base gravable = 800, IVA = 200.

---

Caso 3: IVA por porcentaje con base gravable explícita

Cuando solo una parte del monto total es gravable (por ejemplo, el envío o servicios exentos no aplican IVA), el comercio declara la base gravable en taxable_amount. El porcentaje se aplica únicamente sobre ese valor.

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "purchase",
    "initiator": "customer",
    "capture": {
        "mode": "AUTOMATIC"
    },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": {
        "value": 100000,
        "currency": "COP"
    },
    "instrument": {
        "type": "CARD",
        "card": {
            "number": "53830400xxxx0002",
            "cvv": "917",
            "expiration_month": "12",
            "expiration_year": "30",
            "holder_name": "Juan Rodriguez"
        }
    },
    "customer_data": {
        "billing_address": {
            "street": "Calle 26",
            "number": "45A-60",
            "city": "Bogotá",
            "state": "Cundinamarca",
            "zip_code": "110911",
            "country": "COL"
        }
    },
    "transaction_compliance": {
        "taxes": [
            {
                "code": "IVA",
                "percentage": "19",
                "taxable_amount": {
                    "value": "84034",
                    "currency": "COP"
                }
            }
        ]
    }
}

La respuesta aplicaría el 19% solo sobre 84034: IVA = 15966.46. El remanente (100000 - 84034 - 15966.46) se trata como porción no gravable.

---

Nota: El campo percentage siempre debe enviarse como string. Los casos 1 y 3 son mutuamente excluyentes con el caso 2: no se debe combinar percentage con valor mayor a "0" junto a tax_amount.

3. Pago con datos antifraude

Enviar datos adicionales del comprador mejora la evaluación de riesgo. Todos los campos dentro de customer_data son opcionales, pero entre más datos se envíen, mejor será la evaluación.

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "purchase",
    "initiator": "customer",
    "capture": {
        "mode": "AUTOMATIC"
    },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": {
        "value": 25000.00,
        "currency": "COP"
    },
    "instrument": {
        "type": "CARD",
        "card": {
            "number": "53830400xxxx0002",
            "cvv": "917",
            "expiration_month": "12",
            "expiration_year": "30",
            "holder_name": "Juan Rodriguez"
        }
    },
    "customer_data": {
        "billing_address": {
            "street": "Calle 26",
            "number": "45A-60",
            "city": "Bogotá",
            "state": "Cundinamarca",
            "zip_code": "110911",
            "country": "COL"
        },
        "delivery_address": {
            "street": "Av. Libertador",
            "number": "1234",
            "city": "Buenos Aires",
            "state": "Buenos Aires",
            "zip_code": "C1001",
            "country": "ARG"
        },
        "email": "user@example.com",
        "phone_number": "+57899123456",
        "device_fingerprint": "a1b2c3d4e5f6g7h8i9j0",
        "ip_address": "203.0.113.42",
        "latitude": "-34.9011",
        "longitude": "-56.1645"
    }
}

Campos antifraude disponibles: email, phone_number, device_fingerprint, ip_address, latitude, longitude, delivery_address. Enviar delivery_address cuando la dirección de entrega difiere de la de facturación permite detectar patrones de fraude.

4. Pago con 3D Secure

Cuando el comercio ejecuta autenticación 3DS antes del cobro, se incluyen los campos eci y three_ds con los datos resultantes de la autenticación.

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "purchase",
    "initiator": "customer",
    "eci": "02",
    "capture": {
        "mode": "AUTOMATIC"
    },
    "three_ds": {
        "cavv": "K0nxdecnwejnckdnsfv3i4f",
        "version": "2.6.1.1",
        "ds_transaction_id": "021956238443987999831863072557355283"
    },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": {
        "value": 25000.00,
        "currency": "COP"
    },
    "instrument": {
        "type": "CARD",
        "card": {
            "number": "53830400xxxx0002",
            "cvv": "917",
            "expiration_month": "12",
            "expiration_year": "30",
            "holder_name": "Juan Rodriguez"
        }
    },
    "customer_data": {
        "billing_address": {
            "street": "Calle 26",
            "number": "45A-60",
            "city": "Bogotá",
            "state": "Cundinamarca",
            "zip_code": "110911",
            "country": "COL"
        }
    }
}

5. Pago con cuotas

Para diferir el cobro en cuotas, se agrega el objeto installments.

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "purchase",
    "initiator": "customer",
    "capture": {
        "mode": "AUTOMATIC"
    },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": {
        "value": 25000.00,
        "currency": "COP"
    },
    "instrument": {
        "type": "CARD",
        "card": {
            "number": "53830400xxxx0002",
            "cvv": "917",
            "expiration_month": "12",
            "expiration_year": "30",
            "holder_name": "Juan Rodriguez"
        }
    },
    "customer_data": {
        "billing_address": {
            "street": "Calle 26",
            "number": "45A-60",
            "city": "Bogotá",
            "state": "Cundinamarca",
            "zip_code": "110911",
            "country": "COL"
        }
    },
    "installments": {
        "type": "issuer-financed",
        "quantity": 12
    }
}

Nota: el campo type es recomendado. Si no se especifica, el comportamiento depende de la configuración del adquirente. Además, la cantidad de cuotas debe ser un valor válido según la red y el emisor (valores comunes: 2, 3, 6, 12, 18, 24, 36).

6. Pago con instrumento (tokenizado)

Si previamente se almacenó un instrumento en la bóveda de Akua, basta enviar su id sin necesidad de los datos de tarjeta.

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "purchase",
    "initiator": "customer",
    "capture": {
        "mode": "AUTOMATIC"
    },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": {
        "value": 30000,
        "currency": "COP"
    },
    "instrument": {
        "id": "ins-xxxxxxxxxx"
    },
    "customer_data": {
        "billing_address": {
            "street": "Calle 26",
            "number": "45A-60",
            "city": "Bogotá",
            "state": "Cundinamarca",
            "zip_code": "110911",
            "country": "COL"
        }
    }
}

Al usar instrument.id, no se requieren instrument.type ni instrument.card. La plataforma recupera los datos del instrumento desde la bóveda.

7. Pago con Network Token

Para pagos con billeteras digitales (Apple Pay, Google Pay, etc.), se usa instrument.type: "NETWORK_TOKEN" con los datos del token de red.

{
    "intent": "authorization",
    "entry_mode": "not-present",
    "order_type": "purchase",
    "initiator": "customer",
    "capture": {
        "mode": "AUTOMATIC"
    },
    "merchant_id": "mer-xxxxxxxxxx",
    "amount": {
        "value": 30000,
        "currency": "COP"
    },
    "instrument": {
        "type": "NETWORK_TOKEN",
        "network_token": {
            "token": "51861700xxxx1108",
            "cryptogram": "Qwertyuio09876543",
            "provider": "apple-pay",
            "device_type": "phone",
            "url": "some.merchant.url"
        }
    },
    "customer_data": {
        "billing_address": {
            "street": "Calle 26",
            "number": "45A-60",
            "city": "Bogotá",
            "state": "Cundinamarca",
            "zip_code": "110911",
            "country": "COL"
        }
    }
}

Merchant Advice Codes (MAC)

Qué son

Los Merchant Advice Codes — o "MAC", también llamados "advice codes" o "códigos de aviso al comercio" — son un mecanismo definido por las redes de tarjetas (Mastercard, Visa, etc.) para que el banco emisor le comunique al comercio por qué rechazó una transacción y qué hacer con ese rechazo.

A diferencia del response_code de la red (que es un código duro: "00 aprobada", "05 no honorar", "51 fondos insuficientes"), el MAC va más allá: te dice si tiene sentido reintentar la transacción, si tenés que actualizar primero los datos de la tarjeta, si necesitás autenticación adicional, o si el rechazo es definitivo y no hay que volver a intentarlo. Sin esta información, un comercio puede reintentar una transacción rechazada miles de veces, lo cual aumenta sus tasas de fraude/disputas con la red, le cuesta dinero por cada reintento y puede llevar a sanciones de la marca.

En la respuesta de Akua, el MAC aparece dentro de transaction.network_data y solo cuando el rechazo viene acompañado de un advice code por parte del emisor. No todos los rechazos traen MAC: algunos errores técnicos (timeouts de red, fallas de Akua) responden sin merchant advice porque la transacción ni siquiera llegó al emisor.

---

Tres campos, uno solo importa para automatizar

Akua expone tres campos relacionados al MAC:

"network_data": {
  "merchant_advice_code": "41",
  "merchant_advice_description": "New account information available",
  "merchant_advice_action": "DO_NOT_RETRY"
}

• merchant_advice_code: el código numérico de 2 caracteres definido por la red (01, 02, 03, 04, 21, 24, 40, 41, 42, 43...). Es el dato crudo que reporta el emisor.
• merchant_advice_description: la descripción legible del código, en inglés. Útil para mostrar al usuario interno o loguear.
• merchant_advice_action: la acción que Akua te recomienda tomar, derivada del código. Esto es lo que tu integración debería usar para decidir el flujo automáticamente.

Solo merchant_advice_action es enum cerrado — los otros dos son strings libres que pasan tal cual los entrega la red. Eso significa que si tu lógica depende del código exacto, tenés que estar preparado para valores nuevos que la red puede agregar sin previo aviso. Si en cambio te basás en la action, tu código sigue funcionando aunque aparezcan códigos nuevos.

---

Las cuatro acciones posibles

merchant_advice_action es un enum con cuatro valores. Cada uno te dice exactamente qué hacer:

RETRY

El emisor rechazó la transacción por una causa transitoria (saturación temporal, problema de comunicación, etc.). Reintentar más tarde tiene buenas chances de aprobar.

Recomendación de uso: aplicar un backoff (por ejemplo esperar 10–30 minutos antes del siguiente intento) y reintentar máximo 1 o 2 veces con los mismos datos. Sin backoff, la red puede penalizarte por reintento agresivo.

UPDATE_AND_RETRY

El instrumento de pago tiene un problema que el cliente debe resolver antes de que la transacción pueda aprobarse. Típicamente es: tarjeta vencida, número incorrecto, cuenta cambiada de banco, o que el emisor ya emitió una tarjeta nueva con otros datos.

Recomendación de uso: pedirle al cliente que actualice los datos de la tarjeta (o que use otra). No reintentar con los mismos datos — el emisor te va a seguir rechazando. Si tenés Account Updater habilitado con la red, este es el momento de invocarlo antes de reintentar.

AUTHENTICATE_AND_RETRY

El emisor rechazó la autorización porque el riesgo del fraude le pareció alto, pero te está sugiriendo que si la próxima vez la mandás con autenticación 3D Secure, probablemente la apruebe.

Recomendación de uso: redirigir al cliente al flujo 3DS (típicamente "Smart 3DS" o el flujo de autenticación que tenga el comercio configurado), obtener el CAVV/cryptogram y reintentar la transacción incluyendo los datos de autenticación. Sin la autenticación, el emisor va a volver a rechazar.

DO_NOT_RETRY

El rechazo es definitivo. La cuenta está cerrada, la tarjeta cancelada, hubo fraude confirmado, o el cliente pidió no aceptar más cobros del comercio. Reintentar sin importar qué hagas va a fallar y, peor, te puede generar penalizaciones.

Recomendación de uso: marcar la transacción como permanentemente rechazada en tu sistema, no incluir ese instrumento en reintentos automáticos, no incluir esa cuenta en cobros recurrentes futuros (esto último es especialmente importante para suscripciones — la red sanciona a comercios que siguen cobrando contra cuentas con MAC=DO_NOT_RETRY).

---

Tabla de códigos comunes

Esta es una referencia de los MAC más frecuentes que se ven en la red Mastercard. No es exhaustiva — la lista se actualiza con cada release de la marca y puede haber códigos específicos de Visa u otras redes que entreguen los emisores. Para el listado oficial completo de Mastercard, consultar el manual Customer Interface Specification (CIS) capítulo de Authorization Responses.

Cuando Akua mapea el código a la action, prima el merchant_advice_action que devolvemos sobre cualquier interpretación que hagas del código numérico — porque ese mapeo lo mantiene actualizado el equipo a medida que cambian las reglas de las redes.

---

Combinación con response_code

El MAC siempre va acompañado de un response_code de la red. La combinación da más contexto: el response_code te dice por qué fue rechazada (la causa nominal), el MAC te dice qué hacer. Algunos ejemplos:

Notar que el mismo response_code puede venir con MACs distintos según la decisión del emisor en cada caso particular. Por eso conviene siempre mirar el MAC, no solo el response code.

---

Casos donde NO viene MAC

El campo merchant_advice_code puede estar ausente en varios escenarios:

• Transacciones aprobadas: si transaction.status es APPROVED, no hay MAC porque no hay rechazo que aconsejar.
• Errores de Akua antes de la red: validaciones que fallan en el middleware (formato inválido, instrumento bloqueado en Akua, cliente sin habilitar el método de pago) responden sin MAC porque la transacción nunca llegó al emisor. En estos casos decision_source suele ser INTERNAL.
• Errores de sistema en la red: timeouts o fallas de comunicación responden con response_code 96 (System error) y típicamente sin MAC, porque el emisor nunca evaluó la transacción. La acción razonable acá es RETRY.
• Emisores antiguos: algunos emisores no implementan MAC todavía y rechazan solo con response_code. En esos casos el integrador tiene que tomar la decisión basándose solo en el código de respuesta.

Tu integración debería tratar la ausencia del campo como "no hay info adicional, decidí con el response_code solo".

---

Cómo usarlo en tu integración

Pseudocódigo recomendado:

respuesta = autorizar_pago(...)

if respuesta.transaction.status == "APPROVED":
    confirmar_compra()

elif respuesta.transaction.status == "REJECTED":
    advice = respuesta.transaction.network_data.merchant_advice_action

    if advice == "RETRY":
        encolar_reintento(esperar_minutos=15, max_intentos=2)
    elif advice == "UPDATE_AND_RETRY":
        invocar_account_updater_o_pedir_nueva_tarjeta_al_cliente()
    elif advice == "AUTHENTICATE_AND_RETRY":
        redirigir_a_3ds()
    elif advice == "DO_NOT_RETRY":
        marcar_instrumento_como_no_reusable()
        notificar_al_cliente("la tarjeta fue rechazada, contactá a tu banco")
    else:
        # No vino advice — decidir basado en response_code o defaultear a no-reintentar
        loggear_para_revision_manual()

Tres reglas duras que conviene respetar siempre:

1. DO_NOT_RETRY significa no reintentar nunca, ni manualmente ni con Account Updater. La red lo audita y los reintentos contra cuentas marcadas así pueden generar fees o sanciones.
2. RETRY no significa "reintentá inmediatamente". Esperá al menos 10 minutos. Reintentos sin backoff disparan alertas de fraude en la red.
3. AUTHENTICATE_AND_RETRY requiere 3DS real, no se reemplaza con un retry simple. El emisor está pidiendo el step-up de autenticación.

Transacciones de Tránsito (MTT) — Resumen

Las transacciones de tránsito son un tipo especial de pago sin contacto (contactless) diseñado para sistemas de transporte público: buses, metro, trenes, tranvías, peajes y más. Se diferencian de las transacciones retail convencionales en tres aspectos fundamentales:

• La tarifa puede no ser conocida al momento del tap. En muchos sistemas de transporte, el monto final depende de la distancia recorrida o del tiempo de uso, por lo que se calcula después del viaje.
• La autorización puede ser diferida. El pasajero debe poder abordar sin esperar una respuesta online del emisor.
• No se requiere verificación del titular (CVM). No se pide PIN ni firma — el pasajero simplemente acerca su tarjeta al lector.

Todas las transacciones de tránsito cursadas por POS usan el endpoint de tarjeta presente (/pos/...) y requieren entry_mode: "contactless". El comercio debe estar registrado con un MCC de tránsito: 4111 (transporte local/suburbano), 4112 (trenes de pasajeros) o 4131 (líneas de bus).

Importante — todo lo /pos/ es tarjeta presente. Cada autorización por POS se envía exactamente como una venta card-present: con terminal_id y un instrument que incluye los datos de la lectura física de la tarjeta (track2_data y, para chip/contactless, los emv_data.tags). No se envía el PAN en claro vía instrument.card.number como en e-commerce. Si falta el track2_data, el endpoint responde 500 — "Failed to process track2 data". La única excepción es la Recuperación de deuda, que es card-not-present (e-commerce) y usa instrument.id.

Headers requeridos en todas las llamadas. Cada request (autorización, ajuste, captura, etc.) debe enviar: Authorization: Bearer {access_token}, Content-Type: application/json y un Idempotency-Key único por request (UUIDv4 recomendado). Probar sin estos headers puede romper la llamada. El Idempotency-Key garantiza at-most-once: reintentar con la misma clave y mismo body devuelve la respuesta original; con body distinto devuelve 409 CONFLICT.

---

Modelos de transacción

Dependiendo de si la tarifa es conocida o no al momento del tap, y de la situación particular, existen distintos modelos:

---

Mapa de campos por caso de uso

Estas tablas muestran de un vistazo qué endpoint y qué campos se usan en cada caso de uso. Se leen de izquierda a derecha como un flujo progresivo: del caso más simple (Retail-Like) al más especial (Recuperación de deuda).

Mastercard

Visa

Fase 2 — Ajuste vs. Captura: para finalizar el período PAYG hay dos opciones. El ajuste (/adjust) genera una nueva autorización por la diferencia usando amount.value (string); puede fallar si no hay fondos, pero permite montos sin límite. La captura (/captures) confirma el cobro sin nueva autorización usando amount.value (número); no falla, pero solo permite hasta un 20% por encima de la pre-autorización original. Ver la guía de Agrupación PAYG para el detalle completo.

---

Diferencias clave entre redes

Mastercard y Visa siguen el mismo concepto general pero difieren en la implementación:

• En Agrupación PAYG, Mastercard usa una pre-autorización con monto nominal en la Fase 1 y un adjust en la Fase 2. Visa hace un account-status (monto cero) en la Fase 1 y una autorización diferida (deferred) como MIT en la Fase 2.
• El ATC Counter Update es exclusivo de Mastercard. Visa no define un mecanismo equivalente, aunque los emisores Visa deben tolerar contadores fuera de secuencia sin declinar.
• En Recuperación de deuda, ambas redes usan el mismo enfoque: una autorización con order_type: "resubmission" vía el endpoint de e-commerce (no POS), ya que la tarjeta no está presente en ese momento.

---

Guías detalladas

Para el paso a paso de cada modelo con ejemplos de request completos, consultar las guías específicas:

• Retail-Like — Pago con tarifa conocida al momento del tap
• Agrupación PAYG — Ciclo Pay-As-You-Go para tarifas desconocidas
• Recuperación de Deuda — Cobro de tarifas pendientes
• ATC Counter Update — Sincronización del contador de transacciones (Mastercard)

Retail-Like (Tarifa Conocida)

Modelo para cuando la tarifa es conocida al momento del tap. Se procesa una autorización por viaje, igual que una compra retail convencional pero con las particularidades de tránsito: contactless, sin CVM, y con MCC de transporte.

Endpoint: POST /pos/payments/authorizations

Recordatorio card-present: al ser un endpoint /pos/, el request va como una venta con tarjeta presente. Es obligatorio enviar terminal_id, amount, intent y un instrument con track2_data (y los emv_data.tags de la lectura contactless). No se envía el PAN en claro.

---

Cuándo usar

Sistemas de transporte donde el pasajero paga una tarifa fija por viaje. Ejemplos: bus urbano con tarifa plana, metro con tarifa única por estación de origen, peaje con tarifa fija.

---

Flujo

El flujo es simple — un solo paso:

1. El pasajero acerca su tarjeta al lector contactless
2. La terminal arma el track2_data + emv_data y el sistema envía una autorización por el monto exacto de la tarifa
3. Se recibe la respuesta (aprobada o denegada)
4. Si se aprueba, el pasajero viaja. Si se deniega, la tarjeta entra en la deny list del operador

---

Mastercard

POST /pos/payments/authorizations
Authorization: Bearer {access_token}
Content-Type: application/json
Idempotency-Key: {uuid-v4-único-por-request}

{
    "id": "ride-7f3a9c01",
    "intent": "authorization",
    "order_type": "purchase",
    "entry_mode": "contactless",
    "capture": {
        "mode": "AUTOMATIC"
    },
    "terminal_id": "trm-d49abonq5g3h7p5qnpbb",
    "amount": {
        "value": 2950,
        "currency": "COP"
    },
    "instrument": {
        "emv_data": {
            "sequence_number": 0,
            "tags": [
                { "tag": "82",   "length": "2",  "value": "1980" },
                { "tag": "84",   "length": "7",  "value": "a0000000041010" },
                { "tag": "95",   "length": "5",  "value": "0000048001" },
                { "tag": "9A",   "length": "3",  "value": "260626" },
                { "tag": "9C",   "length": "1",  "value": "00" },
                { "tag": "5F2A", "length": "2",  "value": "0170" },
                { "tag": "9F02", "length": "6",  "value": "000000002950" },
                { "tag": "9F03", "length": "6",  "value": "000000000000" },
                { "tag": "9F1A", "length": "2",  "value": "0170" },
                { "tag": "9F10", "length": "18", "value": "0210a040032400000000ffffffffffffffff" },
                { "tag": "9F26", "length": "8",  "value": "5e746608800d2b55" },
                { "tag": "9F27", "length": "1",  "value": "80" },
                { "tag": "9F33", "length": "3",  "value": "004088" },
                { "tag": "9F34", "length": "3",  "value": "1f0302" },
                { "tag": "9F36", "length": "2",  "value": "01e5" },
                { "tag": "9F37", "length": "4",  "value": "20c1bd34" }
            ]
        },
        "track2_data": {
            "data": "5383040000000002D30122011000000000000",
            "encrypted": false
        }
    }
}

Notas sobre Mastercard:

• intent: "authorization" con capture.mode: "AUTOMATIC" — autorización + captura en tiempo real (venta directa).
• instrument.emv_data.tags lleva los tags de la lectura contactless (AID Mastercard a0000000041010 en el tag 84). El 9F34 (CVM Results) refleja "No CVM" porque tránsito no pide PIN ni firma.
• track2_data.encrypted indica si la pista viaja cifrada. Si va cifrada, se acompaña del ksn de la llave; si el cliente la envía en claro (false), Akua la ofusca internamente.
• No se envía CVV ni pin_block — las terminales de tránsito no los solicitan.
• El MCC del comercio (resuelto por terminal_id) debe ser 4111, 4112 o 4131.

---

Visa

El request tiene la misma estructura que Mastercard; Akua resuelve la red por el BIN de la tarjeta. Solo cambian los datos propios de la tarjeta y el AID (tag 84 = a0000000031010 para Visa).

POST /pos/payments/authorizations
Authorization: Bearer {access_token}
Content-Type: application/json
Idempotency-Key: {uuid-v4-único-por-request}

{
    "id": "ride-7f3a9c02",
    "intent": "authorization",
    "order_type": "purchase",
    "entry_mode": "contactless",
    "capture": {
        "mode": "AUTOMATIC"
    },
    "terminal_id": "trm-d49abonq5g3h7p5qnpbb",
    "amount": {
        "value": 2950,
        "currency": "COP"
    },
    "instrument": {
        "emv_data": {
            "sequence_number": 0,
            "tags": [
                { "tag": "82",   "length": "2",  "value": "1980" },
                { "tag": "84",   "length": "7",  "value": "a0000000031010" },
                { "tag": "95",   "length": "5",  "value": "0000048001" },
                { "tag": "9A",   "length": "3",  "value": "260626" },
                { "tag": "9C",   "length": "1",  "value": "00" },
                { "tag": "5F2A", "length": "2",  "value": "0170" },
                { "tag": "9F02", "length": "6",  "value": "000000002950" },
                { "tag": "9F03", "length": "6",  "value": "000000000000" },
                { "tag": "9F1A", "length": "2",  "value": "0170" },
                { "tag": "9F10", "length": "7",  "value": "06010a03a00000" },
                { "tag": "9F26", "length": "8",  "value": "a1b2c3d4e5f60718" },
                { "tag": "9F27", "length": "1",  "value": "80" },
                { "tag": "9F33", "length": "3",  "value": "e0f8c8" },
                { "tag": "9F34", "length": "3",  "value": "1f0302" },
                { "tag": "9F36", "length": "2",  "value": "00c7" },
                { "tag": "9F37", "length": "4",  "value": "8e2f1a44" }
            ]
        },
        "track2_data": {
            "data": "4761120000000148D30122011000000000000",
            "encrypted": false
        }
    }
}

---

Respuesta esperada

La respuesta sigue la estructura estándar de autorización POS (HTTP 201):

{
    "terminal": {
        "id": "trm-d49abonq5g3h7p5qnpbb",
        "batch_id": "2500011"
    },
    "payment_id": "pay-dggb2i4h3gkiv2a3adf7",
    "transaction": {
        "id": "trx-d54i8900icdm50jdldvj",
        "type": "AUTHORIZATION",
        "amount": "2950",
        "status": "APPROVED",
        "issuer_data": {
            "emv_tags": [
                { "tag": "91", "length": "0A", "value": "625A65E467ABB0470012" }
            ]
        },
        "network_data": {
            "approval_code": "772886",
            "response_code": "00",
            "response_code_description": "Approved or completed successfully",
            "financial_network_code": "MCC",
            "system_trace_audit_number": "621157"
        },
        "status_detail": "SUCCESS"
    },
    "instrument_id": "ins-hj4i86u64q0ma1v5phh6",
    "response_code": "00",
    "response_code_description": "Approved or completed successfully"
}

El issuer_data.emv_tags devuelve los tags de respuesta del emisor (p. ej. 91 — Issuer Authentication Data) que la terminal debe entregar al chip para completar la transacción.

Si la transacción es denegada, el operador de transporte debe agregar la tarjeta a su deny list local para evitar que se use en viajes posteriores hasta que se resuelva la deuda (ver guía de Recuperación de Deuda).

Agrupación PAYG (Pay-As-You-Go)

Modelo para cuando la tarifa no es conocida al momento del tap. El monto final se calcula después, una vez que el pasajero finaliza su viaje o su período de uso. El operador agrupa los viajes del período y envía una autorización final con el monto total acumulado.

Este modelo tiene dos fases: una al inicio del viaje (intradía) y otra al finalizar el período de agrupación.

Recordatorio card-present: la Fase 1 (primer tap) es tarjeta presente, por lo que el instrument lleva track2_data + emv_data y terminal_id. La Fase 2 de Visa (autorización diferida) y los ajustes/capturas operan sobre el pago ya creado, así que usan instrument.id o el payment_id, sin volver a leer la tarjeta.

---

Cuándo usar

Sistemas de transporte donde la tarifa depende de la distancia, el tiempo o la cantidad de viajes. Ejemplos: metro con tarifas por zonas, tren con tarifa por distancia, sistemas con tope diario (fare capping).

---

Flujo general

Fase 1 — Primer tap (intradía)
    ↓
El pasajero viaja durante el día (puede hacer múltiples taps)
    ↓
Fase 2 — Finalizar período (el back-office calcula el total)
    ↓
Se cobra el monto acumulado real

El operador asume el First Ride Risk: el pasajero viaja antes de que se confirme si la tarjeta es válida y tiene fondos. Si la autorización inicial es denegada, la tarjeta va a la deny list y la deuda se intenta recuperar posteriormente.

---

Fase 1 — Intradía (primer tap del período)

Mastercard — Pre-autorización

Se envía una pre-autorización con un monto nominal (equivalente a 1-3 viajes típicos). Esto reserva fondos iniciales y valida la tarjeta. Es card-present: lleva track2_data + emv_data.

POST /pos/payments/authorizations
Authorization: Bearer {access_token}
Content-Type: application/json
Idempotency-Key: {uuid-v4-único-por-request}

{
    "id": "payg-mc-7f3a9c10",
    "intent": "pre-authorization",
    "order_type": "purchase",
    "entry_mode": "contactless",
    "capture": {
        "mode": "MANUAL"
    },
    "terminal_id": "trm-d49abonq5g3h7p5qnpbb",
    "amount": {
        "value": 8850,
        "currency": "COP"
    },
    "instrument": {
        "emv_data": {
            "sequence_number": 0,
            "tags": [
                { "tag": "82",   "length": "2",  "value": "1980" },
                { "tag": "84",   "length": "7",  "value": "a0000000041010" },
                { "tag": "95",   "length": "5",  "value": "0000048001" },
                { "tag": "9A",   "length": "3",  "value": "260626" },
                { "tag": "9C",   "length": "1",  "value": "00" },
                { "tag": "5F2A", "length": "2",  "value": "0170" },
                { "tag": "9F02", "length": "6",  "value": "000000008850" },
                { "tag": "9F03", "length": "6",  "value": "000000000000" },
                { "tag": "9F1A", "length": "2",  "value": "0170" },
                { "tag": "9F10", "length": "18", "value": "0210a040032400000000ffffffffffffffff" },
                { "tag": "9F26", "length": "8",  "value": "5e746608800d2b55" },
                { "tag": "9F27", "length": "1",  "value": "80" },
                { "tag": "9F33", "length": "3",  "value": "004088" },
                { "tag": "9F34", "length": "3",  "value": "1f0302" },
                { "tag": "9F36", "length": "2",  "value": "01e5" },
                { "tag": "9F37", "length": "4",  "value": "20c1bd34" }
            ]
        },
        "track2_data": {
            "data": "5383040000000002D30122011000000000000",
            "encrypted": false
        }
    }
}

El monto de la pre-autorización es un estimado nominal — no es el cobro final. Típicamente se usa el valor de 1 a 3 viajes como referencia. El capture.mode: "MANUAL" deja el pago pre-autorizado para finalizarlo en la Fase 2.

Importante: guardar el payment_id de la respuesta. Se necesita para la Fase 2 (adjust o capture).

Visa — Account Status (verificación de monto cero)

Visa usa un enfoque distinto: en lugar de pre-autorizar un monto, se envía una verificación de cuenta con monto cero. Esto valida que la tarjeta exista y esté activa sin reservar fondos. Sigue siendo card-present (la tarjeta está físicamente en el lector), por lo que también lleva track2_data + emv_data.

POST /pos/payments/authorizations
Authorization: Bearer {access_token}
Content-Type: application/json
Idempotency-Key: {uuid-v4-único-por-request}

{
    "id": "payg-visa-7f3a9c11",
    "intent": "account-status",
    "order_type": "purchase",
    "entry_mode": "contactless",
    "terminal_id": "trm-d49abonq5g3h7p5qnpbb",
    "amount": {
        "value": 0,
        "currency": "COP"
    },
    "instrument": {
        "emv_data": {
            "sequence_number": 0,
            "tags": [
                { "tag": "82",   "length": "2",  "value": "1980" },
                { "tag": "84",   "length": "7",  "value": "a0000000031010" },
                { "tag": "95",   "length": "5",  "value": "0000008000" },
                { "tag": "9A",   "length": "3",  "value": "260626" },
                { "tag": "9C",   "length": "1",  "value": "00" },
                { "tag": "5F2A", "length": "2",  "value": "0170" },
                { "tag": "9F02", "length": "6",  "value": "000000000000" },
                { "tag": "9F03", "length": "6",  "value": "000000000000" },
                { "tag": "9F1A", "length": "2",  "value": "0170" },
                { "tag": "9F10", "length": "7",  "value": "06010a03a00000" },
                { "tag": "9F26", "length": "8",  "value": "a1b2c3d4e5f60718" },
                { "tag": "9F27", "length": "1",  "value": "80" },
                { "tag": "9F33", "length": "3",  "value": "e0f8c8" },
                { "tag": "9F34", "length": "3",  "value": "1f0302" },
                { "tag": "9F36", "length": "2",  "value": "00c7" },
                { "tag": "9F37", "length": "4",  "value": "8e2f1a44" }
            ]
        },
        "track2_data": {
            "data": "4761120000000148D30122011000000000000",
            "encrypted": false
        }
    }
}

El amount.value es 0: es una verificación de estatus de cuenta, no un cobro. No se envía capture (no hay fondos que capturar). Guardar el instrument_id de la respuesta — se usa en la Fase 2 para la autorización diferida.

---

Fase 2 — Finalizar período (cobro del monto acumulado)

Una vez que el back-office del operador calcula el monto total del período de viaje, hay dos opciones para cobrar el monto real: ajuste (adjust) o captura (capture). Cada una tiene ventajas y limitaciones distintas.

Opción A: Ajuste (/pos/payments/{id}/adjust)

El ajuste genera una nueva autorización por la diferencia entre el monto pre-autorizado y el monto real. Es la opción más flexible porque permite cobrar cualquier monto, sin importar cuánto exceda la pre-autorización original. Sin embargo, al ser una nueva autorización, puede ser denegada si el tarjetahabiente no tiene fondos suficientes.

Mastercard — Adjust

Se ajusta la pre-autorización original al monto real acumulado, referenciando el payment_id de la Fase 1. El cuerpo usa amount.value (string) y currency.

POST /pos/payments/{id}/adjust
Authorization: Bearer {access_token}
Content-Type: application/json
Idempotency-Key: {uuid-v4-único-por-request}

{
    "amount": {
        "value": "17700",
        "currency": "COP"
    }
}

Donde {id} es el payment_id obtenido en la Fase 1. El value es el monto total real del ciclo de viajes y va como string. Este valor puede ser mayor o menor que la pre-autorización original — en tránsito está permitido que el monto final supere la pre-autorización.

Visa — Autorización diferida (deferred)

Visa usa una nueva autorización completa con order_type: "deferred" e initiator: "merchant", ya que el cobro se hace sin presencia del pasajero. Por eso usa instrument.id (el instrumento almacenado en la Fase 1) y no lleva track2_data ni emv_data.

POST /pos/payments/authorizations
Authorization: Bearer {access_token}
Content-Type: application/json
Idempotency-Key: {uuid-v4-único-por-request}

{
    "id": "payg-visa-final-7f3a9c12",
    "intent": "authorization",
    "order_type": "deferred",
    "entry_mode": "contactless",
    "initiator": "merchant",
    "capture": {
        "mode": "AUTOMATIC"
    },
    "terminal_id": "trm-d49abonq5g3h7p5qnpbb",
    "amount": {
        "value": 17700,
        "currency": "COP"
    },
    "instrument": {
        "id": "ins-cuq7trf79diafopu1rog"
    }
}

Se usa instrument.id (el instrumento devuelto por el account-status) porque la tarjeta no está presente. El initiator: "merchant" indica que es una transacción MIT vinculada al account-status original.

---

Opción B: Captura (/pos/payments/{id}/captures)

La captura confirma el cobro directamente sobre la pre-autorización original, sin generar una nueva autorización. Esto significa que no puede ser denegada — el cobro se ejecuta siempre. La limitación es que el monto de la captura no puede exceder el 120% del monto pre-autorizado original (es decir, hasta un 20% por encima).

Mastercard y Visa — Capture

El request es el mismo para ambas redes. A diferencia del ajuste, la captura usa amount.value (número) y currency:

POST /pos/payments/{id}/captures
Authorization: Bearer {access_token}
Content-Type: application/json
Idempotency-Key: {uuid-v4-único-por-request}

{
    "amount": {
        "value": 10200,
        "currency": "COP"
    }
}

Donde {id} es el payment_id obtenido en la Fase 1. El amount.value es el monto total real del ciclo. Si el monto real es igual al pre-autorizado, se puede enviar la captura sin amount (captura por el monto completo pre-autorizado).

Regla del 20%: si la pre-autorización fue por $8,850 COP, la captura permite cobrar hasta $10,620 COP (8,850 × 1.20). Si el monto real del ciclo supera ese límite, se debe usar el ajuste en lugar de la captura.

---

¿Cuándo usar cada opción?

Recomendación: usar captura cuando el monto acumulado esté dentro del 120% de la pre-autorización original (caso más común en viajes diarios). Usar ajuste cuando el monto real exceda ese umbral (viajes atípicos, acumulaciones de varios días).

---

Resumen del flujo por red

---

Escenario completo: ejemplo de un día de viajes

Un pasajero toma el metro a las 7:00 AM (tarifa por zona, desconocida al tap), hace dos transbordos, y termina su último viaje a las 8:30 PM. El operador agrupa los viajes del día.

7:00 AM — Primer tap (Fase 1)

• Mastercard: pre-autorización por $8,850 COP (3 viajes nominales)
• Visa: account-status por $0

Durante el día

• El pasajero viaja normalmente. Los taps intermedios se registran localmente en el sistema del operador, no generan autorizaciones adicionales.

11:00 PM — Cierre del día (Fase 2)

• El back-office calcula: 5 viajes × $2,950 = $14,750 COP (con fare capping aplicado)

Opción A — Ajuste (monto real $14,750 excede el 120% de $8,850 = $10,620):

• Mastercard: adjust con value: "14750" sobre la pre-autorización original
• Visa: autorización diferida por $14,750

Opción B — Captura (solo si el monto real estuviera dentro del 120%):

• Si el monto acumulado fuera $10,200 (dentro de $10,620), se podría usar captura con value: 10200 sobre la pre-autorización original — sin riesgo de denegación

En este ejemplo, como $14,750 supera el 120% de la pre-autorización ($10,620), el operador debe usar el ajuste.