# 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í](https://docs.zrupay.com/docs/api/ZG9jOjM4MzYzMTQ-errores). - `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, 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**.