Notificaciones

Las notificaciones son enviadas cada vez que:

• se realiza un cambio de estado de una Transacción, Suscripción o Autorización
• se produce un error al intentar confirmar una Transacción, Suscripción o Autorización
• se genera o no un nuevo pago después de un charge a una Autorización
• se genera o no un nuevo pago debido a una Suscripción
• se realizan acciones sobre un Pago

Se envía una notificación POST a la url definida en el campo notify_url que se envió en el momento de la creación del objeto.

Gracias a que la url de notificación se define al crear el objeto, en el campo notify_url, la url puede ser dinámica pudiendo ser diferente para cada objeto creado.

La forma más sencilla de implementar la lógica de notificaciones es:

1. Usar el campo notification_type para identificar qué evento ha ocurrido.
2. Revisar el campo fail: si contiene un código de error, la notificación corresponde a un evento fallido; si es null, el evento fue exitoso.

El campo notification_type está siempre presente en todas las notificaciones.

La notificación consiste en un POST que envía un JSON con los siguientes campos:

• notification_type: Tipo de notificación. Ver tabla de valores más arriba.
• fail: En el caso de que este campo incluya contenido nos referimos a una notificación de error. El contenido sería un código de error, los cuales podemos ver aquí.
• signature: Firma de la notificación, para validar que la notificación es enviada por Zru. Ver más adelante como calcular la firma.
• id: ID de la Transacción, Suscripción o Autorización relacionada con la notificación.
• type: Tipo de objeto relacionado con la notificación (P - Transacción, S - Suscripción, A - Autorización).
• order_id: Incluye el contenido enviado en el campo order_id al crear el objeto.
• status: Estado de la transacción (N - Pendiente, D - Completado, C - Cancelado, E - Expirado).

Los estados Completado, Cancelado y Expirado son estados finales.

• subscription_status: Estado de la Suscripción, solo se envía si la notificación es relacionada con una suscripción (W - En Espera, A - Activa, P - Pausada, S - Parada).

El estado Parada es un estado final.

• authorization_status: Estado de la Autorización, solo se envía si la notificación es relacionada con una autorización (A - Activa, R - Eliminada).

El estado Eliminada es un estado final.

• amount: Cantidad cobrada al cliente.
• sale_id: En el caso de que se haya cobrado al cliente incluirá el ID del Sale relacionado con el pago.
• action: Última acción del objeto.
• sale_action: Última acción del Sale.
• _extra: Incluye el contenido enviado en el campo extra al crear el objeto o al realizar un charge. No se envía en el caso de que no se haya enviado.
• _charge_id: Incluye el contenido enviado en el campo charge_id al realizar un charge.
• _method: En el caso de pagos con tarjeta incluye la información de la tarjeta utilizada.

Es importante tener en cuenta al realizar la implementación que en cualquier momento puede añadirse un nuevo campo al JSON recibido.

• I: Error
• D: Completado
• E: Expirado
• C: Cancelado
• A: Suscripción Activa (solo en el caso de suscripción)
• T: Suscripción Iniciada (solo en el caso de suscripción)
• P: Suscripción Pausada (solo en el caso de suscripción)
• S: Suscripción Parada (solo en el caso de suscripción)
• R: Autorización Eliminada (solo en el caso de autorización)
• Y: Pago recibido (solo en el caso de suscripción o autorización)

• I: Error
• G: Cantidad cobrada
• H: Cantidad en hold
• V: Cantidad liberada
• C: Cantidad capturada
• R: Cantidad devuelta
• S: Cantidad liquidada
• E: Cantidad en escrow rechazada

• name: Nombre de la tarjeta
• masked: Número de tarjeta enmascarada
• unique_hash: Hash que representa a la tarjeta de manera única. Siempre que un cliente utilice el mismo número de tarjeta y la misma fecha de expiración recibirán el mismo hash.
• brand: Marca de la tarjeta
• expiration_month: Mes de expiración de la tarjeta
• expiration_year: Año de expiración de la tarjeta

