Skip to main content

Mobile Money Guide

This guide details how to process Mobile Money payments (MPESA, AIRTEL, MTN, TIGOPESA) directly via the Little Pay API.

1. Setup & Credentials​

Before getting started, ensure you have an account:

  1. Create an account and a sandbox merchant at https://pay.little.africa.
  2. Navigate to Merchants -> Merchant Settings to obtain your credentials:
    • App ID
    • Client ID
    • Client Secret
    • Token ID
    • Secret Key (Used as X-API-KEY)

Note: The Secret Key can be found in the Security tab of the Merchant Settings.

2. Create Payment Intent​

First, create a payment intent.

  • URL: https://pay.little.africa/api/payments/{tokenId}/pay
  • Method: POST
  • Authentication: Basic Auth (use ClientId as username and ClientSecret as password).

Request Body​

The payload should be a JSON object with the following fields:

{
  "amount": 0, //required - amount
  "currency": "string", //required ISO 4217 currency code eg "KES"
  "description": "string", // required
  "callbackUrl": "string", // required
  "key": "string", // required alphanumeric string
  "expiresAt": 0, // optional - minutes after which the payment intent expires
  "payload": {
    "billingAddress": {
      "firstName": "string", //optional 
      "lastName": "string", //optional
      "email": "string", //optional if phone is provided
      "phoneNumber": "string" //optional if email is provided
    },
    "customData": null // optional json with any additional data you want to pass
  }
}

Code Examples​

To create a payment intent, see the examples below:

const https = require('https');

const data = JSON.stringify({
  amount: 100,
  currency: "KES",
  description: "Mobile Money Payment",
  callbackUrl: "https://your-domain.com/callback",
  key: "MM12345",
  payload: {
    billingAddress: {
      phoneNumber: "+254712345678"
    }
  }
});

const options = {
  hostname: 'pay.little.africa',
  path: '/api/payments/{tokenId}/pay', // Replace {tokenId}
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from('YOUR_CLIENT_ID:YOUR_CLIENT_SECRET').toString('base64'),
    'Content-Length': data.length
  }
};

const req = https.request(options, (res) => {
  let body = '';
  res.on('data', (chunk) => body += chunk);
  res.on('end', () => {
    console.log(JSON.parse(body));
  });
});

req.write(data);
req.end();

Response​

{
  "date": "2024-03-07T13:03:05.141Z",
  "data": {
    "reference": "YOUR_REFERENCE_ID",
    "checkoutUrl": "",
    "message": "Request processed successfully"
  }
}

3. Process Payment​

Use the reference from Step 2 to process the mobile money payment.

  • URL: https://pay.little.africa/pay/{reference}/process
  • Method: POST

Request Body​

{
  "type": "MPESA", // supports: MPESA, AIRTEL, MTN, TIGOPESA
  "payment": {
    "mobile": "+254712345678" // phone number in ISO format
  }
}

Code Examples​

const https = require('https');

const data = JSON.stringify({
  type: "MPESA",
  payment: {
    mobile: "+254712345678"
  }
});

const options = {
  hostname: 'pay.little.africa',
  path: '/pay/{reference}/process', // Replace {reference}
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length
  }
};

const req = https.request(options, (res) => {
  let body = '';
  res.on('data', (chunk) => body += chunk);
  res.on('end', () => {
    console.log(JSON.parse(body));
  });
});

req.write(data);
req.end();

Response​

{
  "date": "2024-03-07T13:03:43.598Z",
  "data": {
    "status": "PENDING",
    "message": "You will be promoted to enter your MPESA PIN",
    "meta": {
      "provider": "MPESA",
      "providerReference": "",
      "stepUpUrl": null,
      "accessToken": null,
      "amount": 1,
      "currency": "KES",
      "description": "",
      "reference": ""
    }
  }
}

4. Handle Callback​

Once the payment is completed (user enters PIN), a callback is sent to your callbackUrl.

{
  "reference": "1cbfffbc-b365-45f6-9e5d-13e445c125cd",
  "status": "COMPLETED", // COMPLETED or FAILED
  "payload": {
    "billingAddress": { /* ... */ },
    "customData": null
  },
  "amount": 1,
  "key": "MM12345",
  "currency": "KES",
  "provider": "MPESA",
  "date": "2025-02-03T13:49:46.000Z"
}

5. Check Status (Optional)​

You can check the transaction status at any time.

  • URL: https://pay.little.africa/api/payments-v2/{key}
  • Method: GET
  • Headers: X-API-KEY: {Secret Key}

Response​

{
  "date": "2024-05-13T08:26:18.719Z",
  "data": {
    "reference": "1cbfffbc-b365-45f6-9e5d-13e445c125cd",
    "status": "COMPLETED",
    "payload": { /* ... */ },
    "amount": 1,
    "payment": {
      "provider": "MPESA",
      "details": null
    },
    "key": "MM12345"
  }
}