Integrations
Official SDKs
Server SDKs for Node.js, Python and PHP: install, first call, downloads with SHA-256 checksums, and webhook verification.
What the SDKs do
The SDKs wrap the Moolre API for server code. They send credentials in headers only, use channel names, attach Idempotency-Key to retries, read meta.requestid and meta.notices, raise typed errors, walk cursors for you and verify webhook signatures. Keep API keys on your server: never ship them to a browser or mobile app.
Each SDK is a thin client over the same HTTP API documented here. Anything the SDK does you can do with plain HTTP.
Install
Download the file for your language from the table below, check its checksum, and install it from disk. Each SDK is also published as a single file you can copy into your project.
# Node 18+, ESM and CommonJS, TypeScript types included, no runtime dependenciesnpm install ./moolre-sdk-0.1.2.tgzimport { Moolre } from '@moolre/sdk';const moolre = new Moolre({ environment: 'sandbox', user: process.env.MOOLRE_USER, apiKey: process.env.MOOLRE_API_KEY, pubKey: process.env.MOOLRE_PUBKEY, accountNumber: '1000000000001',});Step by step: your first SDK call
- Download the file for your language, check its SHA-256 checksum against SHA256SUMS, and install it.
- Create the client with environment "sandbox", your username, the keys you have and a default account number. Keep every credential in environment variables.
- Make a collection to the test number 0240000111 with an idempotency key. The result object carries ok, code, message, data, requestId, notices and replayed (read from meta.requestid, meta.notices and meta.replayed).
- If result.otpRequired is true (code TP14), call verifyOtp with 123456 and call initiate once more when it reports TP17.
- Catch the typed error for status 0 (ApiError and its subclasses) and read code, apiMessage, fields and requestId.
- Set strictHttpStatus if you want real HTTP status codes, and keep maxRetries low: the SDK retries network errors and 5xx only for reads and for calls that carry an idempotency key.
- Switch environment to "live" and the credentials to live ones when you go live.
Downloads and checksums
You can install from your package manager, or download the file from docs.moolre.com and check it against the published SHA-256 checksum. The same list is published as one file: SHA256SUMS.
Verify a download before you use it: on Linux or macOS run sha256sum -c SHA256SUMS in the folder that holds the files (shasum -a 256 on macOS), on Windows run Get-FileHash -Algorithm SHA256 <file>.
| SDK | Version | Install command | Download | SHA-256 |
|---|---|---|---|---|
| Node.js package | 0.1.2 | npm install ./moolre-sdk-0.1.2.tgz | moolre-sdk-0.1.2.tgz | 4952481c5da805481c3d5ee3b47fe901de6e8826487f6813e7c42b4905a12782 |
| Node.js single file (ESM) | 0.1.2 | import from ./moolre.bundle.mjs | moolre.bundle.mjs | c44dfe12dc101f58333d7d6e352fc769d95599cde3b8415c64383dfbb79e9a6b |
| Python wheel | 0.1.2 | pip install ./moolre-0.1.2-py3-none-any.whl | moolre-0.1.2-py3-none-any.whl | 935433661e43b491e17166da474931f0ef037f33b7840319bc927ebabfcf6955 |
| Python source | 0.1.2 | pip install ./moolre-0.1.2.tar.gz | moolre-0.1.2.tar.gz | 694e00b18cc3b3f3c365a236977deb6d61c4e9552f56be7bed017ec7c005d39c |
| Python single file | 0.1.2 | copy moolre.py next to your code | moolre.py | f080d73952ba1f775fe2d43edbb9695ab9e36137ec51a0450e6abb64b81f96ba |
| PHP package | 1.1.2 | unzip and use Composer | moolre-php-1.1.2.zip | 611b6d95088400296201cb65a1a002d41fc6cdf2697bc5403e64c79e803da8fe |
| PHP single file | 1.1.2 | require moolre-sdk.php | moolre-sdk.php | 10e70205efd8c75f4141379d239a735ad988b2adf0673942229b4d5b6b433bd3 |
| Webhook test vectors | 1 | JSON test cases for your own verifier | webhook.json | 551f708a42030725a98f3dbe508e42aded2ffd309e0b1a259bdc6ea948a71ccc |
Verify webhooks with an SDK
Every SDK has a constant-time verifier that checks the signature and the timestamp tolerance, and a helper that returns the parsed event.
import { constructEvent, WebhookSignatureError } from '@moolre/sdk';app.post('/moolre/webhook', express.raw({ type: '*/*' }), (req, res) => { try { const event = constructEvent(req.body, req.header('X-Moolre-Signature'), process.env.MOOLRE_WALLET_SECRET); // dedupe on event.eventId, then act once res.sendStatus(200); } catch (e) { if (e instanceof WebhookSignatureError) return res.sendStatus(400); throw e; }});Hosted checkout PHP package
The moolre/moolre-php package also contains the hosted checkout client described on the PHP SDK page. It is unchanged.
What each SDK covers
| Area | Methods |
|---|---|
| Collections | payments.initiate, payments.verifyOtp |
| Payouts | transfers.validateName, transfers.create, transfers.status |
| Bulk payouts | bulk.create, bulk.status, bulk.iterateItems, bulk.iterateBatches |
| Invoices | invoices.create, invoices.status, invoices.cancel, invoices.iterate |
| Accounts | accounts.iterateTransactions |
| Sales | sales.airtime |
| Messaging | sms.send, whatsapp.send, whatsapp.iterateTemplates |
| Webhooks | webhooks.test, webhooks.resend, webhooks.iterateDeliveries, constructEvent, verifyWebhook |
| Payment links | paymentLinks.create |
- Credentials come from environment variables and stay on the server.
- Retries use an idempotency key.
- You log requestId and notices.
- Webhooks are verified with constructEvent on the raw body.