# Notification Notifications are sent using the following criteria: - a change of status of a Transaction, Subscription, or Authorization occurs - an error occurs when trying to confirm a Transaction, Subscription, or Authorization - a new payment is generated or not after a charge to an Authorization - a new payment is generated or not due to a Subscription - some actions are performed over a Sale A `POST` notification is sent to the URL defined in the field `notify_url` which was sent when the object was created. > Since the notification URL is defined when creating the object (Transaction, Subscription or Authorization), in the `notify_url` field, the URL can be dynamic, allowing it to be different for each created object. ## Notification contents The notification consists of a POST that sends a JSON with the following fields: - `signature`: Notification signature, to validate that the notification is sent by ZRU. More details on calculating the signature can be found later. - `fail`: If this field contains content, it refers to an error notification. The content would be an error code, which we can see [here](https://docs.zrupay.com/docs/api-en/d966c87425504-errors). - `id`: ID of the Transaction, Subscription, or Authorization related to the notification. - `type`: Type of object related to the notification (P - Transaction, S - Subscription, A - Authorization). - `order_id`: Includes the content sent in the `order_id` field when creating the object. - `status`: Status of the transaction (N - Pending, D - Completed, C - Canceled, E - Expired). > The statuses Completed, Canceled, and Expired are final statuses. - `subscription_status`: Status of the Subscription, only sent if the notification is related to a subscription (W - Waiting, A - Active, P - Paused, S - Stopped). > The Stopped status is a final status. - `authorization_status`: Status of the Authorization, only sent if the notification is related to an authorization (A - Active, R - Removed). > The Removed status is a final status. - `amount`: Amount charged to the client. - `sale_id`: If charged to the customer, includes the Sale ID related to the payment. - `action`: Last action of the object, more options will be provided later. - `sale_action`: Last action of the Sale, more options will be provided later. - `_extra`: Includes the content sent in the `extra` field when creating the object or when making a charge. It is not sent if not provided. - `_charge_id`: Includes the content sent in the `charge_id` field when making a charge. - `_method`: In the case of card payments, includes the card's information used; more details on the included fields will be provided later. > It is important to keep in mind during implementation that a new field can be added to the received JSON at any time. ### Possible values for `action` field - I: Error - D: Completed - E: Expired - C: Cancelled - A: Active Subscription (it's only available in the case of a subscription) - T: Initialized Subscription (it's only available in the case of a subscription) - P: Paused Subscription (it's only available in the case of a subscription) - S: Stopped Subscription (it's only available in the case of a subscription) - R: Deleted Authorization (it's only available in the case of a authorization) - Y: Payment received (it's only available in the case of a authorization or subscription) ### Possible values for `sale_action` field - I: Error - G: Amount charged - H: Amount on hold - V: Released amount - C: Captured amount - R: Refunded amount - S: Settled amount - E: Rejected escrow amount ### Values for `_method` field - `name`: Card name - `bin`: BIN of the masked card number - `bin8`: 8-digit BIN of the masked card number - `masked`: Masked card number - `masked8`: Masked card number with 8-digit BIN - `unique_hash`: Hash that uniquely represents the card. Whenever a customer uses the same card number and the same expiration date, they will receive the same hash. - `unique_hash_pan`: Hash that uniquely represents the card. Whenever a customer uses the same card number, they will receive the same hash. - `brand`: Card brand - `expiration_month`: Card expiration month - `expiration_year`: Card expiration year ### Calculating the signature The steps to calculate the signature and verify its correctness are as follows: 1. We start from the received JSON dictionary and ignore the keys: - `fail` - `signature` - any other key which starts with `_` 2. We sort the remaining JSON keys in alphabetical order, for example: - `['action', 'amount', 'authorization_status', 'id', 'order_id', 'sale_action', 'sale_id', 'status', 'subscription_status', 'type']` 3. In that order, we put the values one after the other in a variable, ignoring nulls, replacing symbols <, >, ", ', (, ), \ with spaces, and removing spaces from the beginning and end of each value, for example: - `D5.0d825c974-7288-4ddf-ae8b-21635c44eac3323232G545b8519-3e3c-4ee7-adef-9da7eefe5283DP` 4. To this, we add the Secret Key of your environment at the end, for example: - `D5.0d825c974-7288-4ddf-ae8b-21635c44eac3323232G545b8519-3e3c-4ee7-adef-9da7eefe5283DP18754581c5434008b9262dd5a6938ed3` 5. Finally, we sha256 this variable and obtain the signature to check it against the one received in the JSON, for example: - `783600a129c93cad54f561bca60e60c9b8dc328209841751a600a5e1c941ccee` ## Relevant notifications flow We will distinguish the most important notification flows depending on the object type, so we can use the following criteria: - Transaction - Error notification while the customer tries to confirm and fails, check the error code in the `fail` field. - Single cancellation notification (`status=C`). - Single expiration notification (`status=E`). - Single completed transaction notification (`status=D`) including the `sale_id` field of the Payment ID. - The rest of the possible notifications will always be related to the payment (Sale). - Subscription - Error notification while the customer tries to confirm and fails, or a charge attempt is made to an active subscription (in this latter case `status=D`), check the error code in the `fail` field. - Single cancellation notification (`status=C`). - Single expiration notification (`status=E`). - Single completed subscription notification (`status=D`), it does not include the `sale_id` field. - Payment received notification includes the `sale_id` field with the Payment ID. It is triggered the first time if it includes a charge when confirming the subscription and each time a correct charge is made to that subscription. - The rest of the possible notifications will always be related to the subscription payments. - Authorization - Error notification while the customer tries to confirm and fails, or a charge attempt is made to an active authorization (in this latter case `status=D`), check the error code in the `fail` field. - Single cancellation notification (`status=C`). - Single expiration notification (`status=E`). - Single completed authorization notification (`status=D`), it does not include the `sale_id` field. - Payment received notification includes the `sale_id` field with the Payment ID. It is triggered the first time if it includes a charge when confirming the authorization and each time a correct charge is made to that authorization using the `charge` endpoint. - The rest of the possible notifications will always be related to the authorization payments. - Sale - These notifications always include the `id` of the object related to the payment and the `status=D`. - Error notification for any action performed on the sale, such as refund, capture, etc., check the error code in the `fail` field. - Capture notification, can be partial, check the `amount` field (`sale_action=C`). - Void notification, can be partial, check the `amount` field (`sale_action=V`). - Refund notification, can be partial, check the `amount` field (`sale_action=R`). - Settlement notification (`sale_action=S`). ## Panel In the Panel, we can see the notifications sent by ZRU in real-time from the **Developers / Notifications** section, and we can also resend them by selecting the notification and clicking the **Resend** button.