Brij Mpesa Offline Integration

Authentication

To obtain a bearer token send the following fields to the token endpoint

Gets Auth token

POST https://accounts.brij.africa/api/v1/connect/token

Use x-www-form-urlencoded body to obtain a bearer token

Request Body

Name	Type	Description
client_secret*	String	<your-client-secret>
grant_type*	String	<your-client-credentials>
client_id*	String	<your-client-id>

200: OK success

 {
     "access_token": "eyJh......NrdM",
     "expires_in": 3600,
     "token_type": "Bearer",
     "scope": "Mpesa"
}

Registering a Callback URL

To receive payment information once an offline payment is received, you need to register a callback URL along with the routing prefix that will have to be part of the account number the users will key in during payment.

For example, if the account number the user is paying to is 12862637, and your routing prefix is FT then the user has to enter FT12862637 as the account number when making the offline Mpesa Payment.

The routing prefix is important to prevent transaction mix-up. Your callback URL must accept post requests. The request body must be of type application/json.

Registering a Callback URL

POST https://saf.brij.africa/api/mpesaoffline/register-url

Request Body

Name	Type	Description
routingPrefix*	String	<your-prefix>
url*	String	<your-callback-url>

200: OK success

{
     "result": {
       "id": "018b290b......ef229116526c",
       "url": "https://yoursite.tld/path/to/callback",
       "routingPrefix": "FT"
     },
     "message": "success",
     "errors": []
}

400: Bad Request

Updating the Callback URL

The API allows you to update the callback URL or prefix if need be.

Updating the Callback URL

POST https://saf.brij.africa/api/mpesaoffline/update-url/

Query Parameters

Name	Type	Description
id*	String	<your-url-id>

Request Body

Name	Type	Description
routingPrefix*	String	<your-prefix> Required if URL is null otherwise optional
url*	String	<your-callback-url> Required if routingPrefix is null otherwise optional

200: OK success

{
     "result": {
       "id": "018b290b......ef229116526c",
       "url": "https://yourupdatesite.tld/path/to/callback",
       "routingPrefix": "FT"
     },
     "message": "success",
     "errors": []
}

400: Bad Request

Mpesa Offline Callback Structure

Expect the following JSON payload in your registered callback URL.

{
     "msisdn": "254*******7",
     "transId": "RJB..AQ",
     "transAmount": 2.00,
     "billRefNumber": "FT…567",
     "transTime": "20231011132104",
     "firstName": "JOHN",
     "lastName": "DOE"
}

Transaction Status Query

In case a callback is missed by our system or your system, the API provides a way to query the transaction status. You need to provide a result URL that will receive the transaction status callback once it is received from the Mpesa system

Querying transaction status

POST https://saf.brij.africa/api/mpesaoffline/transaction-status

Request Body

Name	Type	Description
billRefNumber*	String	<account-number>
transId*	String	<mpesa-transaction-id>
resultUrl*	String	<url-to-receive-result>

200: OK success

{
     "result": {
       "conversationId": "12ac……a9382"
     },
     "message": "success",
     "errors": []
}

400: Bad Request

Transaction status callback structure (sent to resultUrl)

{
     "conversationId": "2ac……a9382",
     "resultCode": 0,
     "message": "Completed",
     "paymentInfo": {
         "msisdn": "254*******7",
         "transId": "RJB..AQ",
         "transAmount": 2.00,
         "billRefNumber": "FT…567",
         "transTime": "20231011132104",
         "firstName": "JOHN",
         "lastName": "DOE"
     }
}

When the resultCode field has a value of 0 the paymentInfo object will be populated. Otherwise, check for possible failure in the message field.

Postman collection for the APIs is available at:

https://api.postman.com/collections/26066936-4dc35f72-22f0-494b-9f3f-ccb9eafb3683?access_key=PMAT-01HCMMVRK3FEG7Y6WHYGEFDAR6api.postman.com

BRij Mpesa Offline Integration Postman Collection