Search…
⌃K
Links

SDK

Initialize

  1. 1.
    Add gradle dependency by adding the following code to the your Android App build.gradle
dependencies {
implementation "io.nearpay:nearpay-sdk:2.1.07"
}
2.Create single instance of NearPay object with context wherever you need.
Kotlin
Java
val nearpay = NearPay(this, AuthenticationData.UserEnter, Locale.getDefault(), Environments.SANDBOX)
nearPay = new NearPay(this, AuthenticationData.UserEnter.INSTANCE, Locale.getDefault(), Environments.SANDBOX);

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

Context

You need to pass the current context

AuthenticationData .

We have 4 method for login
1- Login with JWT
AuthenticationData.Jwt("jwt here")
2-Login with existing mobile number
AuthenticationData.Mobile("+966500000000")
3-Login with existing email
AuthenticationData.Email("[email protected]")
4-Let the user enter the mobile number or email to Login
AuthenticationData.UserEnter
Here is an explanation on how to use client dashboard , you need to add users to terminals so they can use the SDK
User Manual - Client Dashboard.pdf
1MB
PDF
Client Dashboard : https://sandbox.nearpay.io

Locale

Locale allows you to select the language to be used.

Environment

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.
NearPay service is working inside Saudi Arabia only , if you are outside Saudi Arabia , please share your Static ip with Nearpay Team
if the package name of your android project is not registered in NearPay system , you won't be able to communicate with our system .

SDK Flow

  1. 1.
    Once you call any function for the first time , it will ask you to install payment plugin.
2. After the installation is done , we will check your device meets the requirements.
3.If you pass the health check then we will check the JWT and let you accept payment.

Setup (optional)

Setup allows you to install the payment plugin and log in to our app .
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
Java
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")
}
}
}
})
nearPay.setup(new SetupListener() {
@Override
public void onSetupCompleted() {
// when the setup is done successfully
}
@Override
public void onSetupFailed(@NonNull SetupFailure setupFailure) {
if (setupFailure instanceof SetupFailure.AlreadyInstalled) {
// when the payment plugin is already installed .
}
else if (setupFailure instanceof SetupFailure.NotInstalled){
// when the installtion failed .
}
else if (setupFailure instanceof SetupFailure.AuthenticationFailed){
// when the Authentication Failed.
nearPay.updateAuthentication(new AuthenticationData.Jwt("JWT is here"));
}
else if (setupFailure instanceof SetupFailure.InvalidStatus){
// you can get the status using the following code
List<StatusCheckError> status = ((SetupFailure.InvalidStatus) setupFailure).getStatus();
}
}
});
Find Setup Errors here.

Purchase

Please note the amount should be entered like this 100 which means 1.00 SAR so 1455 will be 14.55 SAR & max length is 12 digits include exponent ( 123456789012 ) which will result in 1,234,567,890.12
You may pass Reference ID in customerReferenceNumber field to be attached to this transaction. or null otherwise.
enableReceiptUi is Boolean so you can set it true or false.
Kotlin
Java
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 .
}
}
}
})
Long amount = 100L; // [Required] ammount you want to set .
String customerReferenceNumber = "9ace70b7-977d-4094-b7f4-4ecb17de6753"; // [optional] any number you want to add as a refrence
Boolean enableReceiptUi = true; // [optional] true will enable the ui and false will disable
Boolean enableReversal = true // it will allow you to enable or disable the reverse button
Long finishTimeOut = 1L // Add the number of seconds
nearPay.purchase(amount, customerReferenceNumber, enableReceiptUi, enableReversal, finishTimeOut new PurchaseListener() {
@Override
public void onPurchaseApproved(Nullable List<TransactionReceipt> list) {
// if you wish to get the receipt in Json format use nearPay.toJson()
//write your code here.
}
@Override
public void onPurchaseFailed(@NonNull PurchaseFailure purchaseFailure) {
if (purchaseFailure instanceof PurchaseFailure.GeneralFailure) {
// when there is General error .
}
else if (purchaseFailure instanceof PurchaseFailure.PurchaseDeclined){
// when the payment declined.
}
else if (purchaseFailure instanceof PurchaseFailure.PurchaseRejected){
// when the payment rejected.
}
else if (purchaseFailure instanceof PurchaseFailure.AuthenticationFailed){
// when the authentication failed .
// You can use the following method to update your JWT
nearPay.updateAuthentication(new AuthenticationData.Jwt("JWT is here"));
}
else if (purchaseFailure instanceof PurchaseFailure.InvalidStatus){
// you can get the status using the following code
List<StatusCheckError> status = ((PurchaseFailure.InvalidStatus) purchaseFailure).getStatus();
}
}
});
Find TransactionReceipt model here.
Find Purchase errors here.

