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 de dicho objeto.

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

Contenido de la notificación

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

• signature: Firma de la notificación, para validar que la notificación es enviada por ZRU. Ver más adelante como calcular la firma.
• 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í.
• 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 (P - 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, ver más adelante posibles opciones.

• sale_action: Última acción del Sale, ver más adelante posibles opciones.

• _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, ver más adelante campos que incluye.

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

Posibles valores del campo action

• 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)

Posibles valores del campo sale_action

• 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

Valores del campo _method

• 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

Calcular la firma

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

Flujo de notificaciones más importantes

Aquí vamos a distinguir los flujos de notificación más importantes en dependencia del tipo de objeto:

• Transacción (Transaction)

  • Notificación de error mientras el cliente intenta confirmar y le falla, verificar código de error en el campo fail.
  • Notificación única de cancelación (status=C).
  • Notificación única de expiración (status=E).
  • Notificación única de transacción completada (status=D) que incluye en el campo sale_id el id del Pago.
  • Resto de notificaciones posibles siempre serán relacionadas con el pago.

• Suscripción (Subscription)

  • Notificación de error mientras el cliente intenta confirmar y le falla o se intenta realizar un cobro a una suscripción activa (en este último caso el status=D), verificar código de error en el campo fail.
  • Notificación única de cancelación (status=C).
  • Notificación única de expiración (status=E).
  • Notificación única de suscripción completada (status=D), no incluye sale_id.
  • Notificación de pago recibido, incluye en el campo sale_id el id del Pago. Se lanza la primera vez si incluye un cobro el confirmar la suscripción y cada vez que se realice un cobro correcto a dicha suscripción.
  • Resto de notificaciones posibles siempre serán relacionadas con los pagos de la suscripción.

• Autorización (Authorization)

  • Notificación de error mientras el cliente intenta confirmar y le falla o se intenta realizar un cobro a una autorización activa (en este último caso el status=D), verificar código de error en el campo fail.
  • Notificación única de cancelación (status=C).
  • Notificación única de expiración (status=E).
  • Notificación única de autorización completada (status=D), no incluye sale_id.
  • Notificación de pago recibido, incluye en el campo sale_id el id del Pago. Se lanza la primera vez si incluye un cobro el confirmar la autorización y cada vez que se realice un cobro correcto a dicha autorización utilizando el endpoint de charge.
  • Resto de notificaciones posibles siempre serán relacionadas con los pagos de la autorización.

• Pago (Sale)

  • Estas notificaciones siempre incluyen en el campo id el objeto relacionado con el pago y el status=D.
  • Notificación de error de cualquier acción realizada al sale, como devolución, liberación, etc, verificar código de error en el campo fail.
  • Notificación de captura, puede ser parcial, verificar campo amount (sale_action=C).
  • Notificación de liberación, puede ser parcial, verificar campo amount (sale_action=V).
  • Notificación de devolución, puede ser parcial, verificar campo amount (sale_action=R).
  • Notificación de liquidación (sale_action=S).

Panel

En el Panel podemos ver las notificaciones enviadas por ZRU en tiempo real desde la sección Desarrolladores / Notificaciones y también podemos reenviarlas seleccionando la notificación y dando click en el botón Volver a enviar.