canonical: https://jentic.com/apis/safaricom.co.ke/safaricom

# Safaricom M-Pesa Daraja API

Jentic publishes the only available OpenAPI specification for Safaricom M-Pesa Daraja API, keeping it validated and agent-ready. The Safaricom M-Pesa Daraja API connects a business to M-Pesa, Kenya's mobile money platform, so it can collect payments from customers and send money out. M-Pesa Express (STK Push) prompts a customer's phone to approve a payment, C2B registers the URLs that validate and confirm paybill and till payments, and B2C and B2B send funds to customers and other businesses. Supporting operations query transaction status and account balance and reverse a transaction, with results delivered asynchronously to callback URLs.

## For AI agents

Prompt a customer's phone for an M-Pesa payment with STK Push, check its status, send B2C and B2B payments, query balances and transaction status, and reverse transactions.

## Scope

Does not process card payments, issue invoices, or handle mobile money outside Safaricom M-Pesa. Use for M-Pesa collections, payouts, and transaction queries only.

## Capabilities

- Prompt a customer to pay with M-Pesa Express (STK Push) using CustomerPayBillOnline or CustomerBuyGoodsOnline
- Check whether an STK Push payment completed using its CheckoutRequestID
- Register C2B ConfirmationURL and ValidationURL endpoints for a paybill or till ShortCode
- Send B2C payouts to customer phones with SalaryPayment, BusinessPayment, or PromotionPayment
- Pay another business shortcode with a B2B payment request
- Query the status of a transaction by TransactionID and check the organisation's account balance
- Reverse a completed M-Pesa transaction and receive the result at a ResultURL

## Use cases

### Checkout agent that collects M-Pesa payments through Jentic

A Kenyan online shop wants its assistant to take payment inside the chat. Through Jentic the agent searches for 'request an M-Pesa payment', receives the Daraja operation with its input schema, and calls POST `/mpesa/stkpush/v1/processrequest` with BusinessShortCode, Password, Timestamp, TransactionType, Amount, PartyA, PartyB, PhoneNumber, CallBackURL, AccountReference, and TransactionDesc. It then calls POST `/mpesa/stkpushquery/v1/query` with the CheckoutRequestID to confirm the customer approved.

Example prompt: Call POST `/mpesa/stkpush/v1/processrequest` with BusinessShortCode '174379', TransactionType 'CustomerPayBillOnline', Amount '500', PartyA and PhoneNumber '254712345678', PartyB '174379', AccountReference 'INV001', TransactionDesc 'Payment', and a CallBackURL, then query POST `/mpesa/stkpushquery/v1/query` with the returned CheckoutRequestID

### Paybill and till payment confirmations

Businesses that receive paybill or till payments want each one confirmed in their system. POST `/mpesa/c2b/v1/registerurl` registers a ConfirmationURL and ValidationURL for a ShortCode with a ResponseType, after which M-Pesa calls those URLs as customers pay. In the sandbox, POST `/mpesa/c2b/v1/simulate` sends a test payment with an Msisdn and BillRefNumber to check the flow.

Example prompt: Call POST `/mpesa/c2b/v1/registerurl` with ShortCode '600000', ResponseType 'Completed', and the ConfirmationURL and ValidationURL, then call POST `/mpesa/c2b/v1/simulate` in the sandbox with Msisdn '254708374149' and BillRefNumber 'TEST01'

### Payouts to customers and suppliers

Platforms paying out winnings, refunds, or wages use B2C. POST `/mpesa/b2c/v1/paymentrequest` takes InitiatorName, SecurityCredential, a CommandID such as SalaryPayment or BusinessPayment, Amount, PartyA, PartyB, Remarks, QueueTimeOutURL, and ResultURL. Supplier payments go through POST `/mpesa/b2b/v1/paymentrequest`, which also needs sender and receiver identifier types and an AccountReference.

Example prompt: Call POST `/mpesa/b2c/v1/paymentrequest` with CommandID 'BusinessPayment', Amount '1000', PartyA '600000', PartyB '254712345678', Remarks 'Refund', and the InitiatorName, SecurityCredential, QueueTimeOutURL, and ResultURL

### Reconciliation and reversals

Finance teams need to confirm what happened to a payment and undo mistakes. POST `/mpesa/transactionstatus/v1/query` looks up a TransactionID, POST `/mpesa/accountbalance/v1/query` reports the organisation's balance, and POST `/mpesa/reversal/v1/request` reverses a transaction to a ReceiverParty. All three return results asynchronously to the ResultURL provided.

