Payment gateway API

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.

Quick start

Your first Mobile Money payment in three steps.

  1. 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. 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. 3

    Listen for the webhook

    When the customer approves, PexiPay posts the final status to your webhookUrl. Fulfil the order on CAPTURED.

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"
    }
  }'
Response · 200
{
  "id": "…",
  "pexiTransactionId": "PEXI…",
  "reference": "order-1234",
  "amount": 100,
  "currency": "KES",
  "status": "PENDING",
  "createdAt": "2026-11-15T09:30:00.000Z",
  "customer": { "firstName": "John", "lastName": "Doe", … }
}
API at a glance

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.

Keys are for server-to-server calls only. Never expose them in browser or mobile app code.
EndpointWhat it does
POST/api/v1/apm/paymentsCollect a mobile money payment (debit a customer)
POST/api/v1/apm/payoutsSend a payout (credit a beneficiary)
GET/api/v1/apm/transactions/{id}Get one transaction and its latest status
GET/api/v1/apm/transactionsList transactions, filtered by status and date
POST/api/v1/paymentsTake a card payment, with 3D Secure
What you can build

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

4
  • KenyaKES
  • TanzaniaTZS
  • UgandaUGX
  • RwandaRWF

West Africa

4
  • GhanaGHS
  • NigeriaNGN
  • SenegalXOF
  • Sierra LeoneSLE

Central & Southern Africa

3
  • CameroonXAF
  • ZambiaZMW
  • South AfricaZAR

North Africa

1
  • EgyptEGP
Webhooks

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
Webhook payload · POST to your URL
{
  "txId": "…",
  "reference": "order-1234",
  "status": "CAPTURED",
  "amount": 100,
  "currency": "KES",
  "gateway": { … }
}
Handling it (Node.js · Express)
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
});
Before you go live

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.

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