mpesa-mcp

Send airtime to a phone (Safaricom, Airtel, MTN, Vodafone and others) in a currency. Use only when the user has explicitly approved this exact top-up. MOVES MONEY: in live mode it needs confirm_send=true and refuses amounts above the per-transaction cap (MPESA_MAX_AMOUNT_KES, default KES 100,000); the sandbox is never restricted. Returns the Africa's Talking response or a refusal saying what is missing.

Returns neutral guidance on choosing a model for these tools; no model is recommended and no benchmark or pricing claims are made. Use when someone asks which model to pair with this server. Takes no arguments. Returns a null recommendation, guidance, a deprecation note and the tool count (23). Read-only.

Query the balance of your business M-PESA account (shortcode or till). Use when someone asks how much is in the account. identifier_type 4 (default) means an organisation shortcode. Returns the Daraja response, with the balance delivered on your result URL. Read-only.

Start a B2B Express Checkout: a USSD push to another merchant's till so they approve a payment from your account. Use only when the user has explicitly approved this exact payment. MOVES MONEY: in live mode it needs confirm_send=true (set only after the user approves this exact payment) and refuses amounts above the per-transaction cap (MPESA_MAX_AMOUNT_KES, default KES 100,000); the sandbox is never restricted. Returns success, the Daraja response and the sandbox flag, or a refusal saying what is missing; the final result arrives asynchronously on your result URL.

Send money from your business shortcode to a customer's phone (Business to Customer). Use only when the user has explicitly approved this exact payment. MOVES MONEY: in live mode it needs confirm_send=true (set only after the user approves this exact payment) and refuses amounts above the per-transaction cap (MPESA_MAX_AMOUNT_KES, default KES 100,000); the sandbox is never restricted. Returns success, the Daraja response and the sandbox flag, or a refusal saying what is missing; the final result arrives asynchronously on your result URL.

Cancel an outstanding Bill Manager invoice by its external reference. Use when an invoice was raised in error or is no longer due. Returns the Daraja response. Cancels the invoice, so have the user approve it first; the customer will no longer be able to pay it, and a cancelled invoice cannot be restored through this tool.

Create a Bill Manager invoice: the customer receives an SMS with the amount and a way to pay. Use when billing a customer. Sends an SMS to the customer's phone in live mode, so have the user approve the customer, amount and due date first. Returns the Daraja response for the invoice.

Enrol your business in M-PESA Bill Manager, a one-time setup for sending invoices with payment links. Use before creating invoices. Takes the notification email and an optional logo and callback URL. Returns the Daraja response. Changes your Bill Manager registration.

Pay from your business shortcode to a till (Buy Goods) number. Use only when the user has explicitly approved this exact payment. MOVES MONEY: in live mode it needs confirm_send=true (set only after the user approves this exact payment) and refuses amounts above the per-transaction cap (MPESA_MAX_AMOUNT_KES, default KES 100,000); the sandbox is never restricted. Returns success, the Daraja response and the sandbox flag, or a refusal saying what is missing; the final result arrives asynchronously on your result URL.

Pay from your business shortcode directly to another paybill number (B2B PayBill). Use only when the user has explicitly approved this exact payment. MOVES MONEY: in live mode it needs confirm_send=true (set only after the user approves this exact payment) and refuses amounts above the per-transaction cap (MPESA_MAX_AMOUNT_KES, default KES 100,000); the sandbox is never restricted. Returns success, the Daraja response and the sandbox flag, or a refusal saying what is missing; the final result arrives asynchronously on your result URL.

Pay from your business shortcode to a Pochi la Biashara micro-business wallet by phone number. Use only when the user has explicitly approved this exact payment. MOVES MONEY: in live mode it needs confirm_send=true (set only after the user approves this exact payment) and refuses amounts above the per-transaction cap (MPESA_MAX_AMOUNT_KES, default KES 100,000); the sandbox is never restricted. Returns success, the Daraja response and the sandbox flag, or a refusal saying what is missing; the final result arrives asynchronously on your result URL.

