Webhooks - Monirates

Webhooks allow your system to receive real-time event notifications from Monirates. When key events happen — like a payment, currency exchange, or wallet transaction — Monirates sends an HTTP POST request with a JSON payload to your registered URL. Every payload is wrapped in a consistent envelope with an event type, so you can safely handle events from multiple Monirates services (exchange, payment links, wallets, stablecoin wallets, and more) on the same webhook URL.

Setup Overview

All webhook configuration happens in your Monirates dashboard:

Log in at business.monirates.com (or dev.business.monirates.com for sandbox).
Navigate to Settings.
Generate your API Key and Secret Key.
Register your Webhook URL.

Monirates delivers all event types to a single registered webhook URL. Use the event field on every payload to route and handle each event type in your own system — see Event Types & Sample Payloads below.

Step 1: Generate Your API Key

Your API key authorizes requests and enables your webhook to receive events. Include it in your request headers:

x-api-key: MR_v1_your_unique_api_key

Step 2: Generate Your Secret Key

The Secret Key is used to verify that incoming webhook events genuinely originate from Monirates. Every webhook delivery includes a signature header:

x-monirates-signature: <signature>

The signature is computed using HMAC SHA256 over the raw request body — the full envelope (event, data, and timestamp together) — combined with your Secret Key. Signing the full envelope, not just data, ensures the event type itself can’t be altered without invalidating the signature.

Validating the Signature

Always validate the signature before processing any webhook event.

const crypto = require('crypto');

const signature = req.headers['x-monirates-signature'];

const computed = crypto
  .createHmac('sha256', process.env.MONIRATES_SECRET_KEY)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (computed !== signature) {
  return res.status(401).send('Invalid signature');
}

// Safe to process the event
const { event, data, timestamp } = req.body;

import hmac
import hashlib
import json
import os

secret_key = os.environ.get("MONIRATES_SECRET_KEY").encode()
signature = request.headers.get("x-monirates-signature")

body = json.dumps(request.json, separators=(',', ':')).encode()
computed = hmac.new(secret_key, body, hashlib.sha256).hexdigest()

if not hmac.compare_digest(computed, signature):
    return {"error": "Invalid signature"}, 401

# Safe to process the event
event_type = request.json["event"]
data = request.json["data"]

$secretKey = getenv('MONIRATES_SECRET_KEY');
$signature = $_SERVER['HTTP_X_MONIRATES_SIGNATURE'];

$body = file_get_contents('php://input');
$computed = hash_hmac('sha256', $body, $secretKey);

