SDK

Initialize

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

dependencies {
    implementation "io.streampay:streampay-sdk:2.1.03"
}

2. Create a single instance of StreamPay object context wherever you need.

Kotlin

val streampay = StreamPay(this, AuthenticationData.UserEnter, Locale.getDefault(), Environments.SANDBOX)

Java

streamPay = new StreamPay(this, AuthenticationData.UserEnter.INSTANCE, Locale.getDefault(), Environments.SANDBOX);

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

Context:

You need to pass the current context

AuthenticationData.

We have 4 methods for login

1. Login with JWT

AuthenticationData.Jwt("jwt here")

2. Login with your existing mobile number

AuthenticationData.Mobile("[phone]")

3. Login with existing email

AuthenticationData.Email("[e-mail]")

4. Let the user enter the mobile number or email to log in

AuthenticationData.UserEnter

Here is an explanation of how to use the client dashboard, you need to add users to terminals so they can use the SDK.

Link

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.

StreamPay service is working inside Saudi Arabia only, if you are outside Saudi Arabia, please share your Static IP with StreamPay Team

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

SDK Flow

1. Once you call any function for the first time, it will ask you to install a 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

The setup allows you to install the payment plugin and login into our StreamPOS 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

streampay.setup(object : SetupListener{
    override fun onSetupCompleted() {
        // if you wish to get the receipt in Json format use streamPay.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 installation 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

streamPay.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 including exponent ( 123456789012 ) which will result in 1,234,567,890.12

You may pass your Reference ID in customerReferenceNumber field to be attached to this transaction. or null otherwise.

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

Kotlin

val amount : Long = 100 // [Required] amount 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 

streampay.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 streamPay.toJson()
        TODO("Your Code Here")
    
    }
    override fun onPurchaseFailed(purchaseFailure: PurchaseFailure) {
        when (purchaseFailure) {
            is PurchaseFailure.PurchaseDeclined -> {
                // when the payment is 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 a General error.
            }
        }
   }
})ot

Java

Long amount = 100L; // [Required] amount 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 

streamPay.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 streamPay.toJson()
    //write your code here. 
    }

    @Override
    public void onPurchaseFailed(@NonNull PurchaseFailure purchaseFailure) {
        if (purchaseFailure instanceof PurchaseFailure.GeneralFailure) {
        // when there is a General error.  
        }
        else if (purchaseFailure instanceof PurchaseFailure.PurchaseDeclined){
        // when the payment is 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 the Transaction Receipt 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 to true or false.

Kotlin

val amount : Long = 100 // [Required] amount 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 streamPay.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 a general error.
                TODO("Your Code Here")
            }
        }
    }
})

Java

// Some code

Find the Transaction Receipt 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 to true or false.

Kotlin

val enableReceiptUi = true //[optional] true will enable the UI and false will disable 
val finishTimeOut : Long = 1 // Add the number of seconds 

streampay.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 streamPay.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 an unexpected error.
                TODO("Your Code Here")
            }
        }
    }
})

Java

Boolean enableReceiptUi = true; //[optional] true will enable the ui and false will disable 
Long finishTimeOut = 1L // Add the number of seconds  

streamPay.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 streamPay.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
            streamPay.updateAuthentication(new AuthenticationData.Jwt("JWT is here"));
        }
        else if (reconcileFailure instanceof ReconcileFailure.GeneralFailure){
            // when there is a general error.
        }
        else if (reconcileFailure instanceof ReconcileFailure.FailureMessage){
            // when there is FailureMessage
        }
        else if (reconcileFailure instanceof ReconcileFailure.InvalidStatus){
            // you can get the status using the 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 to 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 streamPay.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 a general error.
                TODO("Your Code Here")
            }
        }
    }     
})

Java

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  

streamPay.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 streamPay.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
            streamPay.updateAuthentication(new AuthenticationData.Jwt("JWT is here"));
        }
        else if (reversalFailure instanceof ReversalFailure.GeneralFailure){
            // when there is a general error.
        }
        else if (reversalFailure instanceof ReversalFailure.FailureMessage){
            // when there is FailureMessage
        }
        else if (reversalFailure instanceof ReversalFailure.InvalidStatus){
            // you can get the status using the following code
            List<StatusCheckError> status = ((ReversalFailure.InvalidStatus) reversalFailure).getStatus();
        }
    }
});

Find the Transaction Receipt model here.

Find Reversal Error 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 = receiptWidth, object : BitmapListener {
        override fun result(bitmap: Bitmap?) {
            //bitmap
        }
    })

Java

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 StreamPay POS SDK.

Kotlin

streampay.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 a general error
                TODO("Your Code Here")
            }
        }
    }
})

Java

streamPay.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 a general error
        }
    }
});

Find Logout Error types here.