Quickstart
From zero to your first paid order in five minutes.
- Create your account in the dashboard and enter your business name. Customers see this name on the checkout.
- Get your API key — a live key is issued to you automatically the moment your account is created and shown once in the dashboard. Store it on your server; only a hash is kept on our side.
- Create a payment with
POST /payment, sending the amount in KES. - Redirect the customer to the
checkout_urlwe return. They pick M-Pesa, card or another rail and pay. - Get the webhook (or poll) and deliver the goods. Money lands in your balance, withdrawable to M-Pesa.
Authentication
Authorization: Bearer mbg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Every new account receives a live key automatically at signup, so you can start calling the API without any setup step. The key is displayed once in your dashboard on green, with a copy button, and is never shown again.
Test keys start with mbg_test_, live keys with mbg_live_. Only a SHA-256 hash is stored on our side. Generate extra keys, or revoke one, in the dashboard; a revoked key stops working instantly.
Two keys per mode
Every key comes as a pair, like other serious gateways:
- Secret key —
mbg_live_…ormbg_test_…. Keep it on your server. It is the only key that can create payments, refunds and withdrawals. - Publishable key —
mbg_pub_live_…ormbg_pub_test_…. Safe to ship inside a website or mobile app: it can only read payment status, currencies, payment methods and FX quotes. Anything that moves money answersThis endpoint needs your secret key.
Both are shown once, at creation, and hashed at rest. Your dashboard shows the prefix of each and can mint a fresh publishable key on demand.
Create a payment
curl -X POST https://moahboost.com/api/v1/gw/payment \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 250,
"reference": "INV-1042",
"description": "Order 1042",
"customer_name": "Jane Wanjiku",
"customer_phone": "254712345678"
}'
reference is your own idempotency key. Send the same reference twice and you get the same charge back instead of a duplicate.
Response
{
"ok": true,
"reference": "mbg_544ea7d0b30280118d",
"status": "pending",
"amount": 250,
"currency": "KES",
"fee_percent": 3,
"checkout_url": "https://moahboost.com/pay/mbg_544ea7d0b30280118d"
}
Redirect the customer to checkout_url to pay. Keep the returned reference, it is how you and we identify the charge.
Payment links
A payment link is a fixed amount with a hosted checkout behind it. Create one in the dashboard, open it in a new tab to check the branding, then put it anywhere: an invoice, a WhatsApp message, a button on your site, or a QR code on your counter.
<a href="https://moahboost.com/pay/mbg_544ea7d0b30280118d"
style="display:inline-block;padding:13px 24px;border-radius:10px;
background:#8c52ff;color:#fff;font:700 15px system-ui;text-decoration:none">
Pay with M-Pesa
</a>
Each link appears in your payments list with its own status, so you can see at a glance who has paid.
Your own payment method
By default your customers pay into your MoahBoost gateway balance and you withdraw from there. If you would rather collect straight into your own account, connect your own M-Pesa paybill, buy goods till, Airtel Money or bank account. The money then lands with you and never sits in our wallet.
Connect it in the dashboard
Open Your payment method on the dashboard and choose Add my payment details. You give the business name, an email for receipts, the phone on the account, the bank that should receive the money, and the account, paybill or till number. We register those details with our payment partner and keep the returned key encrypted on our side.
What changes at checkout
- The M-Pesa prompt is raised on your own shortcode, so the customer sees your business name.
- Settlement goes to your bank account, not to your MoahBoost balance, so nothing is credited to your withdrawable balance.
- Payments still show as paid on your dashboard and your webhook still receives payment.paid, with the fee recorded as 0 because we are not holding the money.
- Only one method is live at a time. Switching one off frees the slot for another.
Endpoints
All of these take your MoahBoost session (dashboard) rather than your API key, because they change where your money is paid.
| Endpoint | What it does |
|---|---|
| GET /api/v1/gw/methods/banks | Lists the banks you can settle to. |
| GET /api/v1/gw/methods | Lists the methods on your account with their status. |
| POST /api/v1/gw/methods | Connects a new method (creates your own business profile with the partner). |
| POST /api/v1/gw/methods/status | Switches a method on or off: {"id":"…","status":"active"} or "disabled". |
| POST /api/v1/gw/methods/remove | Removes a method from your account. |
Connect example
curl -X POST https://moahboost.com/api/v1/gw/methods \
-H "authorization: Bearer YOUR_DASHBOARD_TOKEN" \
-H "content-type: application/json" \
-d '{
"kind": "mpesa_paybill",
"business_name": "My Shop",
"email": "owner@myshop.co.ke",
"mobile": "254712345678",
"bank_id": "bank-uuid-from-methods-banks",
"account_number": "5001234"
}'
Payment methods
Returns every method currently available on the hosted checkout: M-Pesa in KES, card payments (Visa, Mastercard, Verve) in NGN, international card payments in USD, NGN bank transfer, plus mobile money in Ghana GHS, Tanzania TZS, Cameroon XAF, Ivory Coast XOF and Egypt EGP, and Malawi MWK, Sierra Leone SLL, DR Congo CDF, Zambia ZMW, Uganda UGX and Rwanda RWF. Each entry carries its public code (for example moah_mpesa or moah_card), currency, live rate, minimum and maximum. Send a method's public code as rail on a payment or a link to fix the checkout to that method; an older rail identifier is still accepted for compatibility.
[{ "code": "moah_mpesa", "label": "M-Pesa", "currency": "KES", "rate": 1, "min": 1, "max": 250000 },
{ "code": "moah_ghs", "label": "Ghana MoMo (MTN, AirtelTigo, Vodafone)", "currency": "GHS", "rate": 12.5, "min": 1, "max": 800 },
{ "code": "moah_card", "label": "Card (Visa, Mastercard, Verve)", "currency": "NGN", "rate": 10.415722, "min": 100, "max": 5000000 },
{ "code": "moah_ngn", "label": "Bank transfer (NGN)", "currency": "NGN", "rate": 10.415722, "min": 100, "max": 5000000 },
{ "code": "moah_card_usd", "label": "Card (USD, Visa / Mastercard)", "currency": "USD", "rate": 0.007694, "min": 1, "max": 5000 }]
You do not have to choose a rail when you create a payment. Send the customer to checkout_url and the hosted page shows every rail you have enabled, converts your KES amount, and settles back into your KES balance at the same figure. Fees apply to the KES amount, not the rail amount.
Choosing the method per payment
Leave the method open and the customer picks on your checkout, or fix it per payment by sending the method code as rail. A fixed method means the checkout shows only that option.
{ "amount": 1500, "reference": "INV-1042", "rail": "mpesa" }The same rail field works when you create a payment link from the console. Amounts are always in KES; the customer is charged the equivalent in that method's currency.
Code examples
One request creates the charge; the response carries the URL to send your customer to. Keep the key on the server.
PHP
$ch = curl_init("https://moahboost.com/api/v1/gw/payment");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_KEY", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode([
"amount" => 250,
"reference" => "INV-" . $order_id,
"description" => "Order #" . $order_id,
"customer_phone" => $phone
])
]);
$res = json_decode(curl_exec($ch), true);
header("Location: " . $res["checkout_url"]);
Node
const res = await fetch("https://moahboost.com/api/v1/gw/payment", {
method: "POST",
headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ amount: 250, reference: "INV-" + orderId, description: "Order #" + orderId })
});
const { checkout_url } = await res.json();
res.redirect(checkout_url);
Python
r = requests.post(
"https://moahboost.com/api/v1/gw/payment",
headers={"Authorization": "Bearer YOUR_KEY"},
json={"amount": 250, "reference": f"INV-{order_id}", "description": f"Order #{order_id}"},
timeout=30,
)
checkout_url = r.json()["checkout_url"]
Check a payment
curl "https://moahboost.com/api/v1/gw/payment?ref=mbg_544ea7d0b30280118d" \ -H "Authorization: Bearer YOUR_KEY"
{
"ok": true,
"payment": {
"reference": "mbg_544ea7d0b30280118d",
"merchant_ref": "INV-1042",
"amount": 250, "fee": 7.5, "net": 242.5,
"status": "paid", "rail": "moah_mpesa",
"paid_at": "2026-10-28T19:55:46Z"
}
}
Status values: pending, paid, failed, cancelled. Poll this endpoint, or rely on the hosted checkout page which confirms to the customer automatically.
Balance
Request a withdrawal
Webhooks
Set a webhook URL in the dashboard. Every time a payment is confirmed we POST a JSON event to it, signed so you can prove it came from us.
Headers
X-MB-Event: payment.paid X-MB-Signature: sha256=4d1a...c9e Content-Type: application/json User-Agent: MoahBoost-Webhooks/1
Body
{
"event": "payment.paid",
"created_at": "2026-10-28T20:31:05.118Z",
"data": {
"reference": "mbg_544ea7d0b30280118d",
"merchant_ref": "INV-1042",
"amount": 250, "fee": 7.5, "net": 242.5,
"status": "paid", "rail": "moah_mpesa",
"paid_at": "2026-10-28T20:31:04.902Z"
}
}
Verifying the signature
const crypto = require("crypto");
function valid(rawBody, header, secret) {
var expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
return header && header.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}
The secret is shown in your dashboard. Use the raw request body bytes, not a re-serialised object, or the signature will not match.
Refunds
A refund returns a paid payment to the customer and takes the net amount out of your available balance. The fee on the original payment is not returned.
{
"reference": "mbg_8f21c4d0a9b3",
"reason": "Customer asked for a refund"
}Response:
{ "ok": true, "reference": "mbg_8f21c4d0a9b3", "amount": 250, "debited": 242.5, "balance": 757.5 }- Only paid payments can be refunded, and only once. A second attempt returns "This payment was already refunded."
- The payment moves to status refunded and drops out of volume and fee totals. It stays in your history.
- If your available balance is smaller than the payment's net amount, the refund is refused and nothing changes.
- Your endpoint receives a payment.refunded event with the same signature check as Webhooks.
- Money movement back to the customer's phone or bank is handled by our team, so tell the customer the refund is approved, not that funds have already landed.
Test mode
Create a key in Test mode (mbg_test_… with its mbg_pub_test_… pair) and you can rehearse the entire integration without a shilling moving. Test payments are recorded and flagged as test, and they settle to zero: no balance, no pocket, no payout, and refunds on them debit nothing.
Create a test payment exactly as you would a live one:
curl -X POST https://moahboost.com/api/v1/gw/payment \
-H "Authorization: Bearer mbg_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"amount":100,"currency":"KES","merchant_ref":"order-42"}'
Then complete it and watch your webhook fire:
curl -X POST https://moahboost.com/api/v1/gw/test/pay \
-H "Authorization: Bearer mbg_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"reference":"mbg_1a2b3c4d5e"}'
The answer is {"ok":true,"status":"paid","test":true}, and we POST payment.paid to your webhook with is_test: true in the body, signed with the same X-MB-Signature you already verify.
/test/pay, and test rows stay out of balances, payouts and reports. Swap in the live key when you go live.Errors
| Status | Meaning |
|---|---|
| 401 | Missing or revoked API key. |
| 400 | Validation failed, for example amount below 1 or a bad phone number. The error field explains what to fix. |
| 404 | Payment not found, or the reference belongs to another merchant. |
| 403 | Admin-only endpoint. |
Going live checklist
- Business name and checkout colour set in the dashboard.
- Webhook URL saved and the test event shows delivered.
- Signature verified in your handler with the signing secret.
- You listen for
payment.paid, and treatreferenceas the idempotency key. - Live key on the server only, never in front-end code.
- Withdrawal phone number confirmed, and a KES 50 payout tested.