Refund

pass the transactionReferenceRetrievalNumber of the transaction you want to refund
enableReceiptUi is Boolean so you can set it true or false.
Kotlin
Java
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
nearpay.refund(amount, transactionUuid, customerReferenceNumber, enableReceiptUi, enableReversal, enableEditableRefundAmountUi, finishTimeOut, 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")
}
}
}
})
Long amount = 100L // [Required] ammount you want to set .
String transactionUuid = "9ace70b7-977d-4094-b7f4-4ecb17de6753" // [Required] add Transaction Reference Retrieval Number
String customerReferenceNumber = "9ace70b7-977d-4094-b7f4-4ecb17de6751" // [optional] any number you want to add as a refrence
Boolean enableReceiptUi = true // [optional] true will enable the ui and false will disable
Boolean enableReversal = true // it will allow you to enable or disable the reverse button
Boolean enableEditableRefundAmountUi = true; // [optional] true will enable the ui and false will disable
Long finishTimeOut = 1L // Add the number of seconds
nearPay.refund(amount, transactionUuid, customerReferenceNumber, enableReceiptUi, enableReversal, enableEditableRefundAmountUi, finishTimeOut, new RefundListener() {
@Override
public void onRefundApproved(@Nullable List<TransactionReceipt> list) {
// write your code here
}
@Override
public void onRefundFailed(@NonNull RefundFailure refundFailure) {
if (refundFailure instanceof RefundFailure.RefundDeclined) {
// when the refund is declined
}
else if (refundFailure instanceof RefundFailure.RefundRejected){
// when the refund is rejected
}
else if (refundFailure instanceof RefundFailure.AuthenticationFailed){
// when the Authentication is failed
// You can use the following method to update your JWT
nearPay.updateAuthentication(new AuthenticationData.Jwt("JWT is here"));
}
else if (refundFailure instanceof RefundFailure.GeneralFailure){
// when there is general error .
}
else if (refundFailure instanceof RefundFailure.InvalidStatus){
// you can get the status using the following code
List<StatusCheckError> status = ((RefundFailure.InvalidStatus) refundFailure).getStatus();
}
}
});
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.
enableReceiptUi is Boolean so you can set it true or false.
Kotlin
Java
val enableReceiptUi = true //[optional] true will enable the ui and false will disable
val finishTimeOut : Long = 1 // Add the number of seconds
nearpay.reconcile(enableReceiptUi, 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")
}
}
}
})
Boolean enableReceiptUi = true; //[optional] true will enable the ui and false will disable
Long finishTimeOut = 1L // Add the number of seconds
nearPay.reconcile(enableReceiptUi, finishTimeOut, new ReconcileListener() {
@Override
public void onReconcileFinished(@Nullable ReconciliationReceipt reconciliationReceipt) {
// you can use the object to get the reconciliationReceipt data .
// if you wish to get the receipt in Json format use nearPay.toJson()
}
@Override
public void onReconcileFailed(@NonNull ReconcileFailure reconcileFailure) {
if (reconcileFailure instanceof ReconcileFailure.AuthenticationFailed) {
// when the Authentication is failed
// You can use the following method to update your JWT
nearPay.updateAuthentication(new AuthenticationData.Jwt("JWT is here"));
}
else if (reconcileFailure instanceof ReconcileFailure.GeneralFailure){
// when there is general error .
}
else if (reconcileFailure instanceof ReconcileFailure.FailureMessage){
// when there is FailureMessage
}
else if (reconcileFailure instanceof ReconcileFailure.InvalidStatus){
// you can get the status using following code
List<StatusCheckError> status = ((ReconcileFailure.InvalidStatus) reconcileFailure).getStatus();
}
}
});
Find Reconcile Data here.
Find Reconcile Error here.

