SDK

Initialize

To add a gradle dependency to your Android app, simply include the following code.

NearPay has two methods for initialization to install the plugin:

Download the plugin from Google Play

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

Download the plugin inside your app

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

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

Create a single instance of a NearPay object with context, you can do so wherever you need it.

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

When creating an instance for Nearpay, you must provide the following parameters:

Context Required

You need to pass the current context
AuthenticationData Required

We have 4 method for login:

Login with JWT

AuthenticationData.Jwt("jwt here")

Login with existing mobile number

AuthenticationData.Mobile("+966500000000")

Login with existing email

AuthenticationData.Email("[email protected]")

Let the user enter the mobile number or email to Login

AuthenticationData.UserEnter.INSTANCE

Here is an explanation of how to use the client dashboard. To enable users to use the SDK, you need to add them to terminals.

Environment Required

This will prompt you to select the environment. Please choose "sandbox" and we will notify you when it's time to switch.

Locale Optional

You can choose the language to be used by selecting the locale.

UIPosition Optional

This feature will enable you to select the location on your screen where you want the UI to appear.

networkConfiguration Optional

This will allow you to choose which network to use - SIM, Wi-Fi, or default.

Android SDK Proxy

PDF - 1MP

Client Dashboard here

SDK Flow

Once you call any function for the first time, it will ask you to install a payment plugin.

After the installation is complete, we will verify if your device meets the necessary requirements.

If your health check is successful, we will verify the OTP provided and allow you to proceed with the payment acceptance.

Now you can begin accepting payments.

Please note that when entering the amount, you should use the format 100, which represents 1.00 SAR. For instance, if the amount is 1455, you should enter it as 14.55 SAR. The maximum length allowed is 12 digits, including the exponent (e.g., 123456789012), which will result in 1,234,567,890.12.

You can use the customerReferenceNumber field to attach a Reference ID to this transaction. If there is no reference ID, simply enter null.

The enableReceiptUi parameter is a boolean, which means you can set it to either true or false based on your preference.

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 = 10 // Add the number of seconds 
val transactionId = UUID.randomUUID(); // [optional] You can add your UUID here which allows you to ask about the transaction again using the same UUID
val enableUiDismiss = true // [optional] it will allow you to control dismissing the UI

