MPESA API Integration Guide for Mobile App Development

MPESA API Integration Guide for Mobile App Development

Mobile money services like MPESA have revolutionized financial transactions, making payments fast, secure, and
accessible. Integrating the MPESA API into your mobile app can add significant value by enabling seamless
payment processing. This guide walks you through the integration process step-by-step.

1. Understand MPESA API and Its Use Cases

The MPESA API, also known as the Daraja API, is provided by Safaricom to facilitate mobile money transactions.
Common use cases include:

  • Processing payments for goods and services.
  • Enabling user-to-user money transfers.
  • Checking transaction statuses and balances.
  • Automating refunds and reversals.

2. Prerequisites for MPESA API Integration

Before you start, ensure the following:

  • An active MPESA account.
  • Access to the MPESA Developer Portal.
  • A valid API key and secret.
  • Basic understanding of RESTful APIs and programming skills in a suitable language (e.g., Java, Kotlin,
    Swift, or Flutter).

3. Set Up MPESA Developer Account

Follow these steps:

  1. Register on the MPESA Developer Portal and create an account.
  2. Create a new app to get your API key and secret.
  3. Set up your callback URLs for receiving payment responses and transaction updates.

4. Obtain API Credentials

After registering your app, you’ll receive the Consumer Key and Consumer Secret. Use these
credentials to generate an access token, which is required for all API requests. 

curl -X POST -H "Authorization: Basic {base64_encoded_key_secret}" \
"https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials"

5. Implement the API in Your Mobile App

Here’s a general approach for integrating the API:

a. Generate Access Token

Use your backend server to generate an access token and securely send it to your mobile app.

b. Make API Requests

Examples include:

  • Initiating payment requests using the STK Push API.
  • Querying transaction statuses with the Transaction Status API.

fetch('https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ACCESS_TOKEN',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        BusinessShortCode: '174379',
        Password: 'GENERATED_PASSWORD',
        Timestamp: 'CURRENT_TIMESTAMP',
        TransactionType: 'CustomerPayBillOnline',
        Amount: '1',
        PartyA: '254700000000',
        PartyB: '174379',
        PhoneNumber: '254700000000',
        CallBackURL: 'https://your-callback-url.com',
        AccountReference: 'CompanyXYZ',
        TransactionDesc: 'Payment for goods'
    })
});

6. Test the Integration

Use MPESA’s sandbox environment to simulate transactions and verify the integration. This helps ensure your app
handles various scenarios, such as successful payments, failed payments, and timeouts.

7. Go Live

After successful testing, request production access from Safaricom. Update your app to use the production API
URLs and credentials.

8. Best Practices

  • Secure your API credentials and access tokens to prevent unauthorized access.
  • Log all API responses for troubleshooting and audits.
  • Provide clear feedback to users about the status of their transactions.
  • Implement retries for handling network issues.

Conclusion

Integrating the MPESA API in your mobile app opens up numerous possibilities for creating robust and
user-friendly payment experiences. By following the steps outlined above, you can ensure a seamless integration
process.