Malipo, Payments API

Take M-Pesa, Airtel Money and card payments in your apps through one API

Your server asks Malipo for a payment. The customer approves the prompt on their phone, or pays by card on Equity's Jenga page. Malipo talks to Safaricom, Airtel and Jenga, books the money in a ledger and tells your server how it went by a signed webhook.

  • M-Pesa, Airtel Money and card
  • Hosted checkout pages
  • Refunds and wallet payouts
  • Test mode from the first day

Talk to us about Malipo See how it works

Request

POST /api/v1/payments
Authorization: Bearer mlp_live_…
Idempotency-Key: order-10247
Content-Type: application/json

{
  "method": "MPESA",
  "amount": 150000,
  "currency": "KES",
  "phone": "0712345678",
  "reference": "ORDER-10247",
  "description": "2 x Pilau"
}

Response

{
  "id": "2610191649…",
  "object": "payment",
  "livemode": true,
  "status": "PROCESSING",
  "method": "MPESA",
  "amount": 150000,
  "currency": "KES",
  "reference": "ORDER-10247",
  "nextAction": {
    "type": "APPROVE_ON_PHONE",
    "message": "Check your phone and enter your M-Pesa PIN to pay"
  }
}
Ask for KES 1,500 by M-Pesa: the answer says the prompt is on the customer's phone.

Who it is for

  • Developers

    Hold one API key and one webhook secret instead of Daraja, Airtel and Jenga credentials, and test every outcome on a simulator.

  • Businesses selling online

    Customers pay by an M-Pesa or Airtel Money prompt, or by card, on a checkout page with your name, logo and colour.

  • Platforms that pay people

    Send riders and suppliers their pay from your balance to M-Pesa and Airtel Money wallets, up to a daily limit.

  • Finance teams

    See every payment, refund and payout in one dashboard and one ledger, and find a payment by your reference, its receipt or a phone number.

How it works

  1. Sign your app up

    Sign in to the dashboard and sign up an app. It gets a first test key and can take test payments at once.

  2. Test every outcome

    Run each flow through the simulator, failures and repeated requests included, then through the providers' own sandboxes.

  3. Go live

    Ask to go live from the dashboard. Once FoxShard approves, it points your live routes at your provider accounts, and an owner makes a live key.

  4. Take payments

    Your server asks for a payment or opens a checkout page. The customer approves the prompt on their phone or pays on the card page.

  5. Hear what happened

    Malipo confirms the result with the provider, books it in the ledger and sends your server a signed webhook.

What it does

  • One API for three providers

    A payment is the same request whichever provider carries it: method is MPESA, AIRTEL_MONEY or CARD. Your app holds no Daraja, Airtel or Jenga credential.

  • Hosted checkout pages

    Open a page for an amount and send the customer to its url. It shows your name, logo and colour and the ways to pay, and you hear checkout.completed once it is paid.

  • Refunds and payouts

    Refunds go back the way the money came: whole for M-Pesa and Airtel Money, whole or in part for cards. Payouts send money from your balance to M-Pesa and Airtel Money wallets.

  • Signed webhooks

    Each event is signed with HMAC-SHA256 over a timestamp and the body. A failed delivery is tried up to 10 times, and missed events can be read from GET /api/v1/events.

  • A ledger that adds up

    Every payment, refund and payout is booked in an append-only ledger. Refunds and payouts take the balance when asked for, so two at once cannot spend the same money.

  • Test mode with a simulator

    A new app takes test payments at once. Phones ending 1032, 1037, 0001 or 2001 cancel, expire or fail on purpose, so you can test each outcome.

  • Safe to send twice

    Requests that move money carry an Idempotency-Key. Send one again after a timeout and you get the first payment back, never a second charge.

  • Callbacks checked with the provider

    Malipo takes no callback on trust: it asks the provider how the payment stands. Payments nobody has heard of are asked about until they end.

Questions

Does our application hold any provider credentials?

No. It holds one API key and one webhook secret. The Daraja, Airtel and Jenga credentials stay in Malipo, sealed with AES-256-GCM and never shown again once saved. API keys are stored as hashes, so a lost key is revoked and replaced, not recovered.

Can we test without moving real money?

Yes. A test key only sees and makes test objects, and test payments go through a simulator that answers after 4 seconds. Phones ending 1032 cancel, 1037 expire, 0001 fail with insufficient_funds and 2001 with wrong_pin. A test card payment gets a page with Approve and Decline.

Can we refund part of a payment?

For a card payment, yes, up to what is left of it. M-Pesa and Airtel Money give back all of a payment or nothing, so leave amount out. The refund is taken from your app's balance when you ask, and goes back to it if the refund fails.

Does our app ever see a card number?

No, and neither does Malipo. The customer types their card on Equity's Jenga page: your server sends their browser to nextAction.url or to a checkout page. Coming back to your returnUrl says nothing about how it went; the payment's status and its webhook do.

Can customers pay in US dollars?

By card, where the Jenga merchant account takes the currency: KES and USD by default. Mobile money is KES only, in whole shillings. A checkout page in USD offers cards alone.

Who on our team can move money?

Owners change the app, its team and its keys, refund and pay out live money, and ask to go live. Developers make test keys and webhook endpoints, and refund and pay out test money. Viewers look. Everyone signs in with FoxShard Identity.

Talk to us about Malipo

Tell us what you are building, and we will set you up with keys to try it.

Send us a message