Mamlaka
Payment API
Accept and send payments via mobile money, card, and bank transfer. Integrate seamlessly with M-Pesa, card gateways, and bank APIs across Africa.
REST API
JSON over HTTPS with JWT authentication
Callbacks
Async notifications for payment status
Multi-Channel
M-Pesa, Card, and Bank Transfer support
https://payments.mamlakapsp.com/api/v1Authentication
All authenticated endpoints require an Authorization: Bearer <token> header. First generate a token using Basic Auth via the endpoint.
Key Response Fields
secureIdEncrypted transaction identifier for secure referenceexternalIdYour merchant-provided reference IDtransactionStatusFinal state: COMPLETE, FAILED, or PENDINGtransactionReportDetailed status reportnetAmountAmount received after deductions/feescurrencyTransaction currency code (KES, USD, NGN, etc.)Country & Payment Method Coverage
Corridors Mamlaka Hub & Spoke currently operates, with the mobile money and alternative payment methods available for collections and payouts in each. A value in brackets is the exact string to send as `mobileMoneySP` — for example Orange Money is `ORANGE-MONEY`. Where an operator accepts several aliases, the bracket shows the canonical one and the endpoint sections list the alternatives. A method shown without a bracket is commercially available but its identifier is issued during onboarding, so ask your account manager before coding against it. This table is commercial coverage. The endpoint sections below carry the technical detail — operator identifiers, service IDs and request examples — for the corridors documented so far. For any corridor not covered below, operator identifiers and integration details are provided during onboarding. Pricing, settlement timelines and limits are not published here; your account manager provides the current rate card.
| Country | Collections | Payouts |
|---|---|---|
| Kenya (KES) | M-Pesa (M-Pesa), Airtel Money (AIRTEL) | M-Pesa (M-Pesa), Airtel Money (AIRTEL) |
| Nigeria (NGN) | Bank transfer / virtual account (Bank Transfer endpoint) | Bank transfer (Bank Transfer endpoint) |
| Burkina Faso (XOF) | Orange Money (ORANGE-MONEY, om_otp required). Moov: not available | Orange Money (ORANGE-MONEY). Moov: not available |
| Benin (XOF) | MTN (MTN). Moov: Remita collect only (BJMOOV), enabled per merchant | MTN (MTN). Moov: not available |
| Cameroon (XAF) | Orange Money (ORANGE-MONEY), MTN (MTN); also Remita collect (OMCM, MTNCM), enabled per merchant | Orange Money (ORANGE-MONEY), MTN (MTN) |
| Sénégal (XOF) | Orange Money (ORANGE-MONEY, om_otp required), Wave (WAVE), Free (FREE) | Wave (WAVE), Orange Money (ORANGE-MONEY), Free (FREE) |
| Ivory Coast (XOF) | Orange Money (ORANGE-MONEY), MTN (MTN), Moov (MOOV), Wave (WAVE) | Orange Money (ORANGE-MONEY), MTN (MTN), Moov (MOOV), Wave (WAVE) |
| Mali (XOF) | Moov Money only, via the Remita collect endpoint (method MLMOOV), enabled per merchant. Orange Money: not available. Mali numbers are refused on /mobile/initiate | Not available |
| Gambia (GMD) | Qmoney (QMONEY), Afrimoney (AFRIMONEY) | Qmoney (QMONEY), Afrimoney (AFRIMONEY) |
| Uganda (UGX) | MTN / Airtel via the Remita collect endpoint only (UGMTN, UGAIRTEL), enabled per merchant | MTN (MTN), Airtel (AIRTEL) |
| Zambia (ZMW) | MTN (MTN), Airtel (AIRTEL), Zamtel (ZAMTEL) | MTN (MTN), Airtel (AIRTEL), Zamtel (ZAMTEL) |
| Rwanda (RWF) | Airtel (AIRTEL), MTN (MTN) | Not available |
| Tanzania (TZS) | M-Pesa, Tigo, Airtel — enabled per merchant on request | M-Pesa, Tigo, Airtel — enabled per merchant on request |
| Ethiopia (ETB) | Not available | Telebirr — enabled per merchant on request |
Authentication
Obtain a JWT token required for all subsequent API operations. Use Basic Auth with your merchant credentials.
/api/v1BASICGenerate Token
Obtain a JWT token using your merchant credentials via Basic Authentication. This token is required for all other API calls.
Request
curl -X GET 'https://payments.mamlakapsp.com/api/v1' \
-H 'Authorization: Basic <credentials>'Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600
}Mobile Money — East Africa
Initiate STK Push payments (C2B) and money transfers (B2C) via mobile money. Set `mobileMoneySP` to "M-PESA" or "airtel" to choose the provider — the same endpoints handle both, so switching a transaction to Airtel is a one-field change. On success, the callback's `reference` field carries the provider receipt (M-Pesa or Airtel). When callback signing is enabled for your account, each callback carries an `X-Mamlaka-Signature: sha256=<hex HMAC-SHA256(rawBody, yourSecret)>` header — verify it against the shared secret Mamlaka issued you, using the exact raw request bytes and a constant-time comparison. Note: Airtel's minimum amount is 10 KES.
/api/v1/mobile/initiatePUBLICSTK Push (C2B)
Initiate an STK push to request payment from a customer's mobile money account. The customer receives a prompt on their phone to authorize the payment. Authenticated by your impalaMerchantId in the body — no bearer token is required. Supports M-Pesa and Airtel — set `mobileMoneySP` to "M-PESA" or "airtel". The result (COMPLETE/FAILED) is delivered via callback once the customer responds.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
impalaMerchantId | string | Yes | Your merchant username/ID |
displayName | string | Yes | Business name displayed to the customer on STK prompt |
currency | string | Yes | Currency code (e.g. "KES") |
amount | number | Yes | Amount to charge |
payerPhone | string | Yes | Customer phone number in international format (e.g. "254...") |
mobileMoneySP | string | Yes | Provider: "M-PESA" or "airtel" (case-insensitive). Airtel minimum is 10 KES. |
externalId | string | Yes | Your unique reference for this transaction |
callbackUrl | string | Yes | URL to receive payment status callbacks |
Request
{
"impalaMerchantId": "your_merchant_id",
"displayName": "Your Business Name",
"currency": "KES",
"amount": 10,
"payerPhone": "254712345678",
"mobileMoneySP": "M-Pesa",
"externalId": "order_12345",
"callbackUrl": "https://your-app.com/callback"
}Response
{
"message": "Payment initiation successful",
"secureId": "qdml8553ZeInavKorBHzLA==",
"transactionId": "order_12345"
}/api/v1/mobile/transferBEARERMoney Transfer (B2C)
Transfer money from your merchant account to a customer's mobile money account. Supports M-Pesa and Airtel — set `mobileMoneySP` to "M-PESA" or "airtel". Airtel disbursements typically settle immediately (COMPLETE in the response path); M-Pesa settles via callback.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
impalaMerchantId | string | Yes | Your merchant username/ID |
currency | string | Yes | Currency code (e.g. "KES") |
amount | number | Yes | Amount to transfer |
recipientPhone | string | Yes | Recipient phone number in international format (e.g. "254...") |
mobileMoneySP | string | Yes | Provider: "M-PESA" or "airtel" (case-insensitive). Airtel minimum is 10 KES. |
externalId | string | Yes | Your unique reference for this transaction |
callbackUrl | string | Yes | URL to receive transfer status callbacks |
Request
{
"impalaMerchantId": "your_merchant_id",
"currency": "KES",
"amount": 10,
"recipientPhone": "254712345678",
"mobileMoneySP": "M-Pesa",
"externalId": "transfer_12345",
"callbackUrl": "https://your-app.com/callback"
}Response
{
"message": "Payment initiation successful",
"secureId": "qdml8553ZeInavKorBHzLA==",
"transactionId": "a392-45d1-93c1-58f9447915e717138558"
}Mobile Money — West & Central Africa
XOF (UEMOA) and XAF (CEMAC) mobile money use the same two endpoints as East Africa — `/api/v1/mobile/initiate` to collect and `/api/v1/mobile/transfer` to pay out. This is not a separate API; only `currency`, `mobileMoneySP`, and the phone number change. A third endpoint, `/api/v1/remita/collect`, serves the corridors listed under it (Mali Moov among them) and is enabled per merchant. Country is resolved from the phone number, not a country field. A number from a country with no rail on the mobile endpoint (Mali, for example) is refused immediately with `400 UNSUPPORTED_CORRIDOR` and no transaction is created, so check the coverage table before routing traffic. Send the MSISDN with or without the country code (`+221776389999`, `221776389999`, or `776389999` are all accepted) and the operator is matched against that country's supported list. `currency` must be exactly `"XOF"` or `"XAF"` — uppercase, compared exactly. `mobileMoneySP` accepts an alias or the numeric service ID. Orange Money can be written `ORANGE-MONEY`, `ORANGE_MONEY`, `ORANGE`, or `OM` (case-insensitive); passing the numeric ID directly always works and skips alias resolution. `om_otp` is required in three cases — Senegal Orange Money collection, Burkina Faso Orange Money collection, and Senegal Orange Money payout. The customer generates it on their handset (`#144#391#`). Send it as a string so leading zeros survive. It is read from the JSON body first, then the `?om_otp=` query parameter, then the `X-OM-OTP` header, then the `om_otp` header — the body field is the recommended form. Omitting it returns `400 MISSING_OM_OTP`. Amounts on collection are whole numbers (XOF and XAF have no minor units) — send `200`, not `200.50`. Coverage: Senegal (XOF) Wave + Orange Money · Benin (XOF) MTN only · Burkina Faso (XOF) Orange Money only · Cameroon (XAF) MTN + Orange Money. Gambia (GMD, QMoney and AfriMoney) runs on this same contract — ask your account manager to enable it.
/api/v1/mobile/initiateBEARERCollection / Payin (XOF & XAF)
Charge a customer's mobile money wallet in West or Central Africa. The example shows Senegal Orange Money, which is the case that needs `om_otp`; for Wave, MTN, or Cameroon Orange Money drop that field and change `mobileMoneySP`. Service IDs by country and operator — Senegal: Wave `151`, Orange Money `153`. Benin: MTN `305` (no other operator is accepted for Benin). Burkina Faso: Orange Money `167`. Cameroon: MTN `339`, Orange Money `337`. Wave returns a `redirectUrl` — send the customer there to approve the payment. Orange Money and MTN prompt the customer on their handset instead. Final status always arrives on your `callbackUrl`.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
impalaMerchantId | string | Yes | Your merchant identifier |
currency | string | Yes | Exactly "XOF" or "XAF" |
amount | integer | Yes | Whole-number amount — XOF/XAF have no minor units |
payerPhone | string | Yes | Customer MSISDN, with or without country code. Determines the country. |
mobileMoneySP | string | Yes | Operator alias ("WAVE", "ORANGE-MONEY", "OM", "MTN") or the numeric service ID |
om_otp | string | Optional | Required for Senegal and Burkina Faso Orange Money collection. Send as a string to preserve leading zeros. |
externalId | string | Yes | Your unique reference for this transaction |
callbackUrl | string | Yes | URL to receive payment status callbacks |
Request
{
"impalaMerchantId": "your_merchant_id",
"currency": "XOF",
"amount": 200,
"payerPhone": "776389999",
"mobileMoneySP": "ORANGE-MONEY",
"om_otp": "091842",
"externalId": "SN-IN-001",
"callbackUrl": "https://your-app.com/callback"
}Response
{
"message": "Payment initiation successful",
"externalId": "SN-IN-001",
"secureId": "qdml8553ZeInavKorBHzLA==",
"redirectUrl": "https://pay.wave.com/..."
}/api/v1/mobile/transferBEARERPayout / Disbursement (XOF & XAF)
Send money from your merchant balance to a customer's mobile money wallet. Identical to collection except the phone field is `recipientPhone`. Service IDs by country and operator — Senegal: Wave `150`, Orange Money `152`. Benin: MTN `304`. Burkina Faso: Orange Money `166`. Cameroon: MTN `338`, Orange Money `336`. `om_otp` is required for Senegal Orange Money payouts. Burkina Faso payouts do not require it, even though Burkina collections do. Sending an operator the destination country does not support returns `400 UNSUPPORTED_SERVICE`.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
impalaMerchantId | string | Yes | Your merchant identifier |
currency | string | Yes | Exactly "XOF" or "XAF" |
amount | number | Yes | Amount to disburse |
recipientPhone | string | Yes | Recipient MSISDN, with or without country code. Determines the country. |
mobileMoneySP | string | Yes | Operator alias ("WAVE", "ORANGE-MONEY", "OM", "MTN") or the numeric service ID |
om_otp | string | Optional | Required for Senegal Orange Money payouts. Send as a string to preserve leading zeros. |
externalId | string | Yes | Your unique reference for this transaction |
callbackUrl | string | Yes | URL to receive payout status callbacks |
Request
{
"impalaMerchantId": "your_merchant_id",
"currency": "XOF",
"amount": 200,
"recipientPhone": "776389999",
"mobileMoneySP": "ORANGE-MONEY",
"om_otp": "091842",
"externalId": "SN-OUT-001",
"callbackUrl": "https://your-app.com/callback"
}Response
{
"message": "Payment initiation successful",
"externalId": "SN-OUT-001",
"secureId": "i1FHTQgFpHP0g-MRacZXUQ=="
}/api/v1/remita/collectBEARERCollection via Remita (Mali Moov, Cameroon, Uganda and other corridors)
A second collection path for corridors served by our Remita partner rather than the mobile endpoint. Today this is the only way to collect Moov Money in Mali (MLMOOV), and an alternative route for Cameroon (OMCM, MTNCM), Benin Moov (BJMOOV), Uganda (UGMTN, UGAIRTEL), Senegal (SNWAVE, SNOM, SNFREE), Ivory Coast (CIWAVE, CIOM) and Burkina Faso (BFOM). It is enabled per merchant: until Mamlaka has switched it on for your account every call returns 403 REMITA_NOT_ENABLED. The customer receives a prompt on their phone; the result arrives on your callbackUrl as a signed callback with the same shape as every other collection. Note that `externalId` in the response and in the callback is Mamlaka's reference for this request; your own `externalId` is stored for reconciliation but the field to match on is `secureId`. `customerName` is mandatory because the partner requires the payer's name.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
externalId | string | Yes | Your unique reference for this transaction |
phoneNumber | string | Yes | Payer's number in international format without +, e.g. 22370123456 for Mali |
amount | integer | Yes | Whole units of the corridor currency (XOF for Mali, XAF for Cameroon, UGX for Uganda) |
method | string | Yes | Remita service type: "MLMOOV" (Moov Mali), "OMCM" / "MTNCM" (Cameroon Orange / MTN), "BJMTN" / "BJMOOV" (Benin), "UGMTN" / "UGAIRTEL" (Uganda), "SNWAVE" / "SNOM" / "SNFREE" (Senegal), "CIWAVE" / "CIOM" (Ivory Coast), "BFOM" (Burkina Faso). The method decides the country and currency; the number must belong to that country |
customerName | string | Yes | Payer's full name (required by the partner) |
callbackUrl | string | Yes | URL to receive the signed result callback |
Request
{
"externalId": "ML-IN-001",
"phoneNumber": "22370123456",
"amount": 1500,
"method": "MLMOOV",
"customerName": "Amadou Diallo",
"callbackUrl": "https://your-app.com/callback"
}Response
{
"secureId": "k3rJ0bq9m2X8Yq1wVt6c7A==",
"externalId": "7f3a9c21-d4b8-4e6f-9a12-0c5b7e8d1f34",
"status": "pending",
"message": "Remita collection initiated; the customer will receive a prompt.",
"amount": 1500,
"currency": "XOF"
}Card Payments
Accept Visa and Mastercard through the Mastercard Payment Gateway, with 3-D Secure (3DS2) on every payment. Two integration modes: Hosted page (recommended): Call `POST /card/initiate` and send the customer to the returned `cardLink`. The page is served by Mamlaka; the card number, expiry and security code are typed into fields hosted by the Mastercard gateway, so card data never reaches your systems and you stay out of PCI DSS scope. 3DS runs on that page. The customer is then redirected to your `redirectUrl` and you receive the signed callback. Server-to-server (S2S): Call `POST /card/s2s/initiate` with the card details from your own checkout page. This mode puts your systems in PCI DSS scope and is enabled per merchant only with a current attestation of compliance; without it the endpoint answers `403 CARD_S2S_NOT_ENABLED`. You render the 3DS challenge we return in the customer's browser. To keep this light, include our helper script on your checkout page: <script src="https://sandbox.payments.mamlakapsp.com/api/v1/card/s2s/mamlaka-s2s.js"></script>. It gives you MamlakaCard.browserDetails(), which builds the `browser` object from the customer's real browser on every browser we support, and MamlakaCard.renderChallenge(challengeHtml, "#selector"), which mounts the 3DS challenge. Post the browser object to your server together with the card form and forward it in the S2S call. Availability: live on the sandbox base URL `https://sandbox.payments.mamlakapsp.com` now; production card enablement is arranged through your account manager. KES is the tested currency; other currencies are enabled per merchant at onboarding. At go-live replace the sandbox host with the production base URL in every call, including the helper script src. Sandbox testing: use the Mastercard test cards with any future expiry and any 3-digit security code. 5555555555000018 pays without a challenge (frictionless). 5123450000000008, 4508750015741019 and 2223000000000007 trigger the 3DS challenge, which on sandbox is an issuer emulator page: choose the successful outcome and submit to complete the payment, or a failed outcome to see a decline. 5111111111111118 is a card whose issuer does not support 3DS (CARD_3DS_UNAVAILABLE). No real money moves on sandbox. The test gateway applies velocity rules, so repeated payments with the same test card within a short period can be blocked by the risk engine (callback reason mentions BLOCKED); switch to another test card or wait a few minutes. The sandbox callback must still reach a public URL; a request-capture service such as webhook.site works for inspection. Status is final only when you receive the callback or `GET /api/v1/transaction?reference=<externalId>` returns COMPLETE or FAILED. Never treat the redirect alone as proof of payment. Postman collection for both modes: https://merchant-docs.mamlakapsp.com/mamlaka-card-api.postman_collection.json
/api/v1/card/initiateBEARERInitiate Card Payment (hosted page)
Creates the payment and returns `cardLink`, the hosted page for this payment only. Redirect the customer there (full page, not an iframe). After payment the customer is sent to your `redirectUrl` with `status`, `secureId` and `externalId` appended as query parameters, for example `https://your-app.com/payment-complete?status=COMPLETE&secureId=...&externalId=order_12345`. If `redirectUrl` is omitted a plain Mamlaka result page is shown. The link is single-use and expires after 24 hours if nothing is paid; the row is then FAILED with reason "Checkout expired". `callbackUrl` and `redirectUrl` must be public http(s) URLs: private, loopback and link-local addresses are rejected with `INVALID_CALLBACK_URL` / `INVALID_REDIRECT_URL`. `externalId` must be unique per merchant (`409 DUPLICATE_EXTERNAL_ID`).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
impalaMerchantId | string | Yes | Your merchant username/ID |
currency | string | Yes | ISO 4217 code, e.g. "KES" |
amount | number | Yes | Amount to charge in major units (e.g. 1500 = KES 1,500.00) |
externalId | string | Yes | Your unique reference for this payment (max 40 characters are forwarded to the card gateway as the order reference) |
callbackUrl | string | Yes | Public URL that receives the signed status callback |
redirectUrl | string | Optional | Public URL the customer lands on after paying; status, secureId and externalId are appended |
description | string | Optional | Shown on the payment page and sent to the card gateway (max 127 characters) |
Request
{
"impalaMerchantId": "your_merchant_id",
"currency": "KES",
"amount": 1500,
"externalId": "order_12345",
"callbackUrl": "https://your-app.com/callbacks/mamlaka",
"redirectUrl": "https://your-app.com/payment-complete",
"description": "Order 12345"
}Response
{
"message": "card Payment initiation successful",
"cardLink": "https://payments.mamlakapsp.com/api/v1/card/checkout/OWXJJDUMgPvh9XQhSBy9xg%3D%3D",
"secureId": "OWXJJDUMgPvh9XQhSBy9xg==",
"provider": "mpgs"
}/api/v1/card/s2s/initiateBEARERInitiate Card Payment (server-to-server)
For merchants that collect card details on their own PCI DSS compliant checkout. Send the card and the customer's browser properties; we run 3-D Secure and, when the issuer allows it, the payment in one call. Three outcomes: `COMPLETE` (frictionless, paid), `3DS_REQUIRED` (render `challengeHtml` in the customer's browser: it auto-posts to the issuer inside an iframe, the customer completes the challenge, the issuer returns to Mamlaka, we finish the payment, send the callback and redirect the iframe to your `redirectUrl`), or `FAILED` with an `error` code (a payment declined after the challenge is reported on the callback and the redirect, not in this response). `browser.userAgent` and `browser.acceptHeader` are required and must be the customer's real values; the other browser fields improve frictionless rates. Minimal checkout page: <script src="https://sandbox.payments.mamlakapsp.com/api/v1/card/s2s/mamlaka-s2s.js"></script> <form id="card-form">...card fields...</form> <div id="challenge"></div> <script> document.getElementById("card-form").onsubmit = async (e) => { e.preventDefault(); const r = await fetch("/your-server/pay", { method: "POST", headers: {"Content-Type": "application/json"}, body: JSON.stringify({ card: readCardForm(), browser: MamlakaCard.browserDetails() }) }); const j = await r.json(); // your server forwards card + browser to POST /api/v1/card/s2s/initiate and returns our response if (j.status === "3DS_REQUIRED") MamlakaCard.renderChallenge(j.challengeHtml, "#challenge"); else showResult(j.status); }; </script> Card data is never stored or logged by Mamlaka and is never echoed in responses. Status is final on the callback or via the transaction status endpoint; a second call with the same externalId while a challenge is pending is rejected.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
impalaMerchantId | string | Yes | Your merchant username/ID |
currency | string | Yes | ISO 4217 code, e.g. "KES" |
amount | number | Yes | Amount to charge in major units |
externalId | string | Yes | Your unique reference for this payment |
callbackUrl | string | Yes | Public URL that receives the signed status callback |
redirectUrl | string | Optional | Where the challenge iframe is sent after 3DS; status, secureId and externalId are appended |
description | string | Optional | Order description (max 127 characters) |
card.number | string | Yes | PAN, digits only |
card.expiryMonth | string | Yes | Two digits, e.g. "01" |
card.expiryYear | string | Yes | Two digits, e.g. "29" |
card.securityCode | string | Yes | CVV/CVC, 3 or 4 digits |
browser.userAgent | string | Yes | The customer's User-Agent header |
browser.acceptHeader | string | Yes | The customer's Accept header |
browser.language | string | Optional | navigator.language, e.g. "en-US" |
browser.screenHeight | number | Optional | screen.height |
browser.screenWidth | number | Optional | screen.width |
browser.timeZone | number | Optional | new Date().getTimezoneOffset(), minutes from UTC |
browser.colorDepth | number | Optional | screen.colorDepth |
browser.javaEnabled | boolean | Optional | navigator.javaEnabled() |
browser.ipAddress | string | Optional | Customer's IP as seen by your server |
Request
{
"impalaMerchantId": "your_merchant_id",
"currency": "KES",
"amount": 1500,
"externalId": "order_12345",
"callbackUrl": "https://your-app.com/callbacks/mamlaka",
"redirectUrl": "https://your-app.com/payment-complete",
"description": "Order 12345",
"card": {
"number": "5123450000000008",
"expiryMonth": "01",
"expiryYear": "39",
"securityCode": "123"
},
"browser": {
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/130.0 Safari/537.36",
"acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"language": "en-US",
"screenHeight": 900,
"screenWidth": 1440,
"timeZone": -180,
"colorDepth": 24,
"javaEnabled": false,
"ipAddress": "197.232.22.252"
}
}Response
{
"status": "COMPLETE",
"secureId": "lXcT_RUJ0jBZnbErM5h5Rg==",
"externalId": "order_12345"
}Escrow
Hold a buyer's payment until the seller has delivered, then release it to the seller or refund the buyer. One escrow order carries the agreement (buyer, seller, amount, optional milestones), a ledger of every movement and a webhook outbox. Money never sits in your collection wallet while it is held: a funding payment goes into the escrow ledger (HOLD), a release pays the seller over mobile money (RELEASE) and a refund returns the funding card payment (REFUND). Lifecycle: CREATED -> FUNDED -> RELEASED (or PARTIALLY_RELEASED after a milestone) or REFUNDED. A FUNDED or PARTIALLY_RELEASED order can be DISPUTED, which freezes it until you resolve the dispute with RELEASE or REFUND; the resolution SLA is 72 hours. Funding rails: card (the hosted page or the server-to-server call, exactly as in Card Payments) and KES mobile money (M-Pesa STK push, Airtel Money). Release rails: M-Pesa, AIRTEL and TKASH payouts. Refunds are automatic for card-funded orders (back to the same card, within the card scheme's refund window); a mobile-money funded order is refunded by releasing to the buyer's phone. Every order endpoint takes `tenantMerchantId`, which must be the merchant your bearer token was issued to. The product is enabled per merchant: until your account is enrolled every call answers `403 ESCROW_NOT_ENABLED`. Sandbox: live now on `https://sandbox.payments.mamlakapsp.com`; the sandbox test phone 0710000000 funds and receives instantly without moving money, and the card test cards from Card Payments apply. Webhooks: each event is POSTed to the order's `callbackUrl` with the X-Mamlaka-Signature header (see Callbacks & Signature) and the headers X-Mamlaka-Event and X-Mamlaka-Event-Id. Body: { type, eventId, orderSecureId, orderExternalId, tenantMerchantId, environment, createdAt, data }. Types: order.created, order.funded, order.released, order.refunded, milestone.completed, dispute.opened, dispute.resolved. Answer 2xx; anything else is retried with exponential backoff (30 seconds doubling to one hour, 12 attempts, about six hours in all). Card-funded escrow carries chargeback exposure after a release: a buyer can still dispute the card payment with their bank, so your escrow terms should hold a reserve. Postman collection: https://merchant-docs.mamlakapsp.com/mamlaka-escrow-api.postman_collection.json
/api/v1/escrow/ordersBEARERCreate Escrow Order
Opens the agreement in CREATED state; no money moves. `milestones`, if given, must sum exactly to `amount`. `sellerPayoutRail` and `sellerPayoutDest` are the defaults a release uses; `buyerContact` is the default payer phone for mobile-money funding; `callbackUrl` receives the escrow webhooks and is the default callback for the funding and payout legs. `externalId` is your reference and must be unique (`409 DUPLICATE_EXTERNAL_ID`).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
tenantMerchantId | string | Yes | Your merchant ID (must match the token) |
externalId | string | Yes | Your unique reference for the escrow order |
currency | string | Yes | ISO 4217 code, e.g. "KES" |
amount | number | Yes | Total escrow amount in major units |
buyerName | string | Optional | Buyer display name |
buyerContact | string | Optional | Buyer phone; default payer for mobile-money funding |
sellerName | string | Optional | Seller display name |
sellerPayoutRail | string | Optional | Default release rail: "M-Pesa", "AIRTEL" or "TKASH" |
sellerPayoutDest | string | Optional | Default release destination (seller phone, 2547XXXXXXXX) |
fundingRail | string | Optional | Default funding rail: "card", "mpesa" or "airtel" |
callbackUrl | string | Optional | Public URL for escrow webhooks; also the default callback for the funding and payout legs |
milestones | array | Optional | [{ name, amount }] releasable slices; amounts must sum to amount |
Request
{
"tenantMerchantId": "your_merchant_id",
"externalId": "ESC-10021",
"currency": "KES",
"amount": 15000,
"buyerName": "Jane Buyer",
"buyerContact": "254712345678",
"sellerName": "Acme Supplies",
"sellerPayoutRail": "M-Pesa",
"sellerPayoutDest": "254798765432",
"fundingRail": "card",
"callbackUrl": "https://your-app.com/callbacks/escrow",
"milestones": [
{
"name": "Deposit",
"amount": 5000
},
{
"name": "Delivery",
"amount": 10000
}
]
}Response
{
"secureId": "ESC_v0J6rV8tbC4y8yJoq2DQHg",
"externalId": "ESC-10021",
"status": "CREATED",
"amount": 15000,
"currency": "KES"
}/api/v1/escrow/orders/{ref}?tenantMerchantId={merchantId}BEARERGet Escrow Order
Returns the order by `secureId` or `externalId` with its milestones, disputes, the full ledger and `heldBalance` (HOLD minus RELEASE/REFUND). `funding` shows the state of the funding payment (PENDING while a card or STK payment is in flight). `GET /api/v1/escrow/orders?tenantMerchantId=...` lists your latest 100 orders.
Request
curl -X GET 'https://payments.mamlakapsp.com/api/v1/escrow/orders/{ref}?tenantMerchantId={merchantId}' \
-H 'Authorization: Bearer <token>'Response
{
"order": {
"secureId": "ESC_v0J6rV8tbC4y8yJoq2DQHg",
"externalId": "ESC-10021",
"status": "FUNDED",
"amount": 15000,
"currency": "KES",
"fundedAmount": 15000,
"releasedAmount": 0,
"refundedAmount": 0,
"fundingRail": "card",
"sellerPayoutRail": "M-Pesa",
"sellerPayoutDest": "254798765432"
},
"funding": {
"secureId": "fgSOV22yE9HJ5hZ2na2Qgg==",
"status": "COMPLETE",
"rail": "CARD",
"detail": "Approved MASTERCARD 55555555xxxx0018"
},
"milestones": [
{
"id": 6,
"name": "Deposit",
"amount": 5000,
"status": "PENDING"
},
{
"id": 7,
"name": "Delivery",
"amount": 10000,
"status": "PENDING"
}
],
"disputes": [],
"ledger": [
{
"entryType": "HOLD",
"amount": 15000,
"currency": "KES",
"reference": "630607019421",
"note": "funded via card"
}
],
"heldBalance": 15000
}/api/v1/escrow/orders/{ref}/fundBEARERFund Escrow Order
Starts the payment that funds the order; amount and currency come from the order. Card: `mode` hosted returns `cardLink` to send the buyer to, `mode` s2s takes `card` and `browser` exactly as /card/s2s/initiate and answers COMPLETE, 3DS_REQUIRED or FAILED. Mobile money (`rail` mpesa or airtel): sends the prompt to `payerPhone` (default: the order's buyerContact) and answers PENDING until the operator confirms. The order becomes FUNDED when the payment settles (immediately for a frictionless S2S card or the sandbox test phone) and you receive the order.funded webhook plus the normal payment callback on `callbackUrl`. A failed attempt leaves the order CREATED so you can fund again; a pending one answers `409 FUNDING_IN_PROGRESS`.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
tenantMerchantId | string | Yes | Your merchant ID |
rail | string | Optional | "card" (default from the order), "mpesa" or "airtel" |
mode | string | Optional | Card only: "hosted" (default) or "s2s" |
payerPhone | string | Optional | Mobile money only: buyer phone, default buyerContact |
callbackUrl | string | Optional | Callback for the payment leg; default: the order's callbackUrl |
redirectUrl | string | Optional | Card only: where the buyer lands after paying |
description | string | Optional | Shown on the card page / statement |
card | object | Optional | S2S only: { number, expiryMonth, expiryYear, securityCode } |
browser | object | Optional | S2S only: buyer browser details (use MamlakaCard.browserDetails()) |
Request
{
"tenantMerchantId": "your_merchant_id",
"rail": "card",
"mode": "hosted",
"redirectUrl": "https://your-app.com/escrow/10021/paid"
}Response
{
"message": "card Payment initiation successful",
"cardLink": "https://sandbox.payments.mamlakapsp.com/api/v1/card/checkout/fgSOV22yE9HJ5hZ2na2Qgg%3D%3D",
"secureId": "fgSOV22yE9HJ5hZ2na2Qgg==",
"provider": "mpgs"
}/api/v1/escrow/orders/{ref}/releaseBEARERRelease to Seller
Pays the seller from the held balance over a mobile-money payout. Without `amount` or `milestoneId` the whole held balance is released and the order becomes RELEASED; a partial amount or a milestone leaves it PARTIALLY_RELEASED. `rail`, `destination` and `callbackUrl` default to the order's seller details. The payout is booked as a RELEASE ledger entry carrying the payout `secureId`; its own completion callback arrives on the callback URL like any payout. If the payout cannot be dispatched nothing is released (`502 PAYOUT_FAILED`).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
tenantMerchantId | string | Yes | Your merchant ID |
amount | number | Optional | Partial amount; default: whole held balance |
milestoneId | number | Optional | Release exactly this milestone's amount |
rail | string | Optional | "M-Pesa", "AIRTEL" or "TKASH"; default sellerPayoutRail |
destination | string | Optional | Seller phone; default sellerPayoutDest |
callbackUrl | string | Optional | Payout callback; default the order's callbackUrl |
externalId | string | Optional | Payout reference; default <orderSecureId>-R<n> |
Request
{
"tenantMerchantId": "your_merchant_id",
"milestoneId": 6
}Response
{
"secureId": "ESC_v0J6rV8tbC4y8yJoq2DQHg",
"externalId": "ESC-10021",
"status": "RELEASED",
"amount": 15000,
"currency": "KES",
"released": 15000,
"releasedAmount": 15000,
"refundedAmount": 0,
"heldBalance": 0,
"payout": {
"secureId": "ya7zluLdVHJBESN6iBhfEg==",
"externalId": "ESC_v0J6rV8tbC4y8yJoq2DQHg-R1",
"rail": "M-Pesa",
"recipient": "254798765432",
"message": "Payment initiation successful"
}
}/api/v1/escrow/orders/{ref}/refundBEARERRefund to Buyer
Returns held money to the buyer's card through the card gateway. Default `amount` is the whole held balance, which makes the order REFUNDED; a partial refund keeps the current status. The gateway refund is taken first and the REFUND ledger entry carries its receipt. Card-funded orders only: for a mobile-money funded order release to the buyer's phone instead.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
tenantMerchantId | string | Yes | Your merchant ID |
amount | number | Optional | Partial amount; default whole held balance |
reason | string | Optional | Stored on the ledger entry |
Request
{
"tenantMerchantId": "your_merchant_id",
"reason": "Seller could not deliver"
}Response
{
"secureId": "ESC_8IiFNa5uaDMeOvtJ5tJJVQ",
"externalId": "ESC-10022",
"status": "REFUNDED",
"amount": 10,
"currency": "KES",
"refunded": 10,
"refundedAmount": 10,
"releasedAmount": 0,
"heldBalance": 0,
"refund": {
"receipt": "630607011932",
"transactionId": "refund1",
"fundingSecureId": "18ISiXfZnbibRCxnoi33hA=="
}
}/api/v1/escrow/orders/{ref}/disputeBEAREROpen Dispute
Freezes a FUNDED or PARTIALLY_RELEASED order: status DISPUTED, no release until resolved. One open dispute at a time; the response carries the 72-hour `slaDeadline`. Emits dispute.opened.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
tenantMerchantId | string | Yes | Your merchant ID |
reason | string | Yes | Why the order is disputed (max 500 chars) |
evidenceRef | string | Optional | Link or reference to supporting evidence |
Request
{
"tenantMerchantId": "your_merchant_id",
"reason": "Goods arrived damaged",
"evidenceRef": "https://your-app.com/cases/551"
}Response
{
"secureId": "ESC_v0J6rV8tbC4y8yJoq2DQHg",
"externalId": "ESC-10021",
"status": "DISPUTED",
"heldBalance": 15000,
"dispute": {
"id": 3,
"status": "OPEN",
"reason": "Goods arrived damaged",
"slaDeadline": 1793864735
}
}/api/v1/escrow/orders/{ref}/dispute/resolveBEARERResolve Dispute
Closes the open dispute by paying one side: `resolution` RELEASE performs a release (same optional fields as Release to Seller) and REFUND performs a refund (optional `amount`). The dispute is marked RESOLVED in the same booking and dispute.resolved is emitted followed by order.released or order.refunded. The response is the release or refund response.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
tenantMerchantId | string | Yes | Your merchant ID |
resolution | string | Yes | "RELEASE" or "REFUND" |
note | string | Optional | Stored as the ledger note / refund reason |
amount | number | Optional | Partial amount; default whole held balance |
rail | string | Optional | RELEASE only; default sellerPayoutRail |
destination | string | Optional | RELEASE only; default sellerPayoutDest |
Request
{
"tenantMerchantId": "your_merchant_id",
"resolution": "REFUND",
"note": "Seller agreed to refund"
}Response
{
"secureId": "ESC_v0J6rV8tbC4y8yJoq2DQHg",
"externalId": "ESC-10021",
"status": "REFUNDED",
"heldBalance": 0,
"refunded": 15000,
"refund": {
"receipt": "630607015182",
"transactionId": "refund1"
}
}Bank Transfer
Receive payments via bank transfer. Generate virtual account details for customers to pay into.
/api/v1/bank/payinBEARERBank Transfer (Payin)
Receive payments via bank transfer from customers. Generates temporary bank account details for the customer to transfer funds to.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
externalId | string | Yes | Your unique reference for this transaction |
amount | number | Yes | Amount to collect |
currency | string | Yes | Currency code (e.g. "NGN") |
callbackUrl | string | Yes | URL to receive payment status callbacks |
customerName | string | Yes | Name of the paying customer |
customerEmail | string | Yes | Email of the paying customer |
accountName | string | Optional | Label shown to the payer (defaults to "Payment") |
Request
{
"externalId": "bank_order_12345",
"amount": 100,
"currency": "NGN",
"accountName": "Demo account",
"callbackUrl": "https://your-app.com/callback",
"customerName": "John Doe",
"customerEmail": "johndoe@gmail.com"
}Response
{
"secureId": "PSJRU873PGPI",
"externalId": "bank_order_12345",
"status": "pending",
"message": "Bank transfer initiated. Customer should pay to the account below.",
"amount": 100,
"currency": "NGN",
"bankAccountName": "Demo account",
"bankAccountNumber": "5010875892",
"bankName": "vfd",
"bankCode": "566",
"expiryDate": "2026-03-14T01:26:36.263Z"
}Balance
Check your merchant account balances for payins and payouts.
/api/v1/read/payins/balanceBEARERPayins (Collection) Balance
Retrieve your collection wallet balance — funds received from customers (payins), broken down per currency. `Balances` lists the raw balance in every wallet currency (0 where unused), plus `totalBalance`, the sum converted to your base currency.
Request
curl -X GET 'https://payments.mamlakapsp.com/api/v1/read/payins/balance' \
-H 'Authorization: Bearer <token>'Response
{
"merchantId": "your_merchant_id",
"baseCurrency": "KES",
"Balances": {
"merchantId": "your_merchant_id",
"baseCurrency": "KES",
"kesBalance": 71,
"xafBalance": 300,
"usdBalance": 0,
"ngnBalance": 0,
"totalBalance": 135.5
}
}/api/v1/read/payouts/balanceBEARERPayouts (Wallet) Balance
Retrieve your payout wallet balance — funds available to disburse to customers, broken down per currency. `Balances` lists the raw balance in every wallet currency (0 where unused), plus `totalBalance`, the sum converted to your base currency.
Request
curl -X GET 'https://payments.mamlakapsp.com/api/v1/read/payouts/balance' \
-H 'Authorization: Bearer <token>'Response
{
"merchantId": "your_merchant_id",
"baseCurrency": "KES",
"Balances": {
"merchantId": "your_merchant_id",
"baseCurrency": "KES",
"kesBalance": 8500,
"xafBalance": 0,
"usdBalance": 0,
"ngnBalance": 0,
"totalBalance": 8500
}
}Transactions
Query the status of any transaction using its secure ID or external reference.
/api/v1/transaction?reference={externalId}PUBLICTransaction Status
Look up a transaction's status. Pass the reference as a query parameter: `?reference=<value>`, where the value is your externalId (recommended), or the secureId, merchantRequestID, or checkoutRequestID. Optionally add `&merchant=<impalaMerchantId>`, but it must exactly match the merchant the transaction was booked under — if unsure, omit it. Note: the M-Pesa receipt number is NOT a lookup key. Do not query Safaricom directly (TSQ) — collections settle on Mamlaka's short code, so Safaricom returns "not found"; Mamlaka is the system of record. The response also returns `response_code` and `response_description` — the provider's (Safaricom / Airtel / etc.) result code and human-readable reason, e.g. why a transaction FAILED ("DS timeout user cannot be reached.", "The balance is insufficient for the transaction.") — and `callback_status`, which tells you whether Mamlaka delivered the completion webhook to your callbackUrl (`SENT` / `FAILED`). `transaction_report` is the direction (collection / withdraw), not the failure reason.
Request
curl -X GET 'https://payments.mamlakapsp.com/api/v1/transaction?reference={externalId}'Response
{
"transaction": {
"impalaMerchantId": "your_merchant_id",
"transaction_status": "COMPLETE",
"transaction_report": "collection",
"response_code": "0",
"response_description": "The service request is processed successfully.",
"callback_status": "SENT",
"currency": "KES",
"amount": 10,
"secure_id": "qdml8553ZeInavKorBHzLA==",
"external_id": "order_12345",
"callback_url": "https://your-app.com/callback",
"date_added": 1787138041
}
}Callbacks & Signature
How Mamlaka notifies your callbackUrl of final transaction status, and how to verify the X-Mamlaka-Signature header on every callback.
Callback payload
When a transaction reaches a final state we send an HTTP POST with a JSON body to the callbackUrl you supplied. Respond 200 OK to acknowledge. On success, reference carries the mobile-money receipt number (M-Pesa or Airtel); match on your externalId. The callback shape and signature are identical for M-Pesa and Airtel.
{
"amount": 10,
"currency": "KES",
"externalId": "order_12345",
"secureId": "i1FHTQgFpHP0g-MRacZXUQ==",
"reference": "UHJM32U1U5",
"transactionStatus": "COMPLETE",
"transactionReport": "collection"
}Signature verification — X-Mamlaka-Signature
When callback signing is enabled for your account, every callback carries an X-Mamlaka-Signature header. It is an HMAC-SHA256 of the exact raw request body, keyed with the shared secret Mamlaka issued you, hex-encoded:
X-Mamlaka-Signature: sha256=<hex HMAC-SHA256(rawBody, yourSecret)>Recompute the HMAC over the body as received(before any JSON re-serialization — re-stringifying can change the bytes and break the signature) and compare with a constant-time comparison:
const crypto = require('crypto')
function verifyMamlakaSignature(rawBody, header, secret) {
const expected = 'sha256=' +
crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
const a = Buffer.from(header || '', 'utf8')
const b = Buffer.from(expected, 'utf8')
return a.length === b.length && crypto.timingSafeEqual(a, b)
}
// Express: capture the RAW body so the bytes match what we signed
app.use('/callbacks/mamlaka', express.raw({ type: '*/*' }))
app.post('/callbacks/mamlaka', (req, res) => {
const raw = req.body // Buffer
if (!verifyMamlakaSignature(raw, req.get('X-Mamlaka-Signature'), process.env.MAMLAKA_CALLBACK_SECRET)) {
return res.sendStatus(401)
}
const payload = JSON.parse(raw.toString('utf8'))
// reconcile using payload.externalId + payload.reference ...
res.sendStatus(200)
})