Transaction Validation

Transaction validation provides an additional layer of authorization for Monnify disbursements. When enabled, Monnify sends a validation request to your registered HTTPS callback endpoint before processing a disbursement. Your system must explicitly approve the request by returning APPROVE. A REJECT, timeout, or error prevents the disbursement from being processed.

Optional Feature

Transaction validation is optional. If it is not enabled for your account, your existing disbursement flow remains unchanged. You can enable it yourself from your Monnify dashboard — see How to Enable Transaction validation below.

How Transaction validation Works

For a single disbursement, Transaction validation runs before the transaction is processed.

For a batch disbursement, Transaction validation runs once for the entire batch. The response applies to the whole batch and not to individual transactions.

The flow is:

Disbursement request → Transaction Validation → Processing

If your callback returns REJECT, or the callback fails after all retries, the disbursement is not processed.

How to Enable Transaction validation

Transaction validation is configured under Developer > Transaction Validation in the Monnify dashboard.

1. Submit your HTTPS callback URL. You will receive a submission email confirming your request has been received.
2. Monnify runs the endpoint verification check on the URL (see Register Your Callback Endpoint below).
3. Your submission then goes through an approval process before it takes effect.
4. If approved, you receive an approval email and Transaction Validation is enabled for your account.
5. If not approved, you receive a rejection email and Transaction Validation remains disabled.

Once enabled, Transaction Validation applies to all subsequent disbursements until you disable it.

Register Your Callback Endpoint

Your callback endpoint must:

• Use HTTPS.
• Be publicly reachable by Monnify.
• Return an HTTP 200 response to a valid callback request.
• Return an explicit REJECT when Monnify performs the initial endpoint verification.

Endpoint Verification

When Transaction Validation is enabled for the first time, or when you update your callback URL, Monnify sends a test POST request to the endpoint. The endpoint must respond within 5 seconds.

The test request uses a mock payload and must return:

The mock request is expected to be rejected because it does not represent a real disbursement. If the endpoint does not respond within 5 seconds, or does not return the expected rejection response, the callback URL cannot be registered.

Callback Request

Monnify sends a POST request to your registered callback endpoint. The request uses the same envelope structure for both single and batch disbursements.

Request Headers

Request Structure

Single Disbursement

For a single disbursement, the callback contains the transaction reference, amount, destination account and bank details, narration, and source account information.

Batch Disbursement

For a batch disbursement, the callback represents the entire batch.

Note

The batch callback represents the entire batch. Your response determines whether the batch can proceed. A rejection prevents all entries in the batch from being processed.

Verify the Callback Signature

Monnify signs every callback request using HMAC-SHA256. You should verify the signature before making an authorization decision. Your existing client secret is used to verify the signature — no separate callback-specific secret is issued.

The signature is generated using:

Where:

• merchantCode is your Monnify merchant code.
• type is SINGLE or BATCH.
• reference is the transaction reference for a single disbursement.
• reference is the batch reference for a batch disbursement.

The resulting hash is provided in the X-Monnify-Signature header.

Example

Replay Protection

Monnify includes X-Monnify-Timestamp with every callback request. The signature is generated from the merchant code, type, and reference — it does not include the timestamp. This means a valid callback request and signature can be captured and replayed indefinitely. Validate that the timestamp is within an acceptable window and reject requests that are too old. You should also consider tracking previously processed references to prevent duplicate processing.

Callback Response

Your endpoint must return HTTP 200 with a decision.

Approve

Return APPROVE when you have validated the disbursement and want it to proceed.

An approved disbursement proceeds to the next stage of the disbursement flow.

Reject

Return REJECT when you do not want the disbursement to proceed.

Your original disbursement request is always accepted and returns a pending status. If your callback returns REJECT, the disbursement is not processed further.

Response Outcomes

Only an explicit REJECT response is treated as a merchant rejection.

Timeouts and Retries

If Monnify encounters a network error or timeout while calling your callback endpoint, it retries the request up to 2 times. A fixed 2-second delay is applied between retry attempts. If all attempts fail, the disbursement is rejected.

There is no merchant-configurable fallback that allows a disbursement to proceed when Transaction Validation cannot obtain a valid response.

Post-No-Debit (PND)

Only an explicit REJECT response is counted toward PND. Timeouts, network errors, and non-200 responses do not count, no matter how many occur.

PND is applied based on a policy that Monnify sets and may update; it is not something merchants can configure. Currently, a single explicit REJECT response is enough to place an account on PND.

Coming Off PND

Coming off PND requires manual support intervention as there is no automatic expiration.

Batch Disbursement Behavior

Transaction validation is performed once per batch request. The callback decision applies to the entire batch:

• APPROVE: the batch proceeds and individual entries continue through the normal processing flow.
• REJECT: the entire batch is rejected before any entry is processed.
• Timeout or callback failure after retries: the entire batch is rejected.

After a batch is approved, individual transactions continue through the existing processing flow.

Important Considerations

Callback Availability

Your callback endpoint is part of the disbursement authorization flow. If your endpoint is unavailable, slow, or returns an error, the disbursement may fail.

Additional Latency

Enabling Transaction Validation adds latency to disbursements because Monnify must wait for your endpoint to respond before continuing.

Explicit Authorization

Only an explicit APPROVE response allows a disbursement to proceed. A timeout, error, non-200 response, or REJECT does not authorize the transaction.

Batch Authorization

For batch disbursements, a single callback decision applies to the entire batch. Individual entries cannot be independently approved or rejected at the transaction-validation stage.