carrieukie/darajamultiplatform

Kotlin wrapper for Daraja API

Daraja Multiplatform

⚠️Work in progress⚠️

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.

Table of Content

• Prerequisite
• Usage
  • Android - Kotlin/Java
    • Setting Up
    • Request Access Token
    • Initiate M-Pesa Express STK Request
    • Query M-Pesa Transaction
  • iOS - Swift
    • Setting Up

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.

Usage

Android - Kotlin/Java

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.

object Constants {
    const val CONSUMER_SECRET="your_consumer_secret"
    const val CONSUMER_KEY="your_consumer_key"
    const val PASS_KEY="your_pass_key"
}

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 strictly disabled in production mode.

Request Access Token

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

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

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 initiateDarajaStk function:

val darajaPaymentResponse: DarajaResult<DarajaPaymentResponse> = daraja.initiateDarajaStk(
            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 queryMpesaTransaction function:

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

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

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/DarajaMultiplatform.git