Reverse

To perform a Reverse Transaction , it should be within one minute
enableReceiptUi is Boolean so you can set it true or false.
Kotlin
Java
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")
}
}
}
})
String transactionUuid = "2c094354-38ed-11ed-a261-0242ac120002"; // [Required] add your transaction uuid
Boolean enableReceiptUi = true; // [optional] true will enable the ui and false will disable
Long finishTimeOut = 1L // Add the number of seconds
nearPay.reverse(transactionUuid, enableReceiptUi, finishTimeOut, new ReversalListener() {
@Override
public void onReversalFinished(@Nullable List<TransactionReceipt> list) {
// you can use "transactionReceipt" to get the transactionReceipt data.
// if you wish to get the receipt in Json format use nearPay.toJson()
}
@Override
public void onReversalFailed(@NonNull ReversalFailure reversalFailure) {
if (reversalFailure instanceof ReversalFailure.AuthenticationFailed) {
// when the Authentication is failed
// You can use the following method to update your JWT
nearPay.updateAuthentication(new AuthenticationData.Jwt("JWT is here"));
}
else if (reversalFailure instanceof ReversalFailure.GeneralFailure){
// when there is general error .
}
else if (reversalFailure instanceof ReversalFailure.FailureMessage){
// when there is FailureMessage
}
else if (reversalFailure instanceof ReversalFailure.InvalidStatus){
// you can get the status using following code
List<StatusCheckError> status = ((ReversalFailure.InvalidStatus) reversalFailure).getStatus();
}
}
});
Find TransactionReceipt model here.
Find Reversal Error 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
Kotlin
Java
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")
}
}
}
})
String sessionID = "9ace70b7-977d-4094-b7f4-4ecb17de6753"; // [Required] Session id that's passed from your backend
Boolean enableReceiptUi = true; // [optional] true will enable the ui and false will disable
Boolean enableReversal = true // it will allow you to enable or disable the reverse button
Long finishTimeOut = 1L // Add the number of seconds
nearPay.session(sessionID, enableReceiptUi, enableReversal, finishTimeOut, new SessionListener() {
@Override
public void onSessionClosed(@Nullable Session session) {
// when the session is closed
}
@Override
public void onSessionOpen(@Nullable List<TransactionReceipt> list) {
// when the session is open , you can get the receipt by using TransactionReceipt
}
@Override
public void onSessionFailed(@NonNull SessionFailure sessionFailure) {
if (sessionFailure instanceof SessionFailure.AuthenticationFailed) {
// when the authentication is failed
}
else if (sessionFailure instanceof SessionFailure.GeneralFailure) {
// when there is general error.
}
else if (sessionFailure instanceof SessionFailure.FailureMessage) {
// when there is FailureMessage
}
else if (sessionFailure instanceof SessionFailure.InvalidStatus) {
// you can get the status using reconcileFailure.status
}
}
});
Find Session Data here.

Converting receipt to image for printing

You can convert the receipt to an image so you can print it.
Kotlin
Java
receipt?.toImage(requireContext(), receiptWidth = receiptWidth, object : BitmapListener {
override fun result(bitmap: Bitmap?) {
//bitmap
}
})
ReceiptUtilsKt.toImage(Receipt, context, 400, (BitmapListener) bitmap -> {
//bitmap
});

Logout

When the user logs out of your application - the user must be logged out of the NearPay SDK
Kotlin
Java
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")
}
}
}
})
nearPay.logout(new LogoutListener() {
@Override
public void onLogoutCompleted() {
//write your message here
}
@Override
public void onLogoutFailed(@NonNull LogoutFailure logoutFailure) {
if (logoutFailure instanceof LogoutFailure.AlreadyLoggedOut) {
// when the user is already logged out
}
else if (logoutFailure instanceof LogoutFailure.GeneralFailure) {
// when the error is general error
}
}
});
Find LogoutError types here.