One API for cards and mobile money.
Collect payments, send payouts and track every transaction through a single REST API, with webhooks that tell you the moment a payment completes.
Your first Mobile Money payment in three steps.
- 1
Get your API keys
Once your business is onboarded, create a key pair in the merchant portal. The secret is shown once, so store it safely.
- 2
Create a collection
POST the amount, currency and customer. PexiPay sends an approval prompt to the customer's phone and returns the transaction as
PENDING. - 3
Listen for the webhook
When the customer approves, PexiPay posts the final status to your
webhookUrl. Fulfil the order onCAPTURED.
curl -X POST https://gateway.pexipay.com/api/v1/apm/payments \
-H "Content-Type: application/json" \
-H "x-api-key: $PEXIPAY_API_KEY" \
-H "x-api-secret: $PEXIPAY_API_SECRET" \
-d '{
"amount": 100,
"currency": "KES",
"reference": "order-1234",
"description": "Order #1234",
"webhookUrl": "https://your-server.com/pexipay/webhook",
"customer": {
"firstName": "John",
"lastName": "Doe",
"email": "john@example.com",
"phoneCode": "254",
"phone": "712345678"
}
}'{
"id": "…",
"pexiTransactionId": "PEXI…",
"reference": "order-1234",
"amount": 100,
"currency": "KES",
"status": "PENDING",
"createdAt": "2026-11-15T09:30:00.000Z",
"customer": { "firstName": "John", "lastName": "Doe", … }
}Simple REST. JSON in, JSON out.
Base URL
https://gateway.pexipay.com
Authentication
Send your key pair as two headers on every request:
x-api-key: pk_...
x-api-secret: sk_...A missing or wrong pair returns 401 Unauthorized.
| Endpoint | What it does |
|---|---|
| POST/api/v1/apm/payments | Collect a mobile money payment (debit a customer) |
| POST/api/v1/apm/payouts | Send a payout (credit a beneficiary) |
| GET/api/v1/apm/transactions/{id} | Get one transaction and its latest status |
| GET/api/v1/apm/transactions | List transactions, filtered by status and date |
| POST/api/v1/payments | Take a card payment, with 3D Secure |
Pay-ins, payouts and cards behind one integration.
Mobile money collections
Debit customers through M-PESA and other mobile money networks. The network is detected from the phone number and currency, so you don't pass a provider for most markets.
Payouts
Send money to mobile wallets with the same request shape you use for collections. Pass the destination country as an ISO code.
Card payments
Accept Visa and Mastercard with 3D Secure. Choose AUTO (3D Secure first, then 2D), always-3D or 2D processing per payment.
Hosted checkout
In South Africa, redirect customers to a hosted page that offers cards, Instant EFT, Capitec Pay, wallets and more, with one integration.
12
Mobile money markets in the API today
Collect and pay out in local currency across 4 regions. The network is detected from the phone number and currency, so one request shape works everywhere.
Available networks and currencies depend on your merchant agreement.
East Africa
4KenyaKES
TanzaniaTZS
UgandaUGX
RwandaRWF
West Africa
4GhanaGHS
NigeriaNGN
SenegalXOF
Sierra LeoneSLE
Central & Southern Africa
3CameroonXAF
ZambiaZMW
South AfricaZAR
North Africa
1EgyptEGP
Know the moment money moves.
PexiPay posts to your webhook URL on every status change. Set it per request with webhookUrl, or once for your account in the merchant portal.
- PENDINGCreated and waiting for the customer or network
- CAPTUREDSuccessful. Fulfil the order
- FAILEDDeclined or failed
- CANCELLEDCustomer cancelled a hosted checkout
{
"txId": "…",
"reference": "order-1234",
"status": "CAPTURED",
"amount": 100,
"currency": "KES",
"gateway": { … }
}app.post("/pexipay/webhook", express.json(), async (req, res) => {
const { txId, reference, status } = req.body;
if (status === "CAPTURED") {
await markOrderPaid(reference, txId);
} else if (status === "FAILED" || status === "CANCELLED") {
await markOrderFailed(reference, txId);
}
res.sendStatus(200); // acknowledge quickly
});Six things that make for a smooth integration.
Everything is asynchronous
The create response reflects the state at creation, almost always PENDING. Use the webhook, or poll the transaction, for the final result.
reference is your idempotency key
Sending the same reference again returns the existing transaction. To retry after FAILED or CANCELLED, use a new reference.
Phone numbers without prefixes
Send phone as digits only, with no + and no leading 0 (712345678), and the dial code separately in phoneCode ("254").
Match success on CAPTURED
CAPTURED is the success status. Older integrations may see SUCCESS, which is kept only as a legacy alias.
Pass your customer's IP for cards
Send the cardholder's IP address in ipAddress on card payments. It is used for fraud checks and 3D Secure risk scoring.
Keep keys on your server
API keys identify your business server to server. Never put them in a mobile app, browser code or a public repository.
Everything you need to ship.
API reference
Every endpoint, field and response, with a live test console.
Open the referenceMerchant portal
Create and rotate API keys, set your webhook URL and view transactions.
Sign inPostman collection
Ready-made requests for every market, with sample bodies and responses.
Request itTalk to an engineer
Questions about your integration, markets or going live? We'll help.
Contact usReady to unify how your business gets paid?
Tell us about your markets and payment flows. We'll show you how PexiPay brings cards, mobile money and settlement together.