Example prompt: Call POST `/mpesa/transactionstatus/v1/query` for TransactionID 'OEI2AK4Q16' with the initiator details and ResultURL, and if it was sent in error call POST `/mpesa/reversal/v1/request` for the same TransactionID and Amount

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/oauth/v1/generate` | Generate an OAuth access token |
| POST | `/mpesa/stkpush/v1/processrequest` | Initiate an STK Push payment |
| POST | `/mpesa/stkpushquery/v1/query` | Query STK Push status |
| POST | `/mpesa/c2b/v1/registerurl` | Register C2B URLs |
| POST | `/mpesa/b2c/v1/paymentrequest` | Initiate a B2C payment |
| POST | `/mpesa/transactionstatus/v1/query` | Query transaction status |
| POST | `/mpesa/reversal/v1/request` | Reverse a transaction |

## Key resources

- **OAuth** — Access token generation from the consumer key and secret
- **M-Pesa Express** — STK Push payment prompts and status queries
- **C2B** — Confirmation and validation URL registration and sandbox payment simulation
- **B2C and B2B** — Payments from the business to customer phones and to other business shortcodes
- **Account operations** — Transaction status, account balance, and transaction reversal, with asynchronous results

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 64 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 71 / 100
  - AI-Readiness & Agent Experience: 52 / 100
  - Agent Usability: 94 / 100
  - Security: 35 / 100
  - AI Discoverability: 80 / 100
- **View full report:** https://jentic.com/apis/safaricom.co.ke/safaricom/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Daraja by hand means exchanging your consumer key and secret over basic auth for a short-lived bearer token, building the base64 Password from shortcode, passkey, and timestamp, and hosting callback URLs for asynchronous results. Through Jentic you install once, import M-Pesa Daraja from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Daraja carries the shortcode, phone number, and amount inside the request body, so rules bound which operations your agent may call, not which shortcode or phone it pays. You choose the operations it may call, so payouts and reversals like B2C payments or transaction reversal are not included unless you add them.
- **Credential handling:** Your Daraja consumer key and secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'request an M-Pesa payment' or 'check M-Pesa transaction status', and Jentic returns the matching Daraja operation with its input schema so the agent calls the right endpoint without reading the portal docs.

## Related APIs

- **Flutterwave Payments API** — Pan-African payments including cards, bank transfers, and mobile money
- **Paystack API** — Payments for African businesses with cards, transfers, and mobile money
- **MTN Developer API** — MTN developer APIs including mobile money
- **Twilio - API** — SMS and voice messaging

## FAQ

### Why is there no official OpenAPI spec for Safaricom M-Pesa Daraja API?

Safaricom does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Safaricom M-Pesa Daraja API via structured tooling. It is validated against the live API and kept up to date. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### What authentication does the M-Pesa Daraja API use?

The spec declares two schemes. GET `/oauth/v1/generate` uses HTTP basic auth (basicAuth) with your Consumer Key as username and Consumer Secret as password and returns an access token. The payment and query operations use a bearer token (bearerAuth) sent as `Authorization: Bearer` with that access token. B2C, B2B, status, balance, and reversal requests also carry an encrypted SecurityCredential in the body. Through Jentic these credentials are held by your own Jentic One instance.

### Can I test M-Pesa payments without moving real money?

Yes. The spec lists a separate sandbox server alongside the production server, both on safaricom.co.ke. In the sandbox, POST `/mpesa/c2b/v1/simulate` simulates a C2B payment with ShortCode, CommandID, Amount, Msisdn, and BillRefNumber.

### What are the rate limits for the M-Pesa Daraja API?

The OpenAPI spec does not specify rate limits. Check the Safaricom developer portal at https://developer.safaricom.co.ke/ for current limits on your app.

### How do I request an M-Pesa payment through Jentic?

Search Jentic for 'request an M-Pesa payment', load POST `/mpesa/stkpush/v1/processrequest`, and execute it with BusinessShortCode, the base64 Password, Timestamp, TransactionType, Amount, PartyA, PartyB, PhoneNumber, CallBackURL, AccountReference, and TransactionDesc. Then call POST `/mpesa/stkpushquery/v1/query` with the CheckoutRequestID to check the result.

### Is there an M-Pesa MCP server?

You don't need an MCP server to give your agent M-Pesa Daraja. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent finds the STK Push, payout, and query operations it needs on demand, without loading extra tool definitions into its context.

### Can I limit what my agent is allowed to do with the M-Pesa Daraja API?

Yes. For a checkout assistant, write a rule that allows only POST `/mpesa/stkpush/v1/processrequest` and POST `/mpesa/stkpushquery/v1/query.` The agent can ask customers to pay and check the result but cannot send B2C or B2B payouts or reverse transactions, and each call it makes is logged.
