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:

CampoDescripción
typestring
El tipo de evento que generó la notificación
event_date timestamp
Fecha de creación del evento en formato ISO 8601
transactionstring
El objeto de Transacción relacionado con el evento. No enviado en notificaciones de tipo verification.
verification_codestring
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

Nota: 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": "2019-09-20T17:46:52-05:00",
   "transaction": {
       "id": "trkwqxcnk9na5vawvf7z",
       "authorization": "23409378-f6w2-5201-9",
       "operation_type": "in",
       "method": "bank_account",
       "transaction_type": "charge",
       "status": "completed",
       "conciliated": false,
       "creation_date": "2019-09-20T17:43:08-05:00",
       "operation_date": "2019-09-20T17:46:49-05:00",
       "description": "Cargo en banco",
       "error_message": null,
       "order_id": "id2019092055321",
       "customer_id": "aqejwulgvpwj0wcjuw5e",
       "due_date": "2019-09-20T18:03:08-05:00",
       "amount": 100,
       "currency": "COP",
       "payment_method": {
           "type": "redirect",
           "url": "https://sandbox-api.openpay.co/v1/mlsfh8r28osykaj6e84p/charges/trkwqxcnk9na5vawvf7z/redirect/"
       }
   }
}                    
                

Tipos

TipoDescripción
verificationLa notificación contiene el código de verificación del Webhook
charge.createdSe creó un cargo para ser pagado por transferencia bancaria.
charge.succeededIndica que el cargo se ha completado (tarjeta, banco o tienda)
charge.refundedUn cargo a tarjeta fue reembolzado.
payout.createdSe ha programado un pago.
payout.succeededSe ha enviado el pago.
payout.failedEl pago fue rechazado.
transfer.succeededSe ha realizado una transferencia entre dos clientes.
fee.succeededSe ha cobrado una comisión a un cliente.
spei.receivedSe han agregado fondos a una cuenta mediante SPEI.
chargeback.createdSe ha recibido un contracargo de un cargo a tarjeta
chargeback.rejectedEl contrcargo se ha ganado a favor del comercio
chargeback.acceptedEl 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, configurala. 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" : "2019-09-20T11:02:49-05:00",
	"verification_code" : "UY1qorxn"
}                    
                

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.