Receiving Mobile Money payments in real time

The Mobile Money webhook allows Orange Money (or MTN, coming soon) to send an automatic notification to SynkriaOps after each transaction on your merchant wallet. Customer payments appear in your bank journal in real time, with no manual statement import required.

Webhook vs manual import

Criterion	Manual import	Real-time webhook
Delay	24 hours to 7 days (manual export)	A few seconds after the transaction
Errors	Risk of duplicates or omissions	Zero — each payment is recorded exactly once
Effort	Export + drag-and-drop + review	None — fully automatic
Availability	Orange Money CM (production)	Orange Money CM (production), MTN MoMo (roadmap)

Tip

Enable the webhook if you receive more than 10 Mobile Money payments per month. Below this threshold, monthly manual import is still sufficient.

Prerequisites

• An active Orange Money Business merchant account (contact Orange Business Cameroon: +237 655 00 04 44 or orangebusiness.cm).
• The Mobile Money account must be configured in SynkriaOps (see Setting up a bank account).
• The Administrator role on the SynkriaOps company file.

Enabling the webhook in SynkriaOps

1. Go to Settings → Mobile Money → Webhook.

2. Click Enable webhook for the relevant Orange Money account.

3. SynkriaOps generates a unique webhook URL for your company file:

   https://api.synkriaops.com/api/mobile-money/callback/cm-your-tenant-id

4. Click Copy URL — you will need it when configuring the operator side.

5. Also note the HMAC secret displayed (shown only once). This secret is used to verify that each notification genuinely originates from Orange Money and not from a third party. Keep it in a safe place.

Caution

The HMAC secret is displayed only once. If you lose it, click Regenerate secret — the old secret will be revoked immediately and you will need to reconfigure it on the operator side.

Configuring the webhook at Orange Business Cameroon

1. Log in to your Orange Business Cameroon portal.

2. Go to My merchant account → API settings → Webhooks.

3. Click Add a webhook endpoint.

4. Paste the SynkriaOps URL copied in the previous step.

5. In the Secret key (or HMAC secret) field, paste the secret provided by SynkriaOps.

6. Check the events to notify:

   • payment.received (payment received on your merchant wallet) — mandatory
   • payment.failed (failed payment) — optional, ignored by SynkriaOps (rule R1)

7. Save. Orange Business sends a test notification — SynkriaOps will respond 200 OK if the configuration is correct.

Testing the connection

1. In Settings → Mobile Money → Webhook, click Test connection.

2. SynkriaOps sends a test request to Orange and verifies the response.

3. The status changes to Active (green) if the test succeeds, or Error (red) with a detailed error message.

Webhook security

Each incoming notification is verified in two steps:

1. HMAC-SHA256 signature

Orange Money signs each webhook request with the shared secret. SynkriaOps verifies this signature before any processing:

• If the signature is invalid → 401 Unauthorized, no recording.
• If the signature is valid → notification is processed.

Verification uses a constant-time comparison (timingSafeEqual) to prevent timing attacks.

2. IP allowlist (recommended)

For additional security, enter the Orange Business Cameroon IP ranges in Settings → Mobile Money → Webhook → Allowed IPs. Any notification from an unauthorized IP is rejected before even reaching the HMAC check.

Contact Orange Business to obtain the IP ranges of their notification servers.

Note

The IP allowlist is optional but strongly recommended for merchant accounts with a high volume (> 100 payments/day).

What happens on each incoming payment

When a customer pays you via Orange Money:

1. Orange Business sends a JSON notification to the SynkriaOps URL.
2. SynkriaOps verifies the HMAC signature and the source IP.
3. The transaction is created with status TO_PROCESS in the BNQ journal linked to the Mobile Money account.
4. If the payment of 150,000 XAF comes from a customer linked to an outstanding invoice, SynkriaOps automatically suggests reconciliation.
5. A full audit trail is recorded (timestamp, source IP, verification status).

Webhook monitoring

1. In Banking & treasury → Mobile Money → Webhook history, view the list of all notifications received.

2. For each notification you see:

   • Date and time of receipt
   • Transaction amount and reference
   • HMAC verification status (VALID / INVALID)
   • Processing status (SUCCESS / DUPLICATE / ERROR)

3. In case of an error, click Details to see the full error message and manually retry if needed.

Troubleshooting

Problem	Likely cause	Solution
Webhook status “Error” after test	URL incorrectly copied or wrong HMAC secret	Verify the URL and regenerate the secret if necessary
Payments received but not recorded	Source IP not authorized (if IP allowlist is active)	Add the Orange Business IP ranges to the allowed list
Duplicate notifications	Same transaction notified twice	SynkriaOps deduplicates automatically by transaction reference — ignore
”401 Unauthorized” in Orange logs	HMAC secret expired or regenerated without updating the operator side	Reconfigure the secret in the Orange Business portal

Further reading

• Setting up a bank account or Mobile Money wallet →
• Import a Mobile Money statement →