SDK

Initialize

1. Add gradle dependency by adding the following code to the your Android App build.gradle

If want to download the plugin from Google Play, use this code

Kotlin and Java

dependencies {
    implementation "io.nearpay:nearpay-sdk-store:2.1.59"
}

If you want to download the plugin inside your app

Kotlin and Java

dependencies {
    implementation "io.nearpay:nearpay-sdk:2.1.59"
}

2.Create single instance of NearPay object with context wherever you need.

Kotlin

nearPay = new NearPay.Builder()
        .context(this)
        .authenticationData(auth)
        .environment(Environments.SANDBOX)
        .locale(Locale.getDefault())
        .networkConfiguration(NetworkConfiguration.SIM_PREFERRED)
        .uiPosition(UIPosition.CENTER_BOTTOM)
        .paymentText(new PaymentText("يرجى تمرير الطاقة", "please tap your card"))
        .loadingUi(true)
        .build();

While creating instance for the object , you need to pass the following:

Context

You need to pass the current context

AuthenticationData .

Login Methods

1. Login with JWT

AuthenticationData.Jwt("jwt here")

1. Login with existing mobile number

AuthenticationData.Mobile("[phone]")

1. Login with existing email

AuthenticationData.Email("[email protected]")

1. Let the user enter the mobile number or email to Login

AuthenticationData.UserEnter

Locale (Optional)

Locale allows you to select the language to be used.

Environment (Optional)

This will allow you to choose the environments so you need to choose sandbox and we will tell you when it needs to be changed.

UIPosition (Optional)

This will allow you to choose where to show the UI in your screen.

networkConfiguration (Optional)

This will allow you to choose if you wish to choose which network to be used(Sim, Wifi or default).

If the package name of your android project is not registered in the system , you won't be able to communicate with our system .

SDK FLOW

Setup (optional)

Setup allows you to install the payment plugin and log in to our SDK .

if this function is not used , it will be called automatically when you use any other function.

Please don't use SetUp before any other method like purchase,refund,reconcile and reverse.

Kotlin

nearpay.setup(object : SetupListener{
    override fun onSetupCompleted() {
        // if you wish to get the receipt in Json format use nearPay.toJson()
        TODO("Your Code Here")
    }
    override fun onSetupFailed(setupFailure: SetupFailure) {
        when (setupFailure) {
            is SetupFailure.AlreadyInstalled -> {
            // when the payment plugin is already installed  .
            TODO("Your Code Here")
            }
            is SetupFailure.NotInstalled -> {
            // when the installtion failed .
            TODO("Your Code Here")
            }
            is SetupFailure.AuthenticationFailed -> {
            // when the authentication failed .
            // You can use the following method to update your JWT
            nearpay.updateAuthentication(AuthenticationData.Jwt("JWT HERE")
            TODO("Your Code Here")
            }
            is SetupFailure.InvalidStatus -> {
            // Please note that you can get the status using setupFailure.status
            TODO("Your Code Here")
            }
        }
   }
})

Java

Purchase

Please note the amount should be entered like this 100 which means 1.00 KES so 1455 will be 14.55 KES & max length is 12 digits include exponent ( 123456789012 ) which will result in 1,234,567,890.12

enableReceiptUi is Boolean so you can set it true or false.

Kotlin

val amount : Long = 100 // [Required] ammount you want to set .
val customerReferenceNumber = "9ace70b7-977d-4094-b7f4-4ecb17de6753" //[optional] any number you want to add as a refrence
val enableReceiptUi = true // [optional] true will enable the ui and false will disable
val enableReversal = true // it will allow you to enable or disable the reverse button
val finishTimeOut : Long = 1 // Add the number of seconds

nearpay.purchase(amount, customerReferenceNumber, enableReceiptUi, enableReversal, finishTimeOut, object : PurchaseListener{
    override fun onPurchaseApproved(receipts: List<TransactionReceipt>?) {
        // you can use the object "TransactionReceipt" to get the TransactionReceipt data .
        // if you wish to get the receipt in Json format use nearPay.toJson()
        TODO("Your Code Here")

    }
    override fun onPurchaseFailed(purchaseFailure: PurchaseFailure) {
        when (purchaseFailure) {
            is PurchaseFailure.PurchaseDeclined -> {
                // when the payment declined.
                TODO("Your Code Here")
            }
            is PurchaseFailure.PurchaseRejected -> {
                // when the payment is rejected .
                TODO("Your Code Here")
            }
            is PurchaseFailure.AuthenticationFailed -> {
                // when the authentication failed .
                // You can use the following method to update your JWT
                nearpay.updateAuthentication(AuthenticationData.Jwt("JWT HERE")
                TODO("Your Code Here")
            }
            is PurchaseFailure.InvalidStatus -> {
                // Please note that you can get the status using purchaseFailure.status
                TODO("Your Code Here")

            }
            is PurchaseFailure.GeneralFailure -> {
                // when there is General error .
            }
        }
   }
})

Java

Refund

pass the transactionReferenceRetrievalNumber of the transaction you want to refund

enableReceiptUi is Boolean so you can set it true or false.

Kotlin

val amount : Long = 100 // [Required] ammount you want to set .
val transactionUuid = "9ace70b7-977d-4094-b7f4-4ecb17de6753" // [Required] add Transaction Reference Retrieval Number
val customerReferenceNumber = "9ace70b7-977d-4094-b7f4-4ecb17de6751"; // [optional] any number you want to add as a refrence
val enableReceiptUi = true // [optional] true will enable the ui and false will disable
val enableReversal = true // it will allow you to enable or disable the reverse button
val enableEditableRefundAmountUi = true // [optional] true will enable the ui and false will disable
val finishTimeOut : Long = 1 // Add the number of seconds
val adminPin = "0000" //[optional] when you add the admin pin here , the UI for admin pin won't be shown.

nearpay.refund(amount, transactionUuid, customerReferenceNumber, enableReceiptUi, enableReversal, enableEditableRefundAmountUi, finishTimeOut, adminPin, object : RefundListener{
    override fun onRefundApproved(receipts: List<TransactionReceipt>?) {
         // if you wish to get the receipt in Json format use nearPay.toJson()
        TODO("Your Code Here")
    }
    override fun onRefundFailed(refundFailure: RefundFailure) {
        when (refundFailure) {
            is RefundFailure.RefundDeclined -> {
                // when the refund is declined
                TODO("Your Code Here")
            }
            is RefundFailure.RefundRejected -> {
                // when the refund is rejected
                TODO("Your Code Here")
            }
            is RefundFailure.AuthenticationFailed -> {
                // when the Authentication is failed
                // You can use the following method to update your JWT
                nearpay.updateAuthentication(AuthenticationData.Jwt("JWT HERE")
            }
            is RefundFailure.InvalidStatus -> {
                // you can get the status using refundFailure.status  .
                TODO("Your Code Here")
            }
            is RefundFailure.GeneralFailure -> {
                // when there is general error .
                TODO("Your Code Here")
            }
        }
    }
})

Java

Reconcile

To perform a reconciliation, Payment reconciliation is an accounting process that verifies account balances to ensure all sets of records are true, consistent, and up-to-date. Businesses can reconcile their accounts daily, weekly, or monthly.

enableReceiptUi is Boolean so you can set it true or false.

Kotlin

val enableReceiptUi = true //[optional] true will enable the ui and false will disable.
val finishTimeOut : Long = 1 //[optional] Add the number of seconds.
val adminPin = "0000" //[optional] when you add the admin pin here , the UI for admin pin won't be shown.

nearpay.reconcile(enableReceiptUi, adminPin, finishTimeOut, object : ReconcileListener {
    override fun onReconcileFinished(receipt: ReconciliationReceipt?) {
        // you can use the object to get the reconciliationReceipt data .
        // if you wish to get the receipt in Json format use nearPay.toJson()
        TODO("Your Code Here")
    }
    override fun onReconcileFailed(reconcileFailure: ReconcileFailure) {
        when (reconcileFailure) {
            is ReconcileFailure.FailureMessage -> {
                // when there is FailureMessage
                TODO("Your Code Here")
            }
            is ReconcileFailure.AuthenticationFailed -> {
                // when the Authentication is failed
                // You can use the following method to update your JWT
                nearpay.updateAuthentication(AuthenticationData.Jwt("JWT HERE")
            }
            is ReconcileFailure.InvalidStatus -> {
                // you can get the status using reconcileFailure.status
                TODO("Your Code Here")
            }
            is ReconcileFailure.GeneralFailure -> {
                // when there is unexpected error .
                TODO("Your Code Here")
            }
        }
    }
})

Java

Reverse

To perform a Reverse Transaction , it should be within one minute

enableReceiptUi is Boolean so you can set it true or false.

Kotlin

val transactionUuid = "2c094354-38ed-11ed-a261-0242ac120002" // [Required] add your transaction uuid
val enableReceiptUi = true // [optional] true will enable the ui and false will disable
val finishTimeOut : Long = 1 // Add the number of seconds

nearpay.reverse(transaction_uuid, enableReceiptUi, finishTimeOut, object : ReversalListener {
    override fun onReversalFinished(receipts: List<TransactionReceipt>?) {
        // you can use "transactionReceipt" to get the transactionReceipt data.
        // if you wish to get the receipt in Json format use nearPay.toJson()
        TODO("Your Code Here")
    }
    override fun onReversalFailed(reversalFailure: ReversalFailure) {
        when(reversalFailure) {
            is ReversalFailure.FailureMessage -> {
                // when there is FailureMessage
                TODO("Your Code Here")
            }
            is ReversalFailure.AuthenticationFailed -> {
                // when the Authentication is failed
                // You can use the following method to update your JWT
                nearpay.updateAuthentication(AuthenticationData.Jwt("JWT HERE")
            }
            is ReversalFailure.InvalidStatus -> {
                // you can get the status using reversalFailure.status
                TODO("Your Code Here")
            }
            is ReversalFailure.GeneralFailure -> {
                // when there is general error .
                TODO("Your Code Here")
            }
        }
    }
})

Java

Session

Session is used to allow your users to make one transaction while the session is open, once it is closed they are not allowed to make transaction till you create another session, you need to pass the session id that you are getting when creating a new session using our the dashboard.

Kotlin

val sessionID = "9ace70b7-977d-4094-b7f4-4ecb17de6753" // [Required] Session id that's passed from your backend
val enableReceiptUi = true // [optional] true will enable the ui and false will disable
val enableReversal = true // it will allow you to enable or disable the reverse button
val finishTimeOut : Long = 1 // Add the number of seconds

nearpay.session(sessionID, enableReceiptUi, enableReversal, finishTimeOut, object : SessionListener{
    override fun onSessionClosed(session: Session?) {
        // you can use the object "TransactionReceipt" to get the TransactionReceipt data .
        // if you wish to get the receipt in Json format use nearPay.toJson()
        TODO("Your Code Here")

    }
    override fun onSessionOpen(receipts: List<TransactionReceipt>?) {
        // you can use the object "TransactionReceipt" to get the TransactionReceipt data .
        TODO("Your Code Here")
    }
    override fun onSessionFailed(sessionFailure: SessionFailure) {
        when (sessionFailure) {
            is SessionFailure.AuthenticationFailed -> {
                // when the authentication is failed
                TODO("Your Code Here")
            }
            is SessionFailure.GeneralFailure -> {
                // when there is general error
                TODO("Your Code Here")
            }
            is SessionFailure.FailureMessage -> {
                // when there is FailureMessage
                TODO("Your Code Here")
            }
            is SessionFailure.InvalidStatus -> {
                // Please note that you can get the status using sessionFailure.status
                TODO("Your Code Here")

            }
        }
   }
})

Java

Find Session Data here.

Converting receipt to image for printing

You can convert the receipt to an image so you can print it.

Kotlin

receipt?.toImage(requireContext(), receiptWidth, fontSize, object : BitmapListener {
        override fun result(bitmap: Bitmap?) {
            //bitmap
        }
    })

Java

Logout

When the user logs out of your application - the user must be logged out of the NearPay SDK

Kotlin

nearpay.logout(object : LogoutListener {
    override fun onLogoutCompleted() {
        //write your message here
        TODO("Your Code Here")
    }
    override fun onLogoutFailed(logoutError: LogoutFailure) {
        when (logoutError) {
            LogoutFailure.AlreadyLoggedOut -> {
                // when the user is already logged out
                TODO("Your Code Here")
            }
            LogoutFailure.GeneralFailure -> {
                // when the error is general error
                TODO("Your Code Here")
            }
        }
    }
})

Java