Merchant Terminal

How to add library build file to the project

Open your app’s build.gradle file and add a declaration similar to the following:

// Gradle Groovy DSL install command

implementation 'io.vipaso.horizon:terminalSdk:1.0.4'

// Add Gradle Groovy DSL repository command

maven {
  url 'https://development.targit.at/api/v4/projects/34/packages/maven'
}

// Gradle Kotlin DSL install command

implementation("io.vipaso.horizon:terminalSdk:1.0.4")

// Add Gradle Kotlin DSL repository command

maven("https://development.targit.at/api/v4/projects/34/packages/maven")

Check this documentation for more details about libraries: <<<<https://developer.android.com/studio/projects/android-library>>>>

Library packages and classes structure

• API package contains:
  • DTO package that contains a request package with api requests ordered by purpose packages(payment, redemption, transaction and user). The DTO package also includes response packages ordered by purpose. There you can see in more detail the response values of all API calls.
  • Interfaces package contains interfaces with API calls named after the purpose they have(BonusProgramApi, PaymentApi, RedemptionApi, TransactionApi, UserApi).
  • Repositories package contains classes ordered by purpose that use API interfaces to make API requests(BonusProgramRepository, PaymentRepository, RedemptionRepository, TransactionRepository, UserRepository).
  • Storage package is the most important package because it contains use case classes that you will be calling directly from your project. The storage package contains a use case class with one function for each API call or calls for payment, redemption and terminal clients(Please follow instructions below for each use case function with call examples and also see comments in code for more details about parameters and responses).
• Hosts package contains PaymentHost class ..., RedemptionHost ...
• DI package contains Module package and Graph class for dependency injection.
• TerminalSdkApplication class is used for initialising the dependency injection Graph.

Getting started

Current SDK version: 1.0.0
Minimum SDK version for using a library: 21

Permissions:

• "android.permission.ACCESS_FINE_LOCATION"
• "android.permission.ACCESS_COARSE_LOCATION"
• "android.permission.ACCESS_BACKGROUND_LOCATION"
• "android.permission.BLUETOOTH_CONNECT"
• "android.permission.INTERNET"
• "android.permission.ACCESS_NETWORK_STATE"
• "android.permission.READ_PHONE_STATE"
• "android.permission.BLUETOOTH"
• "android.permission.BLUETOOTH_ADMIN"
• "android.permission.UPDATE_DEVICE_STATSU"
• "android.permission.ACCESS_NETWORK_STATE"
• "android.hardware.location.network"

To use Terminal SDK functions you need to instantiate a TerminalAppClient class, example:

var appClient: TerminalAppClient = TerminaltAppClient(YourApplication.context)

Also TerminalAppClient contains callbacks for payments and bonus programs. For example, next two callbacks are used for starting payment and redemption and returns if it is successfully started:

fun startWithAmount(amount: Long, callback: (Boolean) -> Unit) {
    this.paymentHost.startWithAmount(amount, callback)
}

fun startRedemption(callback: (Boolean) -> Unit) {
    this.redemptionHost.startRedemption(callback)
}

and the next two callbacks are used for canceling a payment and redemption:

fun cancelPayment(reason: String) {
    this.paymentHost.cancelPayment(reason)
}

fun cancelRedemption() {
    this.redemptionHost.cancelRedemption()
}

Next, TerminalAppClient also has PaymentHostCallback and PaymentProcessCallback intefaces. First one is used to check what Wallet App is done after you start the payment(accepted or denied and verified method that should be called after accepted) and second is used for checking if payment is done or failed after it is accepted and verified:

interface PaymentHostCallback {
    fun paymentDidVerified()
    fun paymentAccepted()
    fun paymentDenied()
}

interface PaymentProcessCallback {
    fun paymentDone(order: PaymentOrder?)
    fun paymentFailed()
}

same for redemption case:

interface RedemptionHostCallback {
    fun redemptionDidVerified()
    fun redemptionAccepted()
    fun redemptionDenied()
}

