Skip to main content

Mobile Money Payments

To process a payment using mobile money, you can use the POST /pay/{intentId}/process endpoint.

The following is a sample request body for processing a payment using mobile money.

The intentId is the unique identifier for the payment intent. It is returned when you create a payment intent, as the reference field.

POST /pay/{intentId}/process
{
  "type": "MPESA",
  "payment": {
    "mobile": "25400000000"
  }
}
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": ""
    }
  }
}

The status of the payment is returned as PENDING. The status is automatically updated to COMPLETED or FAILED when the payment is completed or fails respectively.

You can check the status of the payment by calling the GET /api/payments-v2/{key} endpoint. The endpoint requires a X-API-KEY header with your API key. The key parameter can either be the intentId used to process the payment, or the key that was set when creating the payment intent.

GET /api/payments-v2/{key}
GET https://pay.little.africa/api/payments-v2/{key}
Response:
{
  "date": "2024-05-13T08:26:18.719Z",
  "data": {
    "reference": "1cbfffbc-b365-45f6-9e5d-13e445c125cd",
    "status": "COMPLETED",
    "payload": {
      "billingAddress": {
        "firstName": "",
        "lastName": "",
        "address1": "",
        "locality": "",
        "administrativeArea": "",
        "postalCode": "",
        "country": "",
        "email": "",
        "phoneNumber": ""
      }
    },
    "amount": 1,
    "payment": {
      "provider": "MPESA",
      "details": null
    },
    "key": "",
    "attempts": [
      {
        "reference": "1cbfffbc-b365-45f6-9e5d-13e445c125cd",
        "provider": "MPESA",
        "status": "COMPLETED"
      }
    ]
  }
}

The attempts property contains a list of attempts that were made to process the payment. Each attempt has a status property that indicates whether the payment was successful or not. The array will only contain one item if you use the intentId as the key parameter to check the payment status.

You can set longPoll to true to enable long polling in the query string. This will keep the connection open until the payment status is updated. The status will be returned as COMPLETED or FAILED when the payment is completed or fails respectively.

Response:
{
  "date": "2024-03-07T13:03:43.598Z",
  "data": {
    "status": "COMPLETED",
    "message": "Success",
    "meta": {
      "provider": "MPESA",
      "providerReference": "",
      "stepUpUrl": null,
      "accessToken": null,
      "amount": 1,
      "currency": "KES",
      "description": "",
      "reference": ""
    }
  }
}