Notificaciones

¿Qué es un Webhook?Los Webhooks te permiten recibir notificaciones de las transacciones realizadas a algún servicio web que tu configures en tu cuenta. Esto te permite saber, por ejemplo, cuando se ha realizado un cargo a una tarjeta o cuando un depósito se ha realizado con éxito.Nota: Si deseas manejar los webhooks vía API, consulta la referencia aqui

Objeto Webhook

Cada vez que se realice una transacción, Openpay enviará un objecto JSON a las URL’s registradas para recibir webhooks. Openpay puede agregar más campos en un futuro, o agregar nuevos valores a campos existentes, por lo que es recomendado que tu Webhook pueda manejar datos adicionales desconocidos.ParámetrosEl objeto webhook contiene los siguientes datos:

Campo Descripción
type stringEl tipo de evento que generó la notificación
event_date timestampFecha de creación del evento en formato ISO 8601
transaction stringEl objeto de Transacción relacionado con el evento. No enviado en notificaciones de tipo verification.
verification_code stringEl código de verificación del Webhook. Enviado solamente en notificaciones de tipo verification.
Todas las notificaciones de las transacciones se enviarán a las URL’s que tengas registradas. Para distinguir una transacción, utiliza la propiedad typeNota: Openpay intentará entregar la notificación hasta recibir una respuesta de éxito. Esto puede causar que algunas notificaciones se envíen dos veces, por lo que debes estar preparado para poder recibir la misma notificación mas de una vez.Ejemplo:

{"type" : "charge.succeeded","event_date" : "2013-11-22T15:09:38-06:00","transaction" : {"amount" : 2000.0, "authorization" : "801585","method" : "card","operation_type" : "in","transaction_type" : "charge","card" : {"type" : "debit","brand" : "mastercard","address" : {"line1" : "Calle #1 Interior #2","line2" : null,"line3" : null, "state" : "Queretaro","city" : "Queretaro","postal_code" : "76040","country_code" : "MX"},"card_number" : "1881","holder_name" : "Card Holder","expiration_month" : "10","expiration_year" : "14","allows_charges" : true,"allows_payouts" : true,"creation_date" : "2013-11-22T15:09:32-06:00","bank_name" : "BBVA BANCOMER","bank_code" : "012"},"status" : "completed", "id" : "tlxcm4vprtz74qoenuay","creation_date" : "2013-11-22T15:09:33-06:00","description" : "Description","error_message" : null,"order_id" : "oid_14235"}}

Características de un servicio Webhook válido

  • Endpoint: Solo dominios (No IPs). ejemplo: https://notifications.merchant.com
  • Puerto: 443/TCP, 1518/TCP, 1519/TCP, 8443/TCP y 10443/TCP
  • Protocolo: HTTPS/TLS_1.2
  • Certificado: Válido (firmado por CA pública y match con dominio).

Tipos

Tipo Descripción
verification La notificación contiene el código de verificación del Webhook
charge.created Se creó un cargo para ser pagado por transferencia bancaria.
charge.succeeded Indica que el cargo se ha completado (tarjeta, banco o tienda)
charge.refunded Un cargo a tarjeta fue reembolsado.
payout.created Se ha programado un pago.
payout.succeeded Se ha enviado el pago.
payout.failed El pago fue rechazado.
transfer.succeeded Se ha realizado una transferencia entre dos clientes.
fee.succeeded Se ha cobrado una comisión a un cliente.
spei.received Se han agregado fondos a una cuenta mediante SPEI.
chargeback.created Se ha recibido un contracargo de un cargo a tarjeta
chargeback.rejected El contracargo se ha ganado a favor del comercio
chargeback.accepted El contracargo se ha perdido. Se ha creado una transacción tipo contracargo que descontará los fondos de tu cuenta.
Tu servidor debe estar preparado para aceptar notificaciones de tipos no conocidos, para asegurar una compatibilidad con futuras versiones.

Registro

Para configurar un Webhook sigue los siguientes pasos:

  1. Entra al Dashboard de Openpay utilizando tu correo y tu contraseña
  2. Da click en tu nombre para accesar a tu perfil de comercio.
  3. En la sección de Webhooks, selecciona la opción +Agregar Webhook.
  4. En el formulario que aparece, indica la URL completa de tu webhook, incluyendo el protocolo a usar. Es recomendado utilizar https.
  5. Si tu Webhook requiere autenticación HTTP, configúrala. Actualmente solo se soporta autenticación HTTP Basic.
  6. Da click en el botón Guardar.

Verificación

Al terminar la configuración de registro, Openpay enviará mediante POST un mensaje JSON a la URL indicada, conteniendo un objeto de notificación Webhook. Tu servicio deberá guardar el código de verificación de alguna manera, y regresar el estado 200 OK.Si por alguna razón requieres que se te envíe de nuevo el código de verificación, selecciona la opción Reenviar Código. Un nuevo código de verificación será generado y enviado a la URL proporcionada.Una vez que ya tengas el código de verificación del Webhook, selecciona la opción de Verificar e introduce el código proporcionado en el objeto de la notificación. Esto activará el Webhook en Openpay, y empezarás a recibir notificaciones de las transacciones realizadas a partir de ese momento.Ejemplo:

{"type" : "verification","event_date" : "2013-11-22T11:04:49-06:00","verification_code" : "UY1qqrxw"}

Implementación

Para implementar tu Webhook, solo tienes que crear un servicio Web con una URL a la que Openpay pueda enviar peticiones POST.Tu Webhook debe manejar los diferentes tipos de notificaciones, incluyendo recibir el código de verificación, para que puedas darlo de alta en Openpay.Tu Webhook también deberá poder recibir tipos de notificaciones inesperados, para asegurar compatibilidad con futuras versiones.Los Webhook deberán regresar un estado HTTP 200 OK siempre que reciban una notificación, de otra manera Openpay reintentará el envío continuamente.

Eliminación

En cualquier momento puedes seleccionar la opción -Eliminar desde el dashboard para eliminar un Webhook y dejar de recibir notificaciones a esa URL.