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

*Web page: https://foxshard.com/solutions/malipo. Updated 2026-11-17*

*Payments API, by FoxShard*

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

## 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.

## 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.

## 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.

## A request to the API

Ask for KES 1,500 by M-Pesa: the answer says the prompt is on the customer's phone.

```http
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"
}
```

```json
{
  "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"
  }
}
```

## 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

Use the form at https://foxshard.com/contact?solution=malipo. Email: support@foxshard.com.