interface RedemptionProcessCallback {
    fun redemptionFailed()
    fun redemptionDone()
}

Use case classes and functions with examples

Registration and login of a merchant

• UserLoginUseCase.login(email: String, password: String)
  Takes email and password. Returns register user info (applicationToken, serverPublicKey, activationUrl and isActivatedUser).
  Call example:

 userLoginUseCase.login(email, password)
            .subscribe({
                val payload = it.payload as ActivateUserResponse
                if (payload != null) {
                    if (payload.isActivatedUser == true) {
                        //Your code here for activated user
                        }
                    } else {
                      //Your code here for unactivated user
                    }
                 }
            } ,{
                Log.e("APICALLLOG", it.toString())
            })

• CheckActivationUseCase.checkActivation()
  Returns info if merchant account is activated or not.
  Call example:

checkActivationUseCase.checkActivation().subscribe({
                 if(it) {
                   //Your code here
                } else {
							}
            } ,{
                Log.e("APICALLLOG", it.toString())
            })

• GetMerchantUseCase.getMerchant()
  Returns merchant object with details.
• AddRegisterUserUseCase.addRegisterUser(name: String)
  Adds user to the Merchant(waiter for example) and returns info list with register users of the Merchant. Call example:

addRegisterUserUseCase.addRegisterUser(name.text.toString()).subscribe({
                        val registerUsers = it.payload.registerUsers
                        if (registerUsers != null) {
                            //Your code here.
                            }
                        }

                    }, {// it: Throwable
                 })

• DeleteRegisterUserUseCase.deleteRegisterUser(id: Long)
  Remove user from the Merchant(waiter for example) and returns info list with register users of the Merchant. Call example:

deleteRegisterUserUseCase.deleteRegisterUser(users[position].id).subscribe {
                        val registerUsers = it.payload.registerUsers
                        if (registerUsers != null) {
                            //Your code here.
                            }
                        }
                    }

Payments and Transactions

• InitPaymentUseCase.initPayment(amount: Long, userId: Long)
  Takes payment amount and Merchant user id. Returns payment info (session Id, daily token, etc.).
• CancelPaymentUseCase.cancelPayment(sessionId: Long, reason: String)
  Takes payment session Id and reason string. Call Example:

repository.appClient.cancelPayment("Payment was cancelled")

• GetPaymentStateUseCase.getPaymentState(sessionId: Long)
  Takes payment session Id. Returns object that contains payment info(session state, payment confirmation, payment order).
• GetTransactionsUseCase.getTransactions(method: String, bodyRequest: PayloadParametersRequest)
  Takes method("getTransactionsForDay", "getTransactionsForWeek" or "getTransactionsForMonth") and body request(TerminalTransactionDayRequest, TerminalTransactionWeekRequest or TerminalTransactionMonthRequest). Returns Transaction Details object(Transactions sum, transactions list, etc) Call example:

fun getTransactionsForWeekOfYear(week: Int, year: Int): Observable<DataResponse<TerminalTransactionsResponse>> {
        val weekRequest = TerminalTransactionWeekRequest()
        weekRequest.weekOfYear = week
        weekRequest.year = year

        return getTransactions("getTransactionsForWeek", weekRequest)
    }

• GetTransactionDetailsUseCase.getTransactionDetails(sessionId: Long)
  Takes payment session Id. Returns transaction detail info (invoice ammount, currency, tip, order Id, merchant).

Redemption and Bonus Program

• InitRedemptionUseCase.initRedemption(userId: Long)
  Takes user id. Returns object that contains redemption detailed info (redemption Id, program Id, daily token).
• CancelRedemptionUseCase.cancelRedemption(redemptionId: Long, reason: String)
  Takes redemption id and reason for the cancellation.
• GetRedemptionStateUseCase.getRedemptionState(redemptionId: Long)
  Takes redemption id. Returns object that contains redemption state info.
• GetMerchantBonusProgramDetailsUseCase.getMerchantBonusProgramDetails()
  Returns list that contains bounus programs details.