IInstaPayv1 Production Checking service…
/
Base URLhttps://moahboost.comAll paths below start with /api/v1/gw · amounts in KES

Quickstart

From zero to your first paid order in five minutes.

  1. Create your account in the dashboard and enter your business name. Customers see this name on the checkout.
  2. 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.
  3. Create a payment with POST /payment, sending the amount in KES.
  4. Redirect the customer to the checkout_url we return. They pick M-Pesa, card or another rail and pay.
  5. Get the webhook (or poll) and deliver the goods. Money lands in your balance, withdrawable to M-Pesa.
No code at all? Make a payment link in the dashboard and share the URL.

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_… or mbg_test_…. Keep it on your server. It is the only key that can create payments, refunds and withdrawals.
  • Publishable key — mbg_pub_live_… or mbg_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 answers This 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.

Lost a key before copying it? Just generate a new one. Old keys keep working until you revoke them, so rotate after your new key is deployed.

Create a payment

POST/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.

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.

EndpointWhat it does
GET /api/v1/gw/methods/banksLists the banks you can settle to.
GET /api/v1/gw/methodsLists the methods on your account with their status.
POST /api/v1/gw/methodsConnects a new method (creates your own business profile with the partner).
POST /api/v1/gw/methods/statusSwitches a method on or off: {"id":"…","status":"active"} or "disabled".
POST /api/v1/gw/methods/removeRemoves 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"
  }'
Safety: the partner key we get back is stored encrypted and is never returned by any endpoint. Removing a method stops new prompts from your shortcode; it does not reverse payments already made.

Payment methods

GET/rails

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.

Rail availability follows the platform switches. Disabled rails disappear from the checkout automatically, so you never have to track which country is live.

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.

POST /api/v1/gw/payment
{ "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

GET/payment?ref=mbg_...
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.

Deliveries are retried up to 3 times with backoff when your endpoint does not answer 2xx within 8 seconds. Deliveries and failures are recorded against your account.

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.

POST https://moahboost.com/api/v1/gw/refund
{
  "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 and live never mix. A test key cannot complete a live payment, a live key cannot use /test/pay, and test rows stay out of balances, payouts and reports. Swap in the live key when you go live.

Errors

StatusMeaning
401Missing or revoked API key.
400Validation failed, for example amount below 1 or a bad phone number. The error field explains what to fix.
404Payment not found, or the reference belongs to another merchant.
403Admin-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 treat reference as the idempotency key.
  • Live key on the server only, never in front-end code.
  • Withdrawal phone number confirmed, and a KES 50 payout tested.

Rules

InstaPay · API v1 · production environmentDashboard · Overview · Test checkout