Descripción
Use este webhook para aprobar o rechazar pagos entrantes en tiempo real.
Cuando la plataforma PaaS notifique a su sistema sobre un pago entrante, su endpoint debe responder con un cuerpo JSON que indique si el pago debe aceptarse o rechazarse. La plataforma utilizará su respuesta para determinar si el pago queda aprobado.
El banco también puede rechazar transacciones. Si la fintech acepta el pago, pero el banco lo rechaza, la transacción será rechazada.
Requisitos
Passport debe habilitar esta funcionalidad para su uso. Una vez completado este paso, el administrador de la fintech podrá configurarla como se describe a continuación.
Flujo de Aprobación de Pagos Entrantes
Este flujo describe cómo se procesa un pago entrante cuando la plataforma PaaS envía una notificación a la entidad y, dependiendo de la configuración, la entidad puede participar o no en la decisión de aprobación.
Flujo de Aprobación
Cuando Passport envía una Inbound Payment Notification, el pago se crea con estado PROCESSING (En procesamiento)
A partir de ese momento, la plataforma valida si la entidad tiene habilitado el flujo de aprobación:
- Si no está habilitado, el pago continúa directamente a la validación del banco.
- Si está habilitado, Passport envía la notificación al URL de Callback configurado por la fintech para que su sistema decida si acepta o rechaza la transacción.
Después de ser aceptado por el banco, el Mecanismo de Operación y Liquidación (MOL) actualiza y hace el movimiento de los fondos, y el pago cambia finalmente a SETTLED (Liquidado).
Habilitación de la Funcionalidad
Un administrador de la fintech debe:
- Iniciar sesión en el Dashboard de Passport.
- Ir a Plataforma > Configuración.
- En URL de Callback, ingresar el endpoint donde la plataforma PaaS debe enviar las notificaciones de pagos entrantes.
- Ingresar el Token de Secreto que la plataforma PaaS utilizará al llamar su endpoint.
- (Opcional) Seleccionar Tiempo de Aprobación Automática si así lo requiere su caso de uso.
- Hacer clic en Guardar.
Authorization Feature Configuration
La funcionalidad de Tiempo de Aprobación Automática está diseñada para aceptar automáticamente cualquier pago cuando se recibe un error desde su URL de Callback. En este escenario, si la plataforma intenta enviar un mensaje POST a su sistema y recibe cualquier respuesta de error, aprobará automáticamente el pago entrante. Esta funcionalidad permite que el procesamiento de pagos continúe sin interrupciones, incluso si ocurre un problema técnico en su sistema.
Debe devolver la respuesta de aceptación o rechazo en un plazo máximo de 3 segundos. Si su endpoint no responde dentro de este tiempo, la plataforma podría considerar el intento como fallido.
Si Auto Approve Error está habilitado y no responde, la plataforma aceptará automáticamente el pago entrante.
Solicitud de Passport a la URL de Callback de la Fintech
Puede consultar los detalles del pago en el mensaje enviado por la plataforma PaaS con la siguiente información:
"payment_id": "932833da-1c97-46c5-92be-6e45d3347622", "type": "BREB", "status": "PROCESSING", "account_id": "99258bd0-4876-425a-8894-312feaa14573", "amount": { "value": "1.00", "currency": "COP" }, "qr_code_reference": "LLAVE", "sender": { "owner": { "name": "Gustavo Munoz (Merchant 7OREJ)", "identification_type": "NIT", "identification_number": "288624272" }, "account": { "account_type": "ORDINARY", "account_number": "88166916083" }, "participant": { "name": "Banco Coopcentral", "identification_number": "890505363" } }, "end_to_end_identification": "20260310890505363VIS228589754906085", "created_at": "2026-03-10T11:00:40.465447Z", "updated_at": "2026-03-10T11:00:40.465447Z"}Respuesta a Passport para Autorizar o Rechazar Transacciones
Devuelva un cuerpo de respuesta JSON con un único campo booleano llamado accept.
- Aceptar el pago entrante:
{"accept": true}
- Rechazar el pago entrante:
{"accept": false}
Devuelva un HTTP 200 con Content-Type: application/json junto con el cuerpo JSON mostrado arriba.
Lógica de decisión
- Si la fintech responde con
"accept": false, el pago termina en REJECTED. - Si la fintech responde con
"accept": true, el pago continúa a la validación del banco. - Si el banco rechaza la transacción, el estado final será REJECTED.
- Si el banco acepta la transacción, el pago pasa a ACCEPTED.