{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "fail": null,
  "type": "P",
  "notification_type": "sale_created",
  "status": "D",
  "action": "D",
  "amount": 157.5,
  "sale_id": "b2c3d4e5-0000-0000-0000-000000000001",
  "sale_action": "G",
  "order_id": "order_example_001",
  "signature": "c1eed82e684cccf2507535f137085d9aafa818114009d9c7f6b2a9edad013014"
}

{
  "id": "a1b2c3d4-0000-0000-0000-000000000002",
  "fail": "MC2P-07001",
  "type": "P",
  "notification_type": "transaction_confirmation_error",
  "status": "N",
  "action": "I",
  "amount": 13.2,
  "sale_id": "",
  "sale_action": "",
  "order_id": "order_example_002",
  "signature": "859e878993ccd736aec1c089f7dd5b73469d47b9213e88659e0ef22cc36f91d4"
}

Los pasos para calcular la firma y verificar que es correcta son los siguientes:

1. Partimos del diccionario JSON recibido e ignoramos los keys:

   • fail
   • signature
   • cualquier otro que empiece por _

2. El resto de keys del JSON los ordenamos por orden alfabético, por ejemplo:

   • ['action', 'amount', 'authorization_status', 'id', 'order_id', 'sale_action', 'sale_id', 'status', 'subscription_status', 'type']

3. Por ese orden ponemos los valores uno detrás de otro en una variable ignorando los que sean null, reemplazando en los valores los símbolos <, >, ", ', (, ), \ por espacio y quitando los espacios del inicio y del final de cada valor, por ejemplo:

   • D5.0d825c974-7288-4ddf-ae8b-21635c44eac3323232G545b8519-3e3c-4ee7-adef-9da7eefe5283DP

4. A eso le agregamos al final la Clave Secreta de vuestro entorno, por ejemplo:

   • D5.0d825c974-7288-4ddf-ae8b-21635c44eac3323232G545b8519-3e3c-4ee7-adef-9da7eefe5283DP18754581c5434008b9262dd5a6938ed3

5. Finalmente le hacemos sha256 a esa variable y obtendríamos el signature para comprobarlo con el recibido en el JSON, por ejemplo:

   • 783600a129c93cad54f561bca60e60c9b8dc328209841751a600a5e1c941ccee

El resto de notificaciones posibles siempre serán relacionadas con el pago.

El resto de notificaciones posibles siempre serán relacionadas con los pagos de la suscripción.

El resto de notificaciones posibles siempre serán relacionadas con los pagos de la autorización.

Estas notificaciones siempre incluyen en el campo id el objeto relacionado con el pago y el status=D.

Desde la sección Desarrolladores del panel tienes acceso a herramientas pensadas para facilitar las tareas de integración. Ve al menú lateral y selecciona Desarrolladores para acceder a las pestañas Notificaciones y Webhooks.

Muestra todas las notificaciones enviadas a tu servidor, la respuesta que devolvió y permite reenviarlas si es necesario.

Al desplegar una notificación verás:

• Información: ID de notificación, URL de notificación, fecha y hora.
• Solicitud: JSON completo enviado por Zru a tu servidor.
• Respuesta: respuesta devuelta por tu servidor.

Puedes filtrar por ID, ID externo, URL de notificación, fecha y código de respuesta. También puedes exportar el listado en CSV.

Para reenviar una notificación: despliega el detalle y haz clic en Volver a enviar.

Los Webhooks permiten configurar los endpoints a los que Zru enviará notificaciones de forma global para todo el entorno, como alternativa a definir la notify_url en cada objeto.

La diferencia entre Webhooks y Notificaciones: los Webhooks son la configuración del endpoint (a qué URL enviar). Las Notificaciones son los eventos concretos enviados a esos endpoints, con su solicitud y respuesta.