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 aquí
Objeto Webhook
Cada vez que se realice una transacción, Openpay enviará una objecto JSON a las URL’s registradas para recibir webhooks. Openpay puede agregar mas 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ámetros
El objeto webhook contiene los siguientes datos:
| Campo | Descripción |
|---|---|
| type | string El tipo de evento que generó la notificación |
| event_date | timestamp Fecha de creación del evento en formato ISO 8601 |
| transaction | string El objeto de Transacción relacionado con el evento. No enviado en notificaciones de tipo verification. |
| verification_code | string El 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 type
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 reembolzado. |
| 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 contrcargo 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:
Entra al Dashboard de Openpay utilizando tu correo y tu contraseña
Da click en tu nombre para accesar a tu perfil de comercio.
En la sección de Webhooks, selecciona la opción +Agregar Webhook.
En el formulario que aparece, indica la URL completa de tu webhook, incluyendo el protocolo a usar. Es recomendado utilizar https.
Si tu Webhook requiere autenticación HTTP, configurala. Actualmente solo se soporta autenticación HTTP Basic.
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.
