Moolre Documentation

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.tgz​import { 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

  1. Download the file for your language, check its SHA-256 checksum against SHA256SUMS, and install it.
  2. Create the client with environment "sandbox", your username, the keys you have and a default account number. Keep every credential in environment variables.
  3. 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).
  4. If result.otpRequired is true (code TP14), call verifyOtp with 123456 and call initiate once more when it reports TP17.
  5. Catch the typed error for status 0 (ApiError and its subclasses) and read code, apiMessage, fields and requestId.
  6. 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.
  7. 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>.

SDKVersionInstall commandDownloadSHA-256
Node.js package0.1.2npm install ./moolre-sdk-0.1.2.tgzmoolre-sdk-0.1.2.tgz4952481c5da805481c3d5ee3b47fe901de6e8826487f6813e7c42b4905a12782
Node.js single file (ESM)0.1.2import from ./moolre.bundle.mjsmoolre.bundle.mjsc44dfe12dc101f58333d7d6e352fc769d95599cde3b8415c64383dfbb79e9a6b
Python wheel0.1.2pip install ./moolre-0.1.2-py3-none-any.whlmoolre-0.1.2-py3-none-any.whl935433661e43b491e17166da474931f0ef037f33b7840319bc927ebabfcf6955
Python source0.1.2pip install ./moolre-0.1.2.tar.gzmoolre-0.1.2.tar.gz694e00b18cc3b3f3c365a236977deb6d61c4e9552f56be7bed017ec7c005d39c
Python single file0.1.2copy moolre.py next to your codemoolre.pyf080d73952ba1f775fe2d43edbb9695ab9e36137ec51a0450e6abb64b81f96ba
PHP package1.1.2unzip and use Composermoolre-php-1.1.2.zip611b6d95088400296201cb65a1a002d41fc6cdf2697bc5403e64c79e803da8fe
PHP single file1.1.2require moolre-sdk.phpmoolre-sdk.php10e70205efd8c75f4141379d239a735ad988b2adf0673942229b4d5b6b433bd3
Webhook test vectors1JSON test cases for your own verifierwebhook.json551f708a42030725a98f3dbe508e42aded2ffd309e0b1a259bdc6ea948a71ccc

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

AreaMethods
Collectionspayments.initiate, payments.verifyOtp
Payoutstransfers.validateName, transfers.create, transfers.status
Bulk payoutsbulk.create, bulk.status, bulk.iterateItems, bulk.iterateBatches
Invoicesinvoices.create, invoices.status, invoices.cancel, invoices.iterate
Accountsaccounts.iterateTransactions
Salessales.airtime
Messagingsms.send, whatsapp.send, whatsapp.iterateTemplates
Webhookswebhooks.test, webhooks.resend, webhooks.iterateDeliveries, constructEvent, verifyWebhook
Payment linkspaymentLinks.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.