How to Integrate M-PESA with an Ecommerce Website in Kenya

Adding M-PESA to an ecommerce website means connecting checkout to a payment service and then matching the provider’s confirmed transaction to the correct order. A payment prompt is only a request. Do not dispatch an order until your system has verified the final payment result.

The right integration depends on how the store is built, which M-PESA business account it uses, and whether the checkout should send a payment prompt or accept another customer-to-business flow. Before choosing a developer or provider, map the order and payment steps you need.

Choose the payment flow before choosing the integration

An online payment flow typically has four parts: checkout collects an order reference and payment details; the payment provider requests or receives payment; the provider reports a result; and the store updates the order after verifying that result.

These are not interchangeable setups. A direct integration to a custom website may require development, hosting, security, monitoring, and provider approval. A hosted platform may reduce custom code but still has account, transaction, and operating costs.

Safaricom’s Daraja developer portal documents its APIs and development onboarding. Its current requirements and supported products are the source of truth; do not assume a sandbox application can immediately process live customer payments.

Map the order lifecycle

Write down what should happen from checkout through fulfilment before building anything:

1. Create an order with a unique, hard-to-guess reference.
2. Show the customer the amount, currency, order summary, and payment action.
3. Create a payment attempt linked to that order.
4. Receive the result through a trusted server-to-server callback or provider status check.
5. Match the provider transaction reference, amount, currency, business account, and order reference.
6. Record the verified result once, then update the order according to its own state.
7. Reconcile provider statements against store records on a regular schedule.

Design for delayed callbacks, retries, duplicate notifications, customer cancellation, insufficient funds, a wrong phone number, and provider downtime. A callback may arrive after the customer closes the browser. The server must be able to update the order without relying on a success message shown only in the customer’s browser.

Use an idempotent update: receiving the same provider event twice should not create two payments, fulfill an order twice, or send duplicate confirmation messages. Keep a record of the provider event and the action taken so support staff can investigate a mismatch.

Test payment verification, not just the prompt

A successful-looking phone prompt does not prove payment. The customer may cancel it, enter the wrong PIN, have insufficient funds, or lose connectivity. The checkout page may also time out even though the provider later confirms payment.

Use distinct states such as pending, confirmed, failed, cancelled, and requiring review. Confirm fulfilment only from a verified provider result. If the customer shares a screenshot or SMS, use it as a clue to investigate, not as the only authorization to dispatch goods.

Before going live, test at least:

• A successful payment for the exact order amount.
• A customer cancellation and an unsuccessful attempt.
• A delayed or repeated callback.
• A callback with a mismatched amount or order reference.
• A customer who retries after the first attempt is still pending.
• A refund, reversal request, and the accounting record for each outcome.
• A provider outage and a manual reconciliation procedure.

Keep credentials and callback endpoints on the server. Do not place consumer secrets, passkeys, API credentials, or customer payment data in browser code, analytics events, error messages, or support screenshots. Use the provider’s current production enrollment and security instructions.

Understand total cost

Do not compare integrations by a single “setup fee.” Ask for a written schedule covering:

• Developer or platform setup and later change requests.
• Hosting, monitoring, security maintenance, and support.
• Provider transaction charges, settlement fees, or other account charges.
• Refund, reversal, and dispute handling.
• Costs for failed or repeated payment attempts, if any.
• Reconciliation work and payment support.
• Any minimum volumes, contract terms, or settlement conditions.

Provider charges can change and may depend on the account, product, transaction value, and current tariff. Check current terms directly with the provider. Never present an old fee table as a current M-PESA tariff.

Refunds, reversals, and payment records

A refund is a business decision to return money to a customer. A provider reversal is a separate transaction that may have eligibility rules and a specific process. Neither should silently erase the original sale or payment record.

Link the refund or reversal reference to the original order and payment. Record who approved it, the reason, amount, date, and status. If an order is cancelled while a payment is pending, check the provider result before releasing reserved stock or promising that money has been returned.

For tax documents, use the correct credit note or eTIMS workflow where applicable; a payment refund does not by itself amend a tax invoice. See the KRA eTIMS guidance and the guide to receipt records and eTIMS requirements.

Common integration mistakes

• Treating an STK Push prompt, browser redirect, or customer screenshot as proof of payment.
• Marking an order paid before matching a verified result to its amount and reference.
• Accepting callbacks without authenticating and validating their fields.
• Failing to handle duplicate events, timeouts, late results, or retries.
• Putting secrets in frontend code or committing them to a source repository.
• Building only for a successful test transaction and skipping reversal and reconciliation scenarios.
• Promising a fixed fee or guaranteed settlement time without checking the current provider agreement.

Pre-launch checklist

Confirm the live business account and provider approval; secure server-side credentials; test all payment states; verify amount and order matching; make repeated notifications safe; define a reconciliation owner; document refund and reversal steps; and publish clear payment and delivery terms.

C2B, B2C, and B2B are different transaction directions

M-PESA API product names describe who sends or receives funds. Customer-to-business (C2B) is the direction relevant when a buyer pays a merchant. STK Push is one way to initiate a C2B payment; a customer can also follow a paybill or till process where supported. Business-to-customer (B2C) generally describes a business disbursement to a customer, such as an eligible refund or payout flow. Business-to-business (B2B) concerns payments between businesses. These products have different account permissions, risks, and approval requirements.

Do not select a disbursement or supplier-payment API just because it contains the word M-PESA. Confirm the direction, product, shortcode, and live permissions with Safaricom. For a storefront purchase, document the payer, merchant, amount, order reference, and authoritative confirmation event. For any payout, require a separate approval and beneficiary-validation process.

Choose a provider or developer using evidence

Ask a prospective provider to explain the exact payment sequence, show how a repeated callback is handled, demonstrate the reconciliation report, and describe the support path during an outage. Ask which party owns the source code, credentials, callback endpoint, monitoring, production approval, and future API updates. Request a test plan and an itemized price rather than relying on a successful demo alone.

Do not send live credentials over ordinary email or chat. Use a controlled secret-sharing process, restrict production access, rotate credentials when staff or contractors leave, and keep a written inventory of the systems that use each credential.

Further reading: How ecommerce website costs are built, digital receipts and customer records, and Safaricom’s Daraja developer portal.