Webhooks

Get notified in real time, with signature verification and replay protection

When a payment lands in a virtual account (or a Collect Payments link is paid), we send a POST request to your configured webhook URL instead of making you poll for it.

Set your webhook URL and grab your webhook secret from Webhook Settings in the merchant dashboard.

Payload

{
    "event": "payment.received",
    "nonce": "9f2a7c1e4b0d8a3f6c5e9b1d2a4f7c0e",
    "sent_at": "2026-05-10T15:25:13Z",
    "data": {
        "reference": "Transfer from JOHN DOE",
        "amount": 100,
        "currency": "NGN",
        "virtual_account": "6678550369",
        "payer_name": "John Doe",
        "payer_bank": "ACCESS BANK",
        "payer_account": "1234567890",
        "transaction_id": "MI2053495351264129024",
        "status": "successful",
        "timestamp": "2026-05-10T15:25:13Z"
    }
}

For this event, data.reference is the bank transfer narration the payer’s own bank attached to the transfer — it is not something you sent, and it is not unique. Two completely different payments can carry identical narration text (a generic “Personal Transfer”, or the same payer transferring twice). Never use it as a lookup key or a duplicate-detection key — use transaction_id instead, below.

data.reference · string

The payer’s bank transfer narration/description, exactly as their bank sent it to us. Free text, not guaranteed unique, and not something you provided. Useful only as a human-readable label to show alongside a transaction — never for matching or deduplication.

data.transaction_id · string

Ours, and unique. ABCMPay’s own internal ID for the transaction (shown as “Order Number” in the dashboard). This is the value to store and to key your duplicate-detection off.

nonce · string

Unique per delivery attempt — even a retry of the same transaction gets a new one. Covered by the signature. See Replay protection.

sent_at · string

ISO 8601 timestamp of this specific delivery attempt. Also covered by the signature.

Request headers

Content-Type: application/json
X-Webhook-Signature: a1f7307efafe5b292fab7989d9fc5970191994194b9763010e62e256d7c67281
X-Webhook-Event: payment.received

Verifying the signature

Every payload is signed with HMAC-SHA256 using your webhook secret, over the entire raw request body (not a re-serialized version of it — hash the bytes exactly as received).

Always verify the signature before trusting a webhook. Anyone who finds your webhook URL can otherwise send you a fake payment.received event.

PHP

<?php
// Get the raw POST body
$payload = file_get_contents('php://input');

// Get the signature from the X-Webhook-Signature header
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$secret = 'your-webhook-secret';

// Verify the signature using HMAC-SHA256
$expected = hash_hmac('sha256', $payload, $secret);

if (hash_equals($expected, $signature)) {
    // Signature is valid - process webhook
    $data = json_decode($payload, true);

    $event = $data['event']; // 'payment.received'
    $txnData = $data['data'];

    // transaction_id is the unique ID - use it (not reference) as your
    // duplicate-detection key before crediting anything.
    $transactionId = $txnData['transaction_id'];
    $reference = $txnData['reference']; // display-only narration, not unique
    $amount = $txnData['amount'];
    $virtualAccount = $txnData['virtual_account'];
    $payerName = $txnData['payer_name'];
    $payerBank = $txnData['payer_bank'];

    if (already_processed($transactionId)) {
        // Seen this transaction_id before (first delivery, or a retry) -
        // acknowledge and stop, don't credit twice.
        http_response_code(200);
        echo 'success';
        exit;
    }

    // Credit user wallet, update order status, etc.
    // Record $transactionId as processed before returning.

    http_response_code(200);
    echo 'success';
} else {
    // Invalid signature - reject request
    http_response_code(401);
    echo 'Invalid signature';
}

Use hash_equals() (or your language’s constant-time comparison) rather than == or === — a plain string comparison leaks timing information an attacker can use to guess a valid signature byte by byte.

Replay protection

A valid signature only proves the request came from us — it doesn’t stop someone from capturing and resending an old, still-valid request later. Every delivery carries a unique nonce and a sent_at timestamp, both covered by the signature above, so you can reject a resend even if its signature checks out.

// Reject anything older than 5 minutes
if (strtotime($data['sent_at']) < time() - 300) {
    http_response_code(401);
    echo 'Stale request';
    exit;
}

// Reject a nonce you've already seen (store seen nonces for at
// least as long as your freshness window above, e.g. in a cache
// or a small database table)
if (nonce_already_seen($data['nonce'])) {
    http_response_code(401);
    echo 'Duplicate request';
    exit;
}
remember_nonce($data['nonce']);

Retries

If your endpoint doesn’t respond with a 2xx status, the delivery is treated as failed and may be retried or manually resent from your dashboard. A retry (or a manual resend from Webhook Events) carries the same transaction_id as the original delivery, with a fresh nonce/sent_at — this is expected and is exactly why you should key duplicate-detection off transaction_id, not reference: it’s the one field guaranteed to stay identical across every delivery attempt of the same payment, and guaranteed distinct between different payments.

You can review delivery history (including HTTP status codes returned) from the Webhook Events page in your dashboard, which also shows both reference and transaction_id for each event so you can trace exactly what was sent.

Respond quickly (under a few seconds) and with a 2xx status as soon as you’ve accepted the payload — do slow work (emails, downstream API calls) after responding, not before.