Generate a dynamic M-PESA QR code for a specific amount and reference. Use when a customer should pay by scanning. Returns qr_base64 (a PNG), qr_data_url usable in an HTML img tag, and the merchant, amount and reference. The QR encodes the amount you pass, so check it before showing it to a customer. Read-only; it changes nothing.

Verify a Safaricom number: registration date, SIM age, last swap date and a hashed IMSI, with risk indicators (recently swapped; SIM age below 30 as returned by the API). Use for identity or fraud checks before onboarding or paying. This queries personal data about a subscriber: do so only with a lawful basis and any consent required under the Data Protection Act 2019. Returns those fields and the risk indicators. Read-only.

Pull C2B transactions in a date range for reconciliation. Use when reconciling payments received. start_date and end_date use YYYY-MM-DD HH:MM:SS; offset pages through results from 0. Returns count, the transactions, the response code and message. Read-only.

Validate a shortcode and return its registered organisation name and tariff type. Use before paying a paybill or till to confirm who will actually receive the money, which helps catch a mistyped number or a lookalike business name. Returns the Daraja organisation details (registered name and tariff type). Read-only; it changes nothing.

Create an M-PESA Ratiba standing order: automated recurring payments collected from a customer's phone. Use when a customer wants to pay a regular amount. The customer must approve on their handset; confirm the amount, dates and customer with the user first, since this creates a recurring commitment. frequency 1 one-off, 2 daily, 3 weekly, 4 monthly (default), 5 bi-monthly, 6 quarterly, 7 half-year, 8 annually. Returns success, standing_order_id, response code, message and frequency_label.

Reverse an erroneous M-PESA transaction by its receipt number. Use only when the user has explicitly approved reversing this exact transaction. MOVES MONEY: in live mode it needs confirm_send=true (set only after the user approves this exact payment) and refuses amounts above the per-transaction cap (MPESA_MAX_AMOUNT_KES, default KES 100,000); the sandbox is never restricted. Returns success, the Daraja response and the sandbox flag, or a refusal saying what is missing; the final result arrives asynchronously on your result URL.

Check whether a phone number's SIM was recently swapped, a fraud signal before sending money. Use before a disbursement to an unfamiliar or high-value recipient. This queries personal data about a subscriber: do so only with a lawful basis and any consent required under the Data Protection Act 2019. Returns phone, swap_detected, last_swap_date, a risk level (HIGH if swapped) and a recommendation. Read-only.

Send an M-PESA payment prompt (STK Push) to a customer's phone for them to approve with their PIN. Use when a customer is to pay your business shortcode. The customer must approve on the handset: nothing is taken without their PIN. Returns success, checkout_request_id, merchant_request_id, response code, message and the sandbox flag; success means the prompt was SENT, not that the customer paid, so poll mpesa_stk_query. In live mode it prompts a real phone.

Check the status of an STK Push using its checkout_request_id. Use 10 to 30 seconds after mpesa_stk_push to learn whether the customer paid, cancelled or the request is still processing. Returns the Daraja status for that request with the sandbox flag. Read-only.

Remit tax from your M-PESA business account to the Kenya Revenue Authority. Use only when the user has explicitly approved this exact remittance. MOVES MONEY: in live mode it needs confirm_send=true (set only after the user approves this exact payment) and refuses amounts above the per-transaction cap (MPESA_MAX_AMOUNT_KES, default KES 100,000); the sandbox is never restricted. Returns success, the Daraja response and the sandbox flag, or a refusal saying what is missing; the final result arrives asynchronously on your result URL.

Query the status of any M-PESA transaction by its receipt number. Use when you need to confirm what happened to a payment, or to reconcile one against your records after an STK Push, B2C or reversal. Returns the Daraja response for that transaction, whose full details can arrive asynchronously on your result URL. Read-only; it changes nothing.

Send an SMS to up to 1,000 recipients through Africa's Talking. Use only when the user has explicitly approved this exact message and recipient list. SENDS TO REAL PEOPLE: in live mode it needs confirm_send=true and refuses more recipients than the per-call cap (MPESA_MAX_SMS_RECIPIENTS, default 50); the sandbox is never restricted. Returns the number sent and failed, any failures, a summary and per-recipient status, cost and id, or a refusal saying what is missing. Sending cannot be undone.