Page

🔧 Requirements

Java 11 or higher.
Maven for dependency management.
Mpesa API credentials (consumer key, consumer secret).

🛠️ Installation

To integrate Mpesa Payment API into your project, follow these steps:

Locally build and install

Clone the repository:


git clone https://github.com/dere7/mpesa-sdk.git
cd mpesa-sdk

Install dependencies: For Maven:


mvn install -Dgroups=mocked # This runs only mock tests then install locally

Maven


<dependency>
  <groupId>io.github.dere7</groupId>
  <artifactId>mpesa-sdk</artifactId>
  <version>1.1.1</version>
</dependency>

Gradle


implementation 'io.github.dere7:mpesa-sdk:1.0'

⚡ Usage Examples

Example 1: Trigger USSD Push Request (With Configuration)


// Create Mpesa instance with configuration
Configuration config = Configuration.builder()
    .baseUrl("https://apisandbox.safaricom.et")
    .logLevel(Level.ALL)
    .build();
 
Mpesa mpesa = new Mpesa("test_consumer_key", "test_consumer_secret", config);
 
UssdPushRequest request = UssdPushRequest.builder()
        .merchantRequestId("Partner name some testing")
        .businessShortCode("1020")
        .password("password")
        .timestamp("20240918055823")
        .transactionType("CustomerPayBillOnline")
        .amount("20")
        .partyA("251777890420")
        .partyB("1020")
        .phoneNumber("251777890420")
        .transactionDesc("Payment Reason")
        .callBackUrl("https://www.myservice:8080/result")
        .accountReference("Partner Unique ID")
        .referenceData(List.of(new ReferenceData("ThirdPartyReference", "Ref-12345")))
        .build();
 
UssdPushResponse response = mpesa.triggerUssdPush(request);
System.out.println(response.getResponseDescription());

Example 2: Trigger USSD Push Request (Without Configuration)

⚠️

Warning

This example is not intended for production use as it utilizes the sandbox API. It is recommended to use a configuration object to set the base URL.


// Create Mpesa instance without configuration
Mpesa mpesa = new Mpesa("test_consumer_key", "test_consumer_secret");
 
UssdPushRequest request = UssdPushRequest.builder()
        .merchantRequestId("Partner name some testing")
        .businessShortCode("1020")
        .password("password")
        .timestamp("20240918055823")
        .transactionType("CustomerPayBillOnline")
        .amount("20")
        .partyA("251777890420")
        .partyB("1020")
        .phoneNumber("251777890420")
        .transactionDesc("Payment Reason")
        .callBackUrl("https://www.myservice:8080/result")
        .accountReference("Partner Unique ID")
        .referenceData(List.of(new ReferenceData("ThirdPartyReference", "Ref-12345")))
        .build();
 
UssdPushResponse response = mpesa.triggerUssdPush(request);
System.out.println(response.getResponseDescription());

Example 3: Trigger USSD Push Request (Asynchronous)


UssdPushRequest request = UssdPushRequest.builder()
        .merchantRequestId("Partner name some testing")
        .businessShortCode("1020")
        .password("password")
        .timestamp("20240918055823")
        .transactionType("CustomerPayBillOnline")
        .amount("20")
        .partyA("251777890420")
        .partyB("1020")
        .phoneNumber("251777890420")
        .transactionDesc("Payment Reason")
        .callBackUrl("https://www.myservice:8080/result")
        .accountReference("Partner Unique ID")
        .referenceData(List.of(new ReferenceData("ThirdPartyReference", "Ref-12345")))
        .build();
 
mpesa.triggerUssdPushAsync(request,
    response -> {
        System.out.println(response.getResponseDescription());
    },
    error -> {
        System.out.println("Error callback should not be invoked");
    });

Example 4: Custom Client

You can create your custom http client and use it to make requests to the API.


// Create a custom client
public class ClientImpl implements Client {
  @Override
  	<T> ResponseClient sendSyncRequest(RequestClient<T> requestClient) {
      // YOUR IMPLEMENTATION HERE
    };
 
    @Override
    <T> void sendAsyncRequest(RequestClient<T> requestClient, CallbackClient callbackClient, CallbackErrorClient callbackErrorClient){
      // YOUR IMPLEMENTATION HERE
    }
 
}
 
// Create Mpesa instance with custom client
 
Mpesa mpesa = new Mpesa("test_consumer_key", "test_consumer_secret");
mpesa.setClient(new ClientImpl());