if (!hash_equals($computed, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Safe to process the event
$payload = json_decode($body, true);
$event = $payload['event'];
$data = $payload['data'];

Never share your Secret Key. Store it securely as an environment variable and never commit it to version control.

Step 3: Register Your Webhook URL

Your webhook endpoint must:

Accept POST requests
Receive JSON payloads
Be publicly accessible over HTTPS

Retry Behavior

If Monirates cannot reach your endpoint, deliveries are retried automatically:

Attempt	Behavior
1st	Initial delivery
2nd	Retry after delay
3rd	Final retry after increased delay
After 3rd failure	Retries stop

Each retry re-signs the payload with a fresh timestamp — a signature from an earlier attempt is not reused.

Manual Retry via API

You can also view and retry failed webhook events programmatically:

Method	Endpoint	Description
`GET`	`/webhooks`	List all webhook events
`GET`	`/webhook/{webhookId}`	View details of a specific event
`POST`	`/webhook/{webhookId}/retry`	Manually retry a failed event

Security Requirements

Two headers are used to secure webhook communication:

Header	Purpose
`x-api-key`	Authorizes the incoming webhook request
`x-monirates-signature`	Validates authenticity and payload integrity

Always reject webhook events that are missing or have an invalid x-monirates-signature. Do not process unsigned events.

Event Types & Sample Payloads

Every webhook delivery uses the same envelope:

{
  "event": "<event_type>",
  "data": { /* event-specific payload */ },
  "timestamp": "2026-08-10T09:15:00.000Z"
}

Field	Description
`event`	Identifies the event type. See the list below.
`data`	The event-specific payload — shape depends on `event`.
`timestamp`	ISO 8601 timestamp of when this delivery was signed and sent.

Some event types cover multiple states of the same resource (for example, a currency exchange moving from PENDING to SUCCESSFUL). In those cases the event stays the same across deliveries, and you distinguish the state using the status (or type) field inside data.

`exchange`

Triggered when a currency exchange transaction is initiated or updated. data.status reflects the current state (e.g. PENDING, PROCESSING,SUCCESSFUL, FAILED).

{
  "event": "exchange",
  "data": {
    "_id": "68ff77732efaebbdad28c843",
    "globalId": "2fd81ca0-b33b-11f0-82b7-2929f12a03df",
    "offerId": "68b5a636793705d3cc1578e7",
    "buyerGlobalId": "6976ea90-0afd-11f0-8cd1-296b05bbd448",
    "fromCurrency": "GBP",
    "toCurrency": "NGN",
    "rate": 1972.2,
    "fee": 0,
    "amount": 200,
    "status": "SUCCESSFUL",
    "buyerDebitPaymentMethod": "BANK_TRANSFER",
    "buyerCreditPaymentMethod": "BANK_TRANSFER",
    "buyerCreditPaymentDetails": {
      "accountName": "MONIRATES LIMITED",
      "accountNumber": "0115847370",
      "providerName": "SAFE HAVEN SANDBOX BANK",
      "bankCode": "999240",
      "paymentMethod": "BANK_TRANSFER",
      "iso2": "NG",
      "currency": "NGN"
    },
    "buyerDebitPaymentDetails": {
      "accountName": "MONIRATES LIMITED",
      "accountNumber": "0115847370",
      "providerName": "1234567",
      "bankCode": "1234567",
      "paymentMethod": "BANK_TRANSFER",
      "iso2": "GB",
      "currency": "GBP"
    },
    "sellerCreditPaymentDetails": {
      "accountName": "Rahama Rahama",
      "accountNumber": "2580369147",
      "providerName": "5566447755",
      "bankCode": "5566447755",
      "paymentMethod": "BANK_TRANSFER",
      "iso2": "GB",
      "currency": "GBP",
      "isUssdCode": false
    },
    "source": "API",
    "buyerMadePayment": true,
    "hasBuyerPaymentProof": false,
    "buyerPaymentProofUrl": null,
    "paymentReferenceCode": 938663,
    "createdAt": "2025-10-27T13:45:23.941Z",
    "updatedAt": "2025-10-27T13:55:26.972Z"
  },
  "timestamp": "2025-10-27T13:55:27.032Z"
}

`payment_link`

Triggered when a payment link transaction is initiated or updated.

{
  "event": "payment_link",
  "data": {
    "_id": "690df12b358c9311463ac6d4",
    "userId": "67e5345cdce758f487ab6ca6",
    "userGlobalId": "6976ea90-0afd-11f0-8cd1-296b05bbd448",
    "amount": 105500,
    "currencyIso2": "NG",
    "paymentDetails": {
      "accountName": "MONIRATES LIMITED",
      "accountNumber": "0115847370",
      "providerName": "MTN",
      "bankCode": "90221",
      "paymentMethod": "BANK_TRANSFER",
      "currency": "NGN"
    },
    "payerDetails": {
      "name": "Monirates",
      "email": "info@monirates.com"
    },
    "displayMessage": "Payment",
    "status": "PENDING",
    "source": "API",
    "globalId": "f7cfd470-bbdb-11f0-9062-8dd914a47085",
    "createdAt": "2025-11-07T13:16:27.986Z",
    "updatedAt": "2025-11-07T13:16:27.986Z"
  },
  "timestamp": "2025-11-07T13:16:28.114Z"
}

Payment link webhooks never include the payer authentication token. If your integration needs that token, retrieve it directly from the create-payment-link API response — it’s issued once, at creation, over an authenticated channel.

`wallet.created`

Triggered when a new fiat wallet is created for your business.

{
  "event": "wallet.created",
  "data": {
    "id": "10957760-7dad-13f1-bdb3-8c86b5ed01c6",
    "balance": 0,
    "heldBalance": 0,
    "incomingBalance": 0,
    "status": "ACTIVE",
    "currency": "NGN",
    "hasBankAccount": true,
    "bankDetails": {
      "accountName": "MoniratesLimite / SUDO",
      "accountNumber": "5123456789",
      "bankCode": "999240",
      "bankName": "Safe Haven MFB",
      "accountRef": "6a4fc22c38e1ef0024279ec6"
    }
  },
  "timestamp": "2026-08-10T09:00:00.000Z"
}

`wallet.virtual_account`

Triggered when a virtual bank account is created, funded (paid), or expires. data.status reflects the current state: PENDING, PAID, or EXPIRED.

{
  "event": "wallet.virtual_account",
  "data": {
    "id": "6a75ca32f338aecf092bec26",
    "walletId": "b00ee8b0-3caa-11f1-aa6b-8322aa66a919",
    "amount": 25000,
    "currency": "NGN",
    "accountNumber": "5123456789",
    "accountRef": "6a4fc22c38e1ef0024279ec6",
    "expiryDate": "2026-08-10T12:00:00.000Z",
    "validFor": 3600,
    "status": "PAID",
    "externalReference": "ext-ref-88213",
    "bankCode": "999240",
    "createdAt": "2026-08-10T09:00:00.000Z",
    "updatedAt": "2026-08-10T09:45:12.000Z"
  },
  "timestamp": "2026-08-10T09:45:12.114Z"
}

`wallet.transaction`

Triggered for any fiat wallet transaction — funding, transfers, payouts, and bank transactions. data.type identifies whether it was a credit or debit; data.status reflects the current state.

{
  "event": "wallet.transaction",
  "data": {
    "id": "6a01913a7a6ab126310a083b",
    "reference": "REF-88213",
    "currency": "NGN",
    "amount": 15000,
    "fee": 50,
    "status": "SUCCESSFUL",
    "paymentMethod": "MOBILE_MONEY",
    "narration": "Wallet funding",
    "purpose": "FUNDING",
    "type": "CREDIT",
    "valueGiven": true,
    "isReversed": false,
    "metadata": {
      "originatingCountry": "GH",
      "paymentMethod": "MOBILE_MONEY",
      "phoneNumber": "0245555555",
      "network": "MTN"
    },
    "createdAt": "2026-08-10T09:10:00.000Z",
    "updatedAt": "2026-08-10T09:10:05.000Z"
  },
  "timestamp": "2026-08-10T09:10:05.114Z"
}

Bank transfer example (data.metadata shape)

{
  "originatingCountry": "NG",
  "paymentMethod": "BANK_TRANSFER",
  "receiver": {
    "name": "Kwame Asamoah",
    "accountNumber": "0245555555",
    "bankName": "First Bank",
    "bankCode": "999024"
  }
}

`stable_wallet.created`

Triggered when a new stablecoin wallet is created for your business.

If data.parentId is present, this wallet belongs to a sub-account. Sub-accounts don’t have their own webhook URL — this event, and every future event for that sub-account’s wallet, is delivered to your parent business’s registered webhook URL.

{
  "event": "stable_wallet.created",
  "data": {
    "id": "9c1f3a10-3fbe-11f1-9a2c-8322aa66a919",
    "userId": "67e5345cdce758f487ab6ca6",
    "type": "BUSINESS",
    "parentId": null,
    "address": "0x8f3b1c2e9a4d5f6e7c8b9a0d1e2f3a4b5c6d7e8f",
    "tronAddress": "TXYZabc123def456ghi789jkl012mno345",
    "solanaAddress": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM6",
    "createdAt": "2026-08-10T09:00:00.000Z",
    "updatedAt": "2026-08-10T09:00:00.000Z"
  },
  "timestamp": "2026-08-10T09:00:00.114Z"
}

`stable_wallet.transaction`

Triggered for stablecoin wallet activity — deposits, and withdrawals as they move through PENDING and CONFIRMED states. data.type identifies the transaction type (DEPOSIT, WITHDRAWAL, REVERSAL); data.status reflects the current state.

For sub-account transactions, data.userId identifies the sub-account, but the webhook itself is always delivered to the parent business’s webhook URL — sub-accounts don’t have independent webhook configuration. Use data.userId to attribute the transaction to the correct sub-account on your side.

{
  "event": "stable_wallet.transaction",
  "data": {
    "id": "7b2e9f40-4cde-11f1-9a2c-8322aa66a919",
    "walletId": "9c1f3a10-3fbe-11f1-9a2c-8322aa66a919",
    "txHash": "0x4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b",
    "userId": "67e5345cdce758f487ab6ca6",
    "token": "USDT",
    "network": "TRON",
    "amount": "150.00",
    "fee": "1.50",
    "type": "WITHDRAWAL",
    "status": "CONFIRMED",
    "from": "TXYZabc123def456ghi789jkl012mno345",
    "to": "TABCdef456ghi789jkl012mno345pqr678",
    "createdAt": "2026-08-10T09:20:00.000Z",
    "updatedAt": "2026-08-10T09:21:30.000Z"
  },
  "timestamp": "2026-08-10T09:21:30.114Z"
}

Fetching Webhook Logs

Beyond the API, you can also view webhook delivery history directly in the Monirates dashboard — filter by event type, SUCCESSFUL, or FAILED, and track retry attempts for reconciliation.

Need help integrating? Reach out to the Monirates support team from your dashboard.

​Setup Overview

​Step 1: Generate Your API Key

​Step 2: Generate Your Secret Key

​Validating the Signature

​Step 3: Register Your Webhook URL

​Retry Behavior

​Manual Retry via API

​Security Requirements

​Event Types & Sample Payloads

​exchange

​payment_link

​wallet.created

​wallet.virtual_account

​wallet.transaction

​stable_wallet.created

​stable_wallet.transaction

​Fetching Webhook Logs

Setup Overview

Step 1: Generate Your API Key

Step 2: Generate Your Secret Key

Validating the Signature

Step 3: Register Your Webhook URL

Retry Behavior

Manual Retry via API

Security Requirements

Event Types & Sample Payloads

`exchange`

`payment_link`

`wallet.created`

`wallet.virtual_account`

`wallet.transaction`

`stable_wallet.created`

`stable_wallet.transaction`

Fetching Webhook Logs