Payment Service Provider

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

Base URL
https://payments.mamlakapsp.com/api/v1

Authentication

All authenticated endpoints require an Authorization: Bearer <token> header. First generate a token using Basic Auth via the endpoint.

PUBLICBASIC AUTHBEARER

Key Response Fields

secureIdEncrypted transaction identifier for secure reference
externalIdYour merchant-provided reference ID
transactionStatusFinal state: COMPLETE, FAILED, or PENDING
transactionReportDetailed status report
netAmountAmount received after deductions/fees
currencyTransaction 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.

CountryCollectionsPayouts
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 availableOrange Money (ORANGE-MONEY). Moov: not available
Benin (XOF)MTN (MTN). Moov: Remita collect only (BJMOOV), enabled per merchantMTN (MTN). Moov: not available
Cameroon (XAF)Orange Money (ORANGE-MONEY), MTN (MTN); also Remita collect (OMCM, MTNCM), enabled per merchantOrange 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/initiateNot 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 merchantMTN (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 requestM-Pesa, Tigo, Airtel — enabled per merchant on request
Ethiopia (ETB)Not availableTelebirr — enabled per merchant on request

Authentication

Obtain a JWT token required for all subsequent API operations. Use Basic Auth with your merchant credentials.

GET/api/v1BASIC

Generate Token

Obtain a JWT token using your merchant credentials via Basic Authentication. This token is required for all other API calls.

Request

cURL
curl -X GET 'https://payments.mamlakapsp.com/api/v1' \
  -H 'Authorization: Basic <credentials>'

Response

Success (200)
1234
{
  "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.

POST/api/v1/mobile/initiatePUBLIC

STK 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

ParameterTypeRequiredDescription
impalaMerchantIdstringYesYour merchant username/ID
displayNamestringYesBusiness name displayed to the customer on STK prompt
currencystringYesCurrency code (e.g. "KES")
amountnumberYesAmount to charge
payerPhonestringYesCustomer phone number in international format (e.g. "254...")
mobileMoneySPstringYesProvider: "M-PESA" or "airtel" (case-insensitive). Airtel minimum is 10 KES.
externalIdstringYesYour unique reference for this transaction
callbackUrlstringYesURL to receive payment status callbacks

Request

Request Body
12345678910
{
  "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

Success (200)
12345
{
  "message": "Payment initiation successful",
  "secureId": "qdml8553ZeInavKorBHzLA==",
  "transactionId": "order_12345"
}
POST/api/v1/mobile/transferBEARER

Money 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

ParameterTypeRequiredDescription
impalaMerchantIdstringYesYour merchant username/ID
currencystringYesCurrency code (e.g. "KES")
amountnumberYesAmount to transfer
recipientPhonestringYesRecipient phone number in international format (e.g. "254...")
mobileMoneySPstringYesProvider: "M-PESA" or "airtel" (case-insensitive). Airtel minimum is 10 KES.
externalIdstringYesYour unique reference for this transaction
callbackUrlstringYesURL to receive transfer status callbacks

Request

Request Body
123456789
{
  "impalaMerchantId": "your_merchant_id",
  "currency": "KES",
  "amount": 10,
  "recipientPhone": "254712345678",
  "mobileMoneySP": "M-Pesa",
  "externalId": "transfer_12345",
  "callbackUrl": "https://your-app.com/callback"
}

Response

Success (200)
12345
{
  "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.

POST/api/v1/mobile/initiateBEARER

Collection / 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

ParameterTypeRequiredDescription
impalaMerchantIdstringYesYour merchant identifier
currencystringYesExactly "XOF" or "XAF"
amountintegerYesWhole-number amount — XOF/XAF have no minor units
payerPhonestringYesCustomer MSISDN, with or without country code. Determines the country.
mobileMoneySPstringYesOperator alias ("WAVE", "ORANGE-MONEY", "OM", "MTN") or the numeric service ID
om_otpstringOptionalRequired for Senegal and Burkina Faso Orange Money collection. Send as a string to preserve leading zeros.
externalIdstringYesYour unique reference for this transaction
callbackUrlstringYesURL to receive payment status callbacks

Request

Request Body
12345678910
{
  "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

Success (200)
123456
{
  "message": "Payment initiation successful",
  "externalId": "SN-IN-001",
  "secureId": "qdml8553ZeInavKorBHzLA==",
  "redirectUrl": "https://pay.wave.com/..."
}
POST/api/v1/mobile/transferBEARER

Payout / 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

ParameterTypeRequiredDescription
impalaMerchantIdstringYesYour merchant identifier
currencystringYesExactly "XOF" or "XAF"
amountnumberYesAmount to disburse
recipientPhonestringYesRecipient MSISDN, with or without country code. Determines the country.
mobileMoneySPstringYesOperator alias ("WAVE", "ORANGE-MONEY", "OM", "MTN") or the numeric service ID
om_otpstringOptionalRequired for Senegal Orange Money payouts. Send as a string to preserve leading zeros.
externalIdstringYesYour unique reference for this transaction
callbackUrlstringYesURL to receive payout status callbacks

Request

Request Body
12345678910
{
  "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

Success (200)
12345
{
  "message": "Payment initiation successful",
  "externalId": "SN-OUT-001",
  "secureId": "i1FHTQgFpHP0g-MRacZXUQ=="
}
POST/api/v1/remita/collectBEARER

Collection 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

ParameterTypeRequiredDescription
externalIdstringYesYour unique reference for this transaction
phoneNumberstringYesPayer's number in international format without +, e.g. 22370123456 for Mali
amountintegerYesWhole units of the corridor currency (XOF for Mali, XAF for Cameroon, UGX for Uganda)
methodstringYesRemita 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
customerNamestringYesPayer's full name (required by the partner)
callbackUrlstringYesURL to receive the signed result callback

Request

Request Body
12345678
{
  "externalId": "ML-IN-001",
  "phoneNumber": "22370123456",
  "amount": 1500,
  "method": "MLMOOV",
  "customerName": "Amadou Diallo",
  "callbackUrl": "https://your-app.com/callback"
}

Response

Accepted (200)
12345678
{
  "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

POST/api/v1/card/initiateBEARER

Initiate 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

ParameterTypeRequiredDescription
impalaMerchantIdstringYesYour merchant username/ID
currencystringYesISO 4217 code, e.g. "KES"
amountnumberYesAmount to charge in major units (e.g. 1500 = KES 1,500.00)
externalIdstringYesYour unique reference for this payment (max 40 characters are forwarded to the card gateway as the order reference)
callbackUrlstringYesPublic URL that receives the signed status callback
redirectUrlstringOptionalPublic URL the customer lands on after paying; status, secureId and externalId are appended
descriptionstringOptionalShown on the payment page and sent to the card gateway (max 127 characters)

Request

Request Body
123456789
{
  "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

Success (200)
123456
{
  "message": "card Payment  initiation successful",
  "cardLink": "https://payments.mamlakapsp.com/api/v1/card/checkout/OWXJJDUMgPvh9XQhSBy9xg%3D%3D",
  "secureId": "OWXJJDUMgPvh9XQhSBy9xg==",
  "provider": "mpgs"
}
POST/api/v1/card/s2s/initiateBEARER

Initiate 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

ParameterTypeRequiredDescription
impalaMerchantIdstringYesYour merchant username/ID
currencystringYesISO 4217 code, e.g. "KES"
amountnumberYesAmount to charge in major units
externalIdstringYesYour unique reference for this payment
callbackUrlstringYesPublic URL that receives the signed status callback
redirectUrlstringOptionalWhere the challenge iframe is sent after 3DS; status, secureId and externalId are appended
descriptionstringOptionalOrder description (max 127 characters)
card.numberstringYesPAN, digits only
card.expiryMonthstringYesTwo digits, e.g. "01"
card.expiryYearstringYesTwo digits, e.g. "29"
card.securityCodestringYesCVV/CVC, 3 or 4 digits
browser.userAgentstringYesThe customer's User-Agent header
browser.acceptHeaderstringYesThe customer's Accept header
browser.languagestringOptionalnavigator.language, e.g. "en-US"
browser.screenHeightnumberOptionalscreen.height
browser.screenWidthnumberOptionalscreen.width
browser.timeZonenumberOptionalnew Date().getTimezoneOffset(), minutes from UTC
browser.colorDepthnumberOptionalscreen.colorDepth
browser.javaEnabledbooleanOptionalnavigator.javaEnabled()
browser.ipAddressstringOptionalCustomer's IP as seen by your server

Request

Request Body
1234567891011121314151617181920212223242526
{
  "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

Paid, no challenge (200)
12345
{
  "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

POST/api/v1/escrow/ordersBEARER

Create 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

ParameterTypeRequiredDescription
tenantMerchantIdstringYesYour merchant ID (must match the token)
externalIdstringYesYour unique reference for the escrow order
currencystringYesISO 4217 code, e.g. "KES"
amountnumberYesTotal escrow amount in major units
buyerNamestringOptionalBuyer display name
buyerContactstringOptionalBuyer phone; default payer for mobile-money funding
sellerNamestringOptionalSeller display name
sellerPayoutRailstringOptionalDefault release rail: "M-Pesa", "AIRTEL" or "TKASH"
sellerPayoutDeststringOptionalDefault release destination (seller phone, 2547XXXXXXXX)
fundingRailstringOptionalDefault funding rail: "card", "mpesa" or "airtel"
callbackUrlstringOptionalPublic URL for escrow webhooks; also the default callback for the funding and payout legs
milestonesarrayOptional[{ name, amount }] releasable slices; amounts must sum to amount

Request

Request Body
1234567891011121314151617181920212223
{
  "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

Created (201)
1234567
{
  "secureId": "ESC_v0J6rV8tbC4y8yJoq2DQHg",
  "externalId": "ESC-10021",
  "status": "CREATED",
  "amount": 15000,
  "currency": "KES"
}
GET/api/v1/escrow/orders/{ref}?tenantMerchantId={merchantId}BEARER

Get 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
curl -X GET 'https://payments.mamlakapsp.com/api/v1/escrow/orders/{ref}?tenantMerchantId={merchantId}' \
  -H 'Authorization: Bearer <token>'

Response

Funded order (200)
12345678910111213141516171819202122232425262728293031323334353637383940414243444546
{
  "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
}
POST/api/v1/escrow/orders/{ref}/fundBEARER

Fund 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

ParameterTypeRequiredDescription
tenantMerchantIdstringYesYour merchant ID
railstringOptional"card" (default from the order), "mpesa" or "airtel"
modestringOptionalCard only: "hosted" (default) or "s2s"
payerPhonestringOptionalMobile money only: buyer phone, default buyerContact
callbackUrlstringOptionalCallback for the payment leg; default: the order's callbackUrl
redirectUrlstringOptionalCard only: where the buyer lands after paying
descriptionstringOptionalShown on the card page / statement
cardobjectOptionalS2S only: { number, expiryMonth, expiryYear, securityCode }
browserobjectOptionalS2S only: buyer browser details (use MamlakaCard.browserDetails())

Request

Request Body
123456
{
  "tenantMerchantId": "your_merchant_id",
  "rail": "card",
  "mode": "hosted",
  "redirectUrl": "https://your-app.com/escrow/10021/paid"
}

Response

Card, hosted page (200)
123456
{
  "message": "card Payment  initiation successful",
  "cardLink": "https://sandbox.payments.mamlakapsp.com/api/v1/card/checkout/fgSOV22yE9HJ5hZ2na2Qgg%3D%3D",
  "secureId": "fgSOV22yE9HJ5hZ2na2Qgg==",
  "provider": "mpgs"
}
POST/api/v1/escrow/orders/{ref}/releaseBEARER

Release 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

ParameterTypeRequiredDescription
tenantMerchantIdstringYesYour merchant ID
amountnumberOptionalPartial amount; default: whole held balance
milestoneIdnumberOptionalRelease exactly this milestone's amount
railstringOptional"M-Pesa", "AIRTEL" or "TKASH"; default sellerPayoutRail
destinationstringOptionalSeller phone; default sellerPayoutDest
callbackUrlstringOptionalPayout callback; default the order's callbackUrl
externalIdstringOptionalPayout reference; default <orderSecureId>-R<n>

Request

Request Body
1234
{
  "tenantMerchantId": "your_merchant_id",
  "milestoneId": 6
}

Response

Released (200)
123456789101112131415161718
{
  "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"
  }
}
POST/api/v1/escrow/orders/{ref}/refundBEARER

Refund 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

ParameterTypeRequiredDescription
tenantMerchantIdstringYesYour merchant ID
amountnumberOptionalPartial amount; default whole held balance
reasonstringOptionalStored on the ledger entry

Request

Request Body
1234
{
  "tenantMerchantId": "your_merchant_id",
  "reason": "Seller could not deliver"
}

Response

Refunded (200)
12345678910111213141516
{
  "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=="
  }
}
POST/api/v1/escrow/orders/{ref}/disputeBEARER

Open 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

ParameterTypeRequiredDescription
tenantMerchantIdstringYesYour merchant ID
reasonstringYesWhy the order is disputed (max 500 chars)
evidenceRefstringOptionalLink or reference to supporting evidence

Request

Request Body
12345
{
  "tenantMerchantId": "your_merchant_id",
  "reason": "Goods arrived damaged",
  "evidenceRef": "https://your-app.com/cases/551"
}

Response

Disputed (201)
123456789101112
{
  "secureId": "ESC_v0J6rV8tbC4y8yJoq2DQHg",
  "externalId": "ESC-10021",
  "status": "DISPUTED",
  "heldBalance": 15000,
  "dispute": {
    "id": 3,
    "status": "OPEN",
    "reason": "Goods arrived damaged",
    "slaDeadline": 1793864735
  }
}
POST/api/v1/escrow/orders/{ref}/dispute/resolveBEARER

Resolve 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

ParameterTypeRequiredDescription
tenantMerchantIdstringYesYour merchant ID
resolutionstringYes"RELEASE" or "REFUND"
notestringOptionalStored as the ledger note / refund reason
amountnumberOptionalPartial amount; default whole held balance
railstringOptionalRELEASE only; default sellerPayoutRail
destinationstringOptionalRELEASE only; default sellerPayoutDest

Request

Request Body
12345
{
  "tenantMerchantId": "your_merchant_id",
  "resolution": "REFUND",
  "note": "Seller agreed to refund"
}

Response

Resolved by refund (200)
1234567891011
{
  "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.

POST/api/v1/bank/payinBEARER

Bank Transfer (Payin)

Receive payments via bank transfer from customers. Generates temporary bank account details for the customer to transfer funds to.

Parameters

ParameterTypeRequiredDescription
externalIdstringYesYour unique reference for this transaction
amountnumberYesAmount to collect
currencystringYesCurrency code (e.g. "NGN")
callbackUrlstringYesURL to receive payment status callbacks
customerNamestringYesName of the paying customer
customerEmailstringYesEmail of the paying customer
accountNamestringOptionalLabel shown to the payer (defaults to "Payment")

Request

Request Body
123456789
{
  "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

Success (200)
12345678910111213
{
  "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.

GET/api/v1/read/payins/balanceBEARER

Payins (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
curl -X GET 'https://payments.mamlakapsp.com/api/v1/read/payins/balance' \
  -H 'Authorization: Bearer <token>'

Response

Success (200)
12345678910111213
{
  "merchantId": "your_merchant_id",
  "baseCurrency": "KES",
  "Balances": {
    "merchantId": "your_merchant_id",
    "baseCurrency": "KES",
    "kesBalance": 71,
    "xafBalance": 300,
    "usdBalance": 0,
    "ngnBalance": 0,
    "totalBalance": 135.5
  }
}
GET/api/v1/read/payouts/balanceBEARER

Payouts (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
curl -X GET 'https://payments.mamlakapsp.com/api/v1/read/payouts/balance' \
  -H 'Authorization: Bearer <token>'

Response

Success (200)
12345678910111213
{
  "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.

GET/api/v1/transaction?reference={externalId}PUBLIC

Transaction 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
curl -X GET 'https://payments.mamlakapsp.com/api/v1/transaction?reference={externalId}'

Response

Completed (200)
12345678910111213141516
{
  "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.

POST → your callbackUrl
123456789
{
  "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:

Header
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:

Verify (Node.js)
12345678910111213141516171819202122
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)
})