Notificaciones de webhook
Un Webhook permite que una aplicación envíe notificaciones a otras aplicaciones. Cuando la pasarela de pago crea o actualiza una transacción para un pedido, envía una notificación a la URL que usted especificó. Al suscribirse a las notificaciones de Webhook, puede asegurarse de que el sistema de su tienda en línea se mantenga actualizado con la información más reciente de los pedidos.
La notificación de webhook:
- Utiliza el protocolo de API de servicios web (REST-JSON o NVP) configurado para el negocio.
- Incluye el secreto configurado por el negocio, que el sistema envía con cada notificación a una URL segura en el encabezado personalizado X-Notification-Secret.
Las notificaciones de Webhook no se recomiendan para el diseño de sistemas críticos y de alta capacidad de respuesta porque no garantizan la entrega oportuna. Como alternativa, puede utilizar la API Retrieve Transaction. Evite usar Webhook en sistemas importantes como liquidación y conciliación o en el flujo de transacciones en tiempo real, ya que es un servicio de notificación fuera de línea.
Notificaciones de webhook para las operaciones de la API de servicios web
Recibirá notificaciones de Webhook para las siguientes operaciones de API:
- Initiate Authentication: solicitud que devuelve qué mecanismo de autenticación del pagador (por ejemplo, autenticación 3-D Secure versión 2, autenticación 3-D Secure versión 1, RuPay PaySecure) recomienda la pasarela para este pedido.
- Authenticate Payer: el sistema envía esta notificación después de completar la operación de Authenticate Payer. Incluye solo los detalles de la operación de autenticación y no proporciona información sobre el resultado de la transacción financiera. Authentication Payer no admite order.notificationUrl en la carga útil JSON, pero el sistema envía un Webhook a la URL que configuró en la solicitud Initiate Authentication.
- Authorization o Pay: el sistema envía una notificación después de que se completa la operación de transacción de Authorization o Pay. Incluye el resultado del procesamiento de la transacción financiera.
- Capture: el sistema envía una notificación después de que se complete la operación de transacción Capture. Incluye el resultado del procesamiento de la transacción financiera. También se admite Standalone Capture.
- Refund: el sistema envía una notificación después de que se complete la operación de Refund transacción. Incluye el resultado del procesamiento de la transacción financiera. También se admite el Standalone Refund.
- Update Authorization: el sistema envía una notificación después de que se completa la operación de transacción Update Authorization. Incluye el resultado del procesamiento de la transacción financiera.
- Void: el sistema envía una notificación después de que se completa la transacción Void. Incluye el resultado del procesamiento de la transacción financiera.
- Verify: el sistema envía una notificación después de que se completa la operación de transacción Verify. Incluye el resultado del procesamiento de la transacción financiera.
- Referral: el sistema envía una notificación después de que se complete la operación de transacción Referral. Incluye el resultado del procesamiento de la transacción financiera.
- Disbursement: el sistema envía una notificación después de que se completa la operación de transacción Referral. Incluye el resultado del procesamiento de la transacción financiera.
- Initiate Browser Payment: el sistema envía una notificación después de que se complete la operación de transacción IBP. Incluye el resultado del procesamiento de la transacción financiera.
- Confirm Browser Payment: el sistema envía una notificación después de que la operación de transacción CBP se completa. Incluye el resultado del procesamiento de la transacción financiera.
Configure las notificaciones de Webhook en Merchant Administration
Para configurar las notificaciones de Webhook:
- Inicie sesión en el portal Merchant Administration y vaya a Admin>Notificaciones de webhook.
- Configure los siguientes parámetros para las notificaciones de Webhook:
- URL de notificación: configure una URL de notificación global para recibir actualizaciones para todas las transacciones. La URL que usted proporcione debe cumplir con el estándar IETF para URL. De lo contrario, el sistema rechaza la solicitud.
Para sobrescribir esta URL global en una transacción específica, incluya la URL en el campo order.notificationUrl en su solicitud de transacción. Para transacciones posteriores, las notificaciones se envían a la URL especificada en la transacción (si se proporciona) o a la última URL utilizada para el pedido.
De acuerdo con el nuevo estándar de la IETF, el formato username:password@host.com ya no está permitido. Si usted utiliza este formato, se envían webhooks, pero el nombre de usuario y la contraseña se ignoran. Utilice un secreto de notificación para fines de autenticación.
- Formato de API: Mastercard Gateway envía notificaciones de Webhook en el formato (REST-JSON o NVP) que usted configura en Merchant Administration. La notificación se envía en la versión que se usó para enviar la solicitud de transacción.
- Verifique el secreto de notificación: el secreto de notificación es una cadena aleatoria de 32 caracteres generada por la pasarela de pagos. Puede ver este secreto en el portal Merchant Administration al configurar las notificaciones de Webhook. Para las URLs seguras (https://), el gateway incluye el secreto en el encabezado
X-Notification-Secretcon el mensaje.
- URL de notificación: configure una URL de notificación global para recibir actualizaciones para todas las transacciones. La URL que usted proporcione debe cumplir con el estándar IETF para URL. De lo contrario, el sistema rechaza la solicitud.
Entrega exitosa de notificaciones de Webhook
La pasarela considera correcta la entrega de la notificación Webhook si su sistema responde con un mensaje de acuse de recibo correcto, que contenga el código de estado HTTP 200, dentro de 2 segundos.
La pasarela no espera encabezados específicos de los clientes, pero en caso de que la respuesta de la URL de destino envíe algún encabezado, estos deben tener un tamaño máximo de 32 KB. El sistema intenta volver a entregar la notificación Webhook hasta que recibe una respuesta.
Mastercard Gateway exige que los negocios reciban notificaciones de Webhook exclusivamente a través de un punto final seguro (HTTPS://), lo que garantiza tanto la seguridad como el cumplimiento.
Secuencia de notificación de Webhook y reintentos de entrega
- Intentos de entrega: el gateway realiza hasta 20 intentos de entrega de notificaciones de Webhook del negocio dentro de un período de 3 días después de que ocurra el evento.
- Intervalos de reintento: el gateway vuelve a intentar la entrega en los siguientes intervalos: 10 segundos, 30 segundos, 2 minutos, 5 minutos, 30 minutos, 4 horas (repetido cuatro veces), 8 horas, 12 horas (repetido cuatro veces).
- Manejo del tiempo de espera: el gateway espera 30 segundos antes de registrar una excepción por tiempo de espera en la notificación de Webhook.
- Entrega exitosa: el gateway considera la entrega de la notificación de Webhook como exitosa si su sistema responde con un código de estado HTTP 200 dentro del período de 3 días.
- Finalización de intentos: todos los intentos de entrega de una notificación de Webhook finalizan tras 20 intentos dentro del período de 3 días.
Gestión de notificaciones reenviadas
Puede usar los siguientes campos en la notificación de Webhook para manejar las notificaciones reenviadas:
- X-Notification-ID: este encabezado identifica de manera única la notificación y es idéntico para transacciones duplicadas.
- X-Notification-Attempt: este encabezado indica el número de intentos realizados para enviar la notificación.