About Notifications

Notifications are sent to Merchant systems after Mazooma processes a payin request or receives a returned payin from a Consumer’s bank.

Notifications are sent to the transaction and event URLs provided to Mazooma by the Merchant prior to the system integration. For more information, see Prerequisites.

  1. Payin notifications
  2. Return notifications
  3. Verifying notifications

The key values included in notifications depend on your specific product and configuration and will be provided during your product integration.

Payin notifications

After Mazooma processes a payin transaction request, it sends a notification to the Merchant’s transaction notification URL.

The notification includes many of the same parameters included in the request, plus the transaction status, transaction fee payable by the Merchant, and any applicable transaction errors.

The payin notification in the Mazooma system has three possible states:

  1. Notification Initiated – The notification could not be sent. Mazooma attempts to make an HTTPS connection to the notification URL three times in succession. If after the third attempt, no connection is established, the notification status remains in Notification Initiated state. A payin notification with this status means the Merchant did not receive the transaction results.

  2. Notification Sent – An HTTPS connection with the Merchant system was established and data was sent. The verification process times out after four minutes.

    If, for any reason, the Merchant does not successfully echo back the payin notification (verification request), the notification status remains Notification Sent. This status means that it is unclear whether the Merchant received a notification and processed the results of the transaction.

  3. Notification Complete – Mazooma received the verification request where the Merchant echoed back the payin notification received from Mazooma.


This object contains the following key value pairs:
accountLabel - The account label that will be displayed to the Consumer to identify the bank account;
accountToken - The token that represents the Consumer’s bank account;
fiAccountType - The Consumer’s bank account type (PC is personal checking and PS is personal savings);
fiName - The name of the Consumer’s financial institution.

Return notifications

A return notification notifies the Merchant that a settled payment transaction has been returned by the Consumer’s bank.

When a Consumer’s bank returns a settled payment, Mazooma sends a notification to the Merchant’s event notification URL. After verifying the content of the return notification, the data can be processed by the Merchant’s back office and used for account reconciliation.

For more information, see ACH return codes.


This object contains the following key value pairs:
customerId - The Consumer user ID within the Mazooma system.
nextActionDate - The representment date is populated only if the nextAction is R. If the nextAction is D, this field is empty.
nextAction - The next action for the returned payment R: Represent or D: Dispose.

Verifying notifications

All notifications must be verified via a verification request sent to Mazooma.

Verification request

After processing the notification, the Merchant system must echo back an exact copy of the original notification message to the notify verification URL:

Notify verification URL

The verification request must be sent within 4 minutes (240 seconds) after receiving a payment notification or event notification. If the verification request is sent more than 4 minutes after receiving a payment or event notification, an error is returned.

Verification response

The response to a verification request is verification_code. verification_code 0 (zero) confirms that the verification request exactly matches the original notification request.


Verification code. 0 means Verified.

1 validation

If the Merchant system doesn’t send the verification request after it receives the notification, Mazooma sends the notification again, to a maximum of three times. If Mazooma still hasn’t received the verification request after the notification is sent the third time, the notification is marked as unsuccessful in the Mazooma system. The Mazooma support team monitors our systems for unsuccessful notifications and contacts Merchants when necessary.

Verification codes are described in the table below. Note that any verification code other than 0 indicates that the data contains errors.

Verification code Description
0 Verified
C001 Could not parse verification request - invalid HTTP request
C002 Could not parse verification request - invalid content
C003 Could not parse verification request - invalid transaction ID
C004 Verification details don’t match original payment - notification not found
C005 Verification details don’t match original payment - notification doesn’t match / exceeded 4 minute thread timeout
C006 Generic error