Skip to content
Last updated

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

Previous page
Next page