Daraja Multiplatform

⚠️Work in progress - Sandbox Mode⚠️

Kotlin multiplatform wrapper for Mpesa API dubbed Daraja API (Daraja means bridge in Swahili) that supports integration with your Android(Kotlin/Java), iOS(Swift) and JVM applications.

M-PESA is a mobile money transfer service in Kenya that allows users to store and transfer money through their mobile phones.

Prerequisite

To get started, you’ll need to create an account on the Daraja API portal to use the Daraja API. How to get started with Daraja API.

After successfully creating an account on the Daraja API portal and creating a new Daraja app, you’ll need to add your consumer key, consumer secret and pass key obtained from the Daraja API portal to your project.

Features

The SDK offers the following functionalities from the Daraja API:

Usage

Android - Kotlin

Setting Up

In your android application project-level gradle file add the following dependency:

Kotlin

  dependencies {
  implementation ("io.github.victorkabata:daraja-multiplatform:0.9.3")
}

Groovy

  dependencies {
    implementation 'io.github.victorkabata:daraja-multiplatform:0.9.3'
  }

Add your consumer secret, consumer key and pass key to your project. You can get them from the Daraja API portal.

You should not add your daraja API environment variables in a production application because it is a vulnerability to expose your environment secrets/variables in your version control system. Ideally, you should add them to your local.properties files as demonstrated in the sample android application.

Create an instance of the Daraja object by passing the daraja environment variables. The daraja object provides functions to request for an access token and initiate M-Pesa express STK request.

val daraja: Daraja = Daraja.Builder()
            .setConsumerSecret("your_consumer_secret")
            .setConsumerKey("your_consumer_key")
            .setPassKey("your_pass_key")
            .isProduction() // Optional. Will default to sandbox_mode = true
            .build()

Network logging is enabled by default when using Daraja Multiplatform. in sandbox/testing mode. The logs can be accessed from the logcat in Android Studio under the Daraja Multiplatform tag.

Network logs are disabled in production mode.

Request Access Token

To request an access token from Daraja API, invoke the authorization function:

val accessTokenResult: DarajaResult<DarajaToken> = daraja.authorization()

accessTokenResult
        .onSuccess { accessToken ->
            // Successfully fetched daraja access token
        }
        .onFailure { error ->
            // Failure fetching daraja access token
        }

Initiate M-Pesa Express STK Request

To initiate M-Pesa Express(Lipa na M-Pesa Online) STK request, invoke the mpesaExpress function:

val darajaPaymentResponse: DarajaResult<DarajaPaymentResponse> = daraja.mpesaExpress(
            businessShortCode = "174379",
            amount = 1,
            phoneNumber = "07xxxxxxxx",
            transactionDesc = "M-Pesa payment",
            callbackUrl = "your_callback_url",
            accountReference = "CompanyName"
        )

darajaPaymentResponse
        .onSuccess { paymentResponse ->
            // Successfully requested M-Pesa STK request
        }.onFailure { error ->
            // Failed to request M-Pesa STK
        }

Query M-Pesa Transaction

To check the status of an M-pesa transaction, invoke the transactionStatus function:

val darajaTransactionResponse: DarajaResult<DarajaTransactionResponse> = daraja.transactionStatus(
            businessShortCode = "174379",
            checkoutRequestID = "ws_CO_20122022180112029708374149"
        )

darajaTransactionResponse
        .onSuccess { transactionResponse ->
            // Successfully fetched M-pesa transaction status
        }.onFailure { error ->
            // Failure fetching M-pesa transaction status
        }

Customer To Business(C2B)

To register the C2B validation and confirmation URL, invoke the c2bRegistration function:

val darajaC2BRegistrationResponse:DarajaResult<C2BResponse> = daraja.c2bRegistration(
            confirmationURL = "https://mydomain.com/confirmation",
            responseType = C2BResponseType.COMPLETED, // C2BResponseType.CANCELLED
            businessShortCode = 600981,
            validationURL = "https://mydomain.com/validation"
        )

darajaC2BRegistrationResponse.onSuccess {
  // Successfully registered  confirmation and validation URL
}.onFailure{
  // Failure registering confirmation and validation URL
}

To initiate a Customer to Business paybill, invoke the c2b function:

val c2bResponse: DarajaResult<C2BResponse> = daraja.c2b(
            amount = 1,
            billReferenceNumber = "600977",
            transactionType = DarajaTransactionType.CustomerBuyGoodsOnline, // DarajaTransactionType.CustomerPayBillOnline
            phoneNumber = "0708374149",
            businessShortCode = "600977" //Optional when using CustomerBuyGoodsOnline
        )

c2bResponse.onSuccess {
  // Successfully invoked C2B request
}.onFailure{
  // Failure invoking C2B request
}

iOS - Swift

Setting Up

To add DarajaMultiplatform package to your Xcode Project, open your Xcode project, navigate to the File tab within the macOS bar and click Select Packages then Add Package Dependency. Enter the package name ie. DarajaMultiplatform or the URL package GitHub URL:

https://github.com/VictorKabata/DarajaSwiftPackage.git

Create an instance of the Daraja object by passing the daraja environment variables. The daraja object provides functions to request for an access token and initiate M-Pesa express STK request.

var daraja=Daraja(
        consumerKey: "your_consumer_key",
        consumerSecret: "your_customer_secret",
        passKey:"your_pass_key",
        environment: DarajaEnvironment.sandboxEnvironment
        )

Network logging is enabled by default when using Daraja Multiplatform. in sandbox/testing mode. The logs can be accessed from the logs in XCode IDE

Network logs are strictly disabled in production mode ie. DarajaEnvironment.productionEnvironment

Request Access Token

To request an access token from Daraja API, invoke the authorization function:

var accessTokenResult = daraja.authorization()

accessTokenResult.onSuccess(action: { accessToken in
    // Successfully fetched daraja access token
        print(accessToken)
    }).onFailure(action: { error in
     // Failure fetching daraja access token
        print(error)
    })

Initiate M-Pesa Express STK Request

To initiate M-Pesa Express(Lipa na M-Pesa Online) STK request, invoke the mpesaExpress function:

var darajaResponse = daraja.mpesaExpress(
  businessShortCode: "174379",
  amount: 1,
  phoneNumber: "07xxxxxxxx",
  transactionType: DarajaTransactionType.customerpaybillonline, transactionDesc: "M-Pesa payment",
  callbackUrl: "https://mydomain.com/path",
  accountReference: "Company name")

  darajaResponse.onSuccess(action: { data in
    // Successfully requested M-Pesa STK request
        print(data)
    })
    .onFailure(action: { error in
    // Failed to request M-Pesa STK
        print(error)
    })

Query M-Pesa Transaction

To check the status of an M-pesa transaction, invoke the transactionStatus function:

var darajaTransactionResponse = daraja.transactionStatus(
  businessShortCode: "174379", checkoutRequestID: "ws_CO_20122022180112029708374149")

darajaTransactionResponse.onSuccess(action: { data in
  // Successfully fetched M-pesa transaction status
  print(data)
}).onFailure(action: { error in
  // Failure fetching M-pesa transaction status
  print(error.errorMessage)
})

victorkabata / darajamultiplatform Goto Github PK