Response envelope change: request ID and notices move into meta
Every JSON response now ends with a meta object that holds meta.requestid and meta.notices. The top-level request_id and notices fields and the outcome field are gone. Webhook payloads are unchanged.
meta is always present on every JSON response, as the last field. It holds meta.requestid (the same value as the X-Request-Id response header; your own X-Request-Id if you sent a valid one) and meta.notices (always an array, [] when there is nothing to report; each notice is `{ code, message, docs? }`).
The top-level request_id and notices fields are removed from API responses. They were added earlier on 15 November 2026 and now live inside meta.
The outcome field is removed everywhere.
error (failures) stays at the top level, before meta, unchanged. The X-Request-Id response header is still sent.
Idempotent replays (same Idempotency-Key and same body) carry meta.replayed: true. It replaces the top-level `replayed` field, which is removed. It is present only on replays. `data.replayed` on bulk payouts (BLK02) and invoice create (INV02) is resource data and stays where it is.
Webhook payloads: the top-level `notices` moved into `meta.notices` (`"meta": {"notices": []}`). event_id, event, created and all other fields stay at the top level. The X-Moolre-Signature header, an HMAC over the raw body, is unchanged. Webhooks have no requestid.
SDK releases
The official SDKs read `meta.requestid`, `meta.notices` and `meta.replayed`, and webhook `meta.notices` (falling back to the old top-level fields and the X-Request-Id header). Their `requestId` / `request_id` and `notices` properties are unchanged.
Published: Node.js `@moolre/sdk` 0.1.3 on npm (`npm install @moolre/sdk`; 0.1.3 only corrects the repository link to github.com/moolrehq/sdk), PHP `moolre/moolre-php` 1.1.2 on Packagist (`composer require moolre/moolre-php`) and the browser checkout `@moolre/moolrejs` 1.1.1 on npm (`npm install @moolre/moolrejs`).
Python `moolre` 0.1.2 is on PyPI since 17 November 2026 (`pip install moolre`). The files on PyPI are the same as the downloads on the SDKs page, which lists the SHA-256 checksum of every file.
Migration
Read the request id from `meta.requestid` instead of `request_id`, and the notices from `meta.notices` instead of `notices`. The X-Request-Id header carries the same value if you prefer it.
Stop reading `outcome`. Decide the result from `status`, `code` and `data.txstatus` (0 pending, 1 succeeded, 2 failed).
Treat these codes as pending, never as failed, because the result is unknown and the transaction may still succeed: PY01, PY02, TR01, TR02, TP11, TP18, APY10, APY16, ASL06 and SYS500. Check the status by externalref and never resend blindly.
Status 1 with TR08, OBGH01, OTGH01, OBNG01, GHQ03 or OM03 is final success. Any other status 1 is an accepted, unfinished request: treat it as pending.
The official SDKs keep their property names (requestId, request_id, notices) and read meta first, then the old top-level fields, then the X-Request-Id header, so SDK users need no code change.
If you read a top-level `replayed`, read `meta.replayed` instead (true only on idempotent replays). If you read a webhook payload top-level `notices`, read `meta.notices`.
Bulk payouts, invoices, signed webhooks and request IDs
Pay up to 500 recipients in one request, create invoices, verify webhooks with a signature, and trace every call with a request ID. Everything is additive and backwards compatible: existing requests and responses are unchanged.
Bulk payouts: Create bulk payout, Bulk payout status and List bulk payouts. Submit up to 500 payouts at once; every item is validated on submit, sent in the background and reported individually, and a `bulk_payout.completed` webhook is sent when the batch is final.
Invoices: Create invoice, Invoice status, List invoices and Cancel invoice, with a hosted payment link and a USSD payment code.
Webhook tools: Webhook deliveries, Resend webhook and Send test webhook, to see which events were delivered, replay a missed one and test your endpoint.
Webhooks
Every callback is signed with X-Moolre-Signature (`t=<unix>,v1=<HMAC-SHA256>`) and carries event_id, event and created. The verification guide has code for Node.js, Python, PHP, Go and C#.
Failed deliveries are retried at 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 24 hours, 48 hours and 72 hours.
data.secret is deprecated and will be removed after 2027-03-31. Verify the signature instead.
Callback URLs must serve a valid TLS certificate. A one-off unverified retry is allowed until 2026-12-31; after that a TLS failure is a failed delivery.
Responses
A meta object on every JSON response with requestid (the same value as the X-Request-Id header) and notices. Send your own X-Request-Id to correlate calls.
meta.notices advise you when a deprecated usage is detected, with a link to the Deprecations page.
An additive error object lists every failing field. Transaction rows gain an ISO 8601 created_at.
Opt in to real HTTP status codes with the request header X-Moolre-Http-Status: strict. Without it, behaviour is exactly as before.
List endpoints support cursor pagination with starting_after, has_more and next_cursor.
Safer retries and limits
Idempotency-Key header on collections, transfers, bulk payouts and invoices. A repeated key returns the stored response; the same key with a different body returns IDEM01.
One-time codes are rate limited per phone number, per IP address and per code (OTP429).
Transfers accept an optional sendername.
Channel names (MTN, TELECEL, AT, BANK) are accepted everywhere. Numeric ids still work and return a deprecation notice.
API keys in the URL or request body still work and return a deprecation notice. Send them in headers.
SDKs and documentation
Official server SDKs for Node.js, Python and PHP, with downloads and SHA-256 checksums.
Every error code the API can return is now documented, with explicit guidance for codes whose outcome is unknown, such as TP18: the payment request may still be sent, so do not retry.
The documentation site loads faster: pages and code editors load on demand, fonts and icons are self-hosted, and each page has its own title and description.
Added payername to the callback `data` object: the registered name on the payer’s account, as returned by the payment network.
Added payernetwork: the network the payer paid from, such as MTN, TELECEL, or AT.
Added payerinstitution: the institution that processed the payment for the payer. For mobile money it usually matches payernetwork.
Updated the successful payment callback example, the transaction field table, and the callback handling guidance on the Payment Webhook page, and in the generated AI documentation and Postman collection.
The new fields are additive. Existing fields are unchanged, so current integrations keep working. Treat payername as information for receipts and reconciliation, not as identity verification.
Added Airtime (POST /open/sales/airtime) to send airtime on MTN, Telecel, or AT, with a minimum amount of GHS 1.00.
Added Data (POST /open/sales/data) to send a network-specific data bundle. The bundle price determines the charge, so no amount is sent.
Added Bundles (POST /open/sales/bundles) to list bundle IDs, prices, quantities, validity, and categories, with an optional network filter.
Added Sales Status (POST /open/sales/status) to check an Airtime or Data sale by original external reference, transaction ID, or returned sale reference.
Added the Sales guide under Documentation > Common Workflows, covering service setup, special payment pricing, pending sale handling, bundle selection, and sale outcomes.
Documented Sales application codes (ASL, ASB, and ASS) in Errors and status codes, and included the new endpoints in generated AI documentation and the Postman collection.
Before you begin
Create a Sell on Our Platform Service in the Moolre App before using the Airtime or Data APIs. Special payment pricing is available for businesses selling airtime and data; contact Moolre Support to request it.
Pending is not delivered: ASL11 means a sale is in progress. Confirm the outcome with Sales Status before retrying, and never resubmit a pending sale with a new external reference.
Added Airtime and data top-ups: customers pay with Mobile Money Collection, the payment webhook triggers an Airtime or Data sale, and Sales Status confirms delivery. Includes Node.js and Python examples and a production checklist.
Added Rewards and incentives: pay survey, referral, and loyalty rewards as airtime or data from a pre-funded wallet, with campaign budgets, one reward per person, and abuse prevention guidance.
Both use cases cover every Sales Status outcome and explain how to avoid sending a sale twice after a timeout or ASL06.
Refreshed the existing use case pages with consistent headings, clearer step cards and status badges, better mobile layouts, and On this page links that no longer hide section titles under the header.
Included the new use cases in navigation, search, and generated AI documentation.
Removed Create Account from API Reference navigation, search, and generated API listings and Postman requests.
Create wallets at app.moolre.com. Existing documentation links now show this guidance instead of the request form.
Updated wallet setup guidance. Account settings, status, and transaction APIs remain documented; this documentation update does not announce a backend API shutdown.
Added IP Whitelisting for Disbursements as the first guide under Documentation > Build and Operate.
Documented the six-step flow: access API Services, select a service, open Security, choose Whitelist IP for Disbursement, add public server IP addresses, and save.
Included expandable screenshots showing the security settings and IP address form, plus On this page navigation.
Clarified service-specific configuration, multiple server IP addresses, IP address changes, secure API credentials, and the distinction from Moolre callback source IPs.
Formatted Important Notes as a bulleted list and Troubleshooting as four numbered checks, with links to related authentication and callback documentation.
Included the guide in generated AI documentation, search, and navigation.
Payment webhook failure guidance and callback source IPs
The Payment Webhook reference now documents failed payment callbacks alongside successful payments, with callback source IPs and section navigation in one place.
Added the failed payment callback example with status 0, code P02, and data.txstatus 2, while retaining the successful P01 example.
Documented the failure reason, nullable transactionid, zero-valued amount and value strings, and correlation using externalref.
Clarified how to handle failed attempts without marking payments as paid, and how to validate callbacks and handle duplicate notifications.
Moved callback source IPv4 and IPv6 addresses from Authentication to one ungrouped allowlist on Payment Webhook, with copy buttons and an Authentication link to the new location. Allowlist all the listed addresses.
Added On this page navigation for the overview, callback handling, fields, both examples, and callback source IPs.
Updated generated AI documentation and Postman guidance. Callback examples use YOUR_CALLBACK_SECRET rather than a real secret.
Moolre has updated its ID verification process to operate at the wallet level rather than the user-account level. Every newly created wallet now requires its own ID verification.
Shareable ID verification links allow users who create wallets on behalf of other individuals or businesses to send verification requests directly to the wallet owners.
For businesses creating multiple wallets, existing verified ID and KYC documents can be reused for new wallets, provided the new wallet belongs to the same business.
Key updates
Wallet-specific verification — ID verification is associated with individual wallets. Verification is required when a new wallet is created.
Reuse existing verification documents — Existing verified ID and KYC documents can be reused for additional wallets belonging to the same business, where the existing verification information is applicable. Businesses do not need to repeat the full verification process in those cases.
Shareable verification links — Generate a link and send it to the wallet owner to complete verification remotely. This supports software providers, businesses, and organizations creating wallets for clients or customers.
Seven-day validity — Verification links are valid for 7 days. The wallet owner must complete verification before the link expires.
How to complete ID verification
Wallet verification can be accessed from two locations within the Moolre platform:
Profile → Documents — Open the Documents page from the profile dropdown to access and complete the required ID verification.
Wallet Admin → Wallet Verification — Open Wallet Verification in the admin panel of the wallet requiring verification. Initiate verification directly or generate a link to share with the wallet owner.
How it works: a new wallet
Create a new wallet on Moolre.
Open Documents from the profile dropdown, or Wallet Verification in the admin panel of the specific wallet.
Check the wallet's verification status.
Reuse existing verified documents if they are available and applicable to the same business.
If new verification is required, initiate the ID verification process.
Complete verification directly, or generate and share a verification link with the wallet owner.
How it works: remote verification
Open Wallet Verification for the specific wallet.
Generate the ID verification link.
Share the link with the wallet owner.
The wallet owner opens the link and completes verification.
The verification status is updated once the process is completed.
Remember: verification links expire after 7 days.
Example use case
A software provider creates Moolre wallets on behalf of several businesses. For a business that already has verified ID and KYC documents, those documents can be reused for additional wallets belonging to that same business.
If the wallet owner needs new verification, the provider generates a verification link and sends it to the owner. The owner completes verification remotely without needing to be physically present with the provider.
Benefits
Wallet-level verification — Each wallet has its own verification status.
Reduced repetition — Reuse existing verified documents for additional wallets belonging to the same business.
Remote verification — Wallet owners can complete verification from anywhere using a shared link.
Simpler onboarding for software providers — Create wallets for clients without requiring owners to be physically present.
Flexible access — Start verification from the profile Documents page or the wallet-specific Wallet Verification section.
Availability
Wallet-specific ID verification availability
Item
Details
Feature
Wallet-Specific ID Verification
Verification Provider
Veriff
Verification Level
Wallet
Verification Link Validity
7 days
Existing KYC Documents
Can be reused for new wallets belonging to the same business
Remote Verification
Supported
Verification Access
Profile → Documents or Wallet Admin → Wallet Verification
Moolre has updated API key management to operate at the wallet level. API keys are associated with specific wallets rather than being generally available across a user account.
To use Moolre APIs with a wallet, first create an API Service for that wallet and generate the credentials associated with the service.
This provides greater control over which wallets connect to external applications and helps ensure API transactions are processed against the intended wallet.
Key updates
Wallet-specific API keys — A key generated for one wallet cannot access or process transactions for another wallet. Each wallet used with Moolre APIs needs its own API Service and credentials.
An API Service for each wallet — Create a service for the specific wallet before integrating. The service connects the wallet to the application or system using Moolre APIs.
Independent integrations — If you manage multiple wallets, create an API Service for each wallet. Each integration operates independently and is linked to its respective wallet.
For example: Wallet A → API Service A → API Key A; Wallet B → API Service B → API Key B; Wallet C → API Service C → API Key C.
How it works
Create an API Service: create a service and link it to the specific wallet.
Generate API credentials: generate the API key and other required credentials for that service.
Integrate: use the credentials generated for that wallet when integrating Moolre APIs into your application.
Repeat for other wallets: create a separate API Service for each additional wallet and generate its corresponding credentials.
Example use case
A business has three Moolre wallets: Main Wallet, Operations Wallet, and Collections Wallet. It wants to integrate Moolre APIs with all three.
Instead of using one API key across the account, the business creates a separate API Service for each wallet:
Separate API services and credentials for three wallets
Wallet
API Service
API Credentials
Main Wallet
Main Wallet API Service
Credentials for Main Wallet
Operations Wallet
Operations API Service
Credentials for Operations Wallet
Collections Wallet
Collections API Service
Credentials for Collections Wallet
Each API integration is directly connected to the wallet it is intended to operate on.
Benefits
Wallet-level control — API access is directly associated with a specific wallet.
Improved security — Credentials for one wallet cannot be used as the API credentials for another wallet.