nearpay.purchase(amount, customerReferenceNumber, enableReceiptUi, enableReversal, finishTimeOut, transactionId, enableUiDismiss, object : PurchaseListener{
    override fun onPurchaseApproved(transactionData: TransactionData) {
        // Your Code Here
    }

    override fun onPurchaseFailed(purchaseFailure: PurchaseFailure) {
        when (purchaseFailure) {
            is PurchaseFailure.PurchaseDeclined -> {
                // when the payment declined.
                // Your Code Here
            }

            is PurchaseFailure.PurchaseRejected -> {
                // when the payment is rejected .
                // 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")
                // Your Code Here
            }

            is PurchaseFailure.InvalidStatus -> {
                // Please note that you can get the status using purchaseFailure.status
                // Your Code Here

            }

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

Find TransactionReceipt model here

Find Purchase errors here

Refund

Kindly provide the transactionUuid of the transaction you wish to refund.

enableReceiptUi is a Boolean variable, which can be set as true or false.

val amount : Long = 100 // [Required] ammount you want to set .
val transactionUuid = "9ace70b7-977d-4094-b7f4-4ecb17de6753" // [Required] add Transaction UUID
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 = 10 // Add the number of seconds 
val transactionId = UUID.randomUUID(); // [optional] You can add your UUID here which allows you to ask about the transaction again using the same UUID
val enableUiDismiss = true // [optional] it will allow you to control dismissing the UI
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, transactionId, adminPin, enableUiDismiss, object : RefundListener{
    override fun onRefundApproved(transactionData: TransactionData) {
        // if you wish to get the receipt in Json format use nearPay.toJson()
        // Your Code Here
    }

    override fun onRefundFailed(refundFailure: RefundFailure) {
        when (refundFailure) {
            is RefundFailure.RefundDeclined -> {
                // when the refund is declined
                // Your Code Here
            }

            is RefundFailure.RefundRejected -> {
                // when the refund is rejected
                // 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  .
                // Your Code Here
            }

            is RefundFailure.GeneralFailure -> {
                // when there is general error .
                // Your Code Here
            }
        }
    }
})

Find TransactionReceipt model here

Find Refund errors here

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.

val enableReceiptUi = true //[optional] true will enable the ui and false will disable.
val finishTimeOut : Long = 10 //[optional] Add the number of seconds.
val enableUiDismiss = true // [optional] it will allow you to control dismissing the UI
val adminPin = "0000"; //[optional] when you add the admin pin here , the UI for admin pin won't be shown.
val reconcileId = UUID.randomUUID(); // [optional] You can add your UUID here which allows you to ask about the transaction again using the same UUID

nearpay.reconcile(reconcileId, enableReceiptUi, adminpin, finishTimeOut, enableUiDismiss, 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()
        // Your Code Here
    }

    override fun onReconcileFailed(reconcileFailure: ReconcileFailure) {
        when (reconcileFailure) {
            is ReconcileFailure.FailureMessage -> {
                // when there is FailureMessage
                // 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
                // Your Code Here
            }

            is ReconcileFailure.GeneralFailure -> {
                // when there is unexpected error .
                // Your Code Here
            }
        }
    }
})

Find Reconcile Data here

Find Reconcile Error here

Get Reconcile by `id`

To retrieve a specific reconciliation by UUID.

val uid = "5cca70b7-347d-4456-b7f4-4ecb17de6753";
Boolean enableReceiptUi = true; //[optional] true will enable the ui and false will disable 
Long finishTimeOut = 10L; // Add the number of seconds

nearPay.getReconciliationByUuid(uid, enableReceiptUi, finishTimeOut, object : GetReconcileListener {
    override fun onSuccess(receipt: ReconciliationReceipt?) {
        //Your Code Here
    }

    override fun onFailure(getDataFailure: GetDataFailure) {
        when (getDataFailure) {
            is GetDataFailure.AuthenticationFailed -> {
                // when the Authentication is failed
                // You can use the following method to update your JWT
                nearpay.updateAuthentication(AuthenticationData.Jwt("JWT HERE")
            }
            is GetDataFailure.FailureMessage -> {
                // when there is FailureMessage
            }
            is GetDataFailure.GeneralFailure -> {
                    // when there is general error
            }
            is GetDataFailure.InvalidStatus -> {
                // you can get the status using reconcileFailure.status
            }
        }
    }
})

Find Reconcile model here

Find Reconcile Error here

Get List of Reconcile

To retrieve all the reconciliation.

val pages = 1;
val page_size = 20;
val startDate = LocalDateTime.of(2024, 1, 1, 1, 1)
val endDate = LocalDateTime.now()


nearPay.getReconciliationListPage( pages, page_size, startDate, endDate object : GetReconciliationPageListener {
        override fun onSuccess(receipt: ReconciliationReceipt?) {
            //Your Code Here
        }
        override fun onFailure(getDataFailure: GetDataFailure) {
            when (getDataFailure) {
                is GetDataFailure.AuthenticationFailed -> {
                    // when the Authentication is failed
                    // You can use the following method to update your JWT
                    nearpay.updateAuthentication(AuthenticationData.Jwt("JWT HERE")
                }
                is GetDataFailure.FailureMessage -> {
                    // when there is FailureMessage
                }
                is GetDataFailure.GeneralFailure -> {
                     // when there is general error
                }
                is GetDataFailure.InvalidStatus -> {
                    // you can get the status using reconcileFailure.status
                }
            }
        }
    })

Find Reconcile model here

Find Reconcile List Error here

Reverse

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

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 = 10 // Add the number of seconds 
val enableUiDismiss = true // [optional] it will allow you to control dismissing the UI

nearpay.reverse(transactionUuid, enableReceiptUi, finishTimeOut, enableUiDismiss, object : ReversalListener {
    override fun onReversalFinished(transactionData: TransactionData) {
        // you can use "transactionData" to get the transactionData.
        // if you wish to get the receipt in Json format use nearPay.toJson()
        //Your Code Here
    }

    override fun onReversalFailed(reversalFailure: ReversalFailure) {
        when(reversalFailure) {
            is ReversalFailure.FailureMessage -> {
                // when there is FailureMessage
                //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
                //Your Code Here
            }
            is ReversalFailure.GeneralFailure -> {
                // when there is general error .
                //Your Code Here
            }
        }
    }     
})

Find TransactionReceipt model here

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 api Create Session

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 = 10 // Add the number of seconds 
val enableUiDismiss = true // [optional] it will allow you to control dismissing the UI

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

    override fun onSessionOpen(transactionData: TransactionData) {
        // you can use the object "TransactionData" to get the TransactionData .
        //Your Code Here
    }

    override fun onSessionFailed(sessionFailure: SessionFailure) {
        when (sessionFailure) {
            is SessionFailure.AuthenticationFailed -> {
                // when the authentication is failed
                //Your Code Here
            }
            is SessionFailure.GeneralFailure -> {
                // when there is general error
                //Your Code Here
            }
            is SessionFailure.FailureMessage -> {
                // when there is FailureMessage
                //Your Code Here
            }
            is SessionFailure.InvalidStatus -> {
                // Please note that you can get the status using sessionFailure.status
                //Your Code Here
            }
        }
   }
})

Find Session Data here

Get Transaction by `id`

To retrieve a specific transaction by UUID.

val uid = "5cca70b7-347d-4456-b7f4-4ecb17de6753";
Boolean enableReceiptUi = true; //[optional] true will enable the ui and false will disable 
Long finishTimeOut = 10L; // Add the number of seconds  

nearPay.getTransactionByUuid(uid, enableReceiptUi, finishTimeOut, object : GetTransactionListener {
    override fun onSuccess(transactionData: TransactionData) {
        //Your Code Here
    }
    override fun onFailure(getDataFailure: GetDataFailure) {
        when (getDataFailure) {
            is GetDataFailure.AuthenticationFailed -> {
                // when the Authentication is failed
                // You can use the following method to update your JWT
                nearpay.updateAuthentication(AuthenticationData.Jwt("JWT HERE")
            }
            is GetDataFailure.FailureMessage -> {
                // when there is FailureMessage
            }
            is GetDataFailure.GeneralFailure -> {
                    // when there is general error
            }
            is GetDataFailure.InvalidStatus -> {
                // you can get the status using reconcileFailure.status
            }
        }
    }
})

Find Transaction Data here

Get List of Transactions

To retrieve all the transactions.

val pages = 1;
val page_size = 20;
val startDate = null,
val endDate = null,
String customerRefNumber = "";

    nearPay.getTransactionListPage( pages, page_size, startDate, endDate, customerRefNumber, object : GetTransactionPageListener {
        override fun onSuccess(transactionList: TransactionBannerList?) {
            binding.console.addLine("getTransaction", "Completed : $transactionList")
        }
        override fun onFailure(dataFailure: GetDataFailure) {
            when (dataFailure) {
                is GetDataFailure.AuthenticationFailed -> {
                    // when the Authentication is failed
                    // You can use the following method to update your JWT
                    nearpay.updateAuthentication(AuthenticationData.Jwt("JWT HERE")
                }
                is GetDataFailure.FailureMessage -> {
                    // when there is FailureMessage
                }
                is GetDataFailure.GeneralFailure -> {
                     // when there is general error
                }
                is GetDataFailure.InvalidStatus -> {
                    // you can get the status using reconcileFailure.status
                }
            }
        }
    })

Find Transaction Data here

Converting receipt to image for printing

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

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

Find Refund errors here

This feature will provide the ability to share a URL through NFC once any function is called.

Note: The phone that will read the NFC needs to have NFC Antennas.

This feature will provide the ability to share a URL through NFC once any function is called.

val url : String = "url" //url: is the url that will be shared through the NFC
val finishTimeOut : Long = 20_000 //20_000 The timeout in MS that represents the time of sharing the url
private fun shareUrl(nearPay: NearPay) {
nearPay.startShareUrlService(url = url, timeoutMillis = finishTimeOut, listener = object: ShareUrlServiceListener {
    override fun onCreated() {
        //When the Url sharing is created
    }

    override fun onProcessed(isSuccess: Boolean) {
        //When the Url sharing is processed in the reader phone
     }

    override fun onDestroyed() {
        //When the Url sharing is killed due to timeout exceeding
     }
})
}

Get User Session

This function will display user details only if the user is logged in to the SDK. If the user is not logged in, an error message will be displayed. Additionally, when a user logs out of your application, they must also be logged out of the NearPay SDK.

    nearPay.getUserSession(object : CheckSessionListener {
            override fun onSessionFree() {
                //add you code here. Triggered when the user is not logged in
            }

            override fun onSessionFailed(sessionFailure: SessionFailure) {
                when(sessionFailure){

                    is SessionFailure.AuthenticationFailed -> {
                        // message
                    }

                    is SessionFailure.FailureMessage -> {
                        // message
                    }

                    SessionFailure.GeneralFailure -> {
                        // add your code here. Triggered when the there's a general error. 
                    }

                    is SessionFailure.InvalidStatus -> {
                        // message 
                    }
                }
            }

            override fun onSessionBusy(message: String) {
                // add your code here. Triggered when there's another app in the same device is using the payment plugin.
            }

            override fun getSessionInfo(info: SessionInfo) {
                // add your code here. Triggred when the user is logged in to the SDK, you can get the session info from SessionInfo
            }
        }
    )

Find Get User Session Info Data types here

Find Get User Session Error types here

Logout

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

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

Find LogoutError types here