Terminal Payment App

Stitch offers an application for supported Android terminals that has been L3 certified with certain acquirers and schemes. The Payment App also offers partners a seamless integration for adding payment processing via the Stitch platform to their Android App. This integration is achieved with either an Android intent or an Android service connection. For ease of implementation, we've created the Stitch Intent Library.

Stitch Intent Library

Setup

This documentation assumes you're using the modern Kotlin syntax in your Android project for both the Gradle DSL & application code.

Add the Maven Repository and include the dependency:

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        ...
        maven("https://gitlab.com/api/v4/projects/64451428/packages/maven")
    }
}

app/build.gradle.kts

dependencies {
    ...
    implementation("com.exipay.terminal:intent_api:1.1.0")
}

Actions

The actions have a Builder with a mandatory parameters: context & listener. The context is what Android needs to start the Intent and can be the current Activity, the listener is a callback interface where the library will provide the result or error.

Sale (Goods & Services) with or without cashback

val externalPosData = mapOf(
    "posEg1" to UUID.randomUUID().toString(),
    "posEg2" to Random().nextInt().toString(),
    "posEg3" to true.toString(),
)
Sale.Builder(
    this,
    object : SaleTransactionListener {
        override fun alertSaleTransactionResponse(
            response: PosTransactionSummary,
            updatedSessionInfo: SessionInfo?,
        ) {
            // handle response
        }

        override fun alertError(error: IntentError) {
            // handle error
        }
    },
).build().apply {
    if (cashback) {
        // the amount is a total of the goods & cashback - ie must include the cashback amount
        startTransactionWithCashback(amount + cashAmount, cashAmount, externalPosData)
    } else {
        // the amount is represented in cents, so an amount of 1059 is R10.59
        startTransaction(amount, externalPosData)
    }
}

note

The externalPosData is an optional map representing a key value pair that'll be echoed in the result and be sent on the webhooks (payment app may add additional keys). Can be used for adding identifiers aiding in matching, like a DB row id or an order number, etc.

Refund

Refund.Builder(
    context,
    object : RefundTransactionListener {
        override fun alertRefundTransactionResponse(
            response: PosTransactionSummary,
            sessionInfo: SessionInfo?,
        ) {
            // handle response
        }

        override fun alertError(error: IntentError) {
            // handle error
        }
    },
).build().refundTransaction(amount, transactionId)

note

It is the responsibility of the calling app to authorise if the void & refund actions are allowed by the user.

Get Last Transaction

Transaction.Builder(
    context,
    object : TransactionListener {
        override fun alertLastTransactionResponse(
            listOfTransactions: List<PosTransactionResult>?,
            sessionInfo: SessionInfo?,
        ) {
            // handle response
        }

        override fun alertError(error: IntentError) {
            // handle error
        }
    },
).build().lastTransaction()

Search Transactions

val dateFormatter = SimpleDateFormat("yyyy-MM-dd", Locale.getDefault())
val searchParams = mutableMapOf<String, Any>(
    "fromDate" to dateFormatter.format(
        Calendar.getInstance().apply { add(Calendar.DATE, -7) }.time,
    ),
    "toDate" to dateFormatter.format(Calendar.getInstance().time),
)
// optional param amount
amount?.let { searchParams["amount"] = it }
Transaction.Builder(
    context,
    object : TransactionListener {
        override fun alertLastTransactionResponse(
            listOfTransactions: List<PosTransactionResult>?,
            sessionInfo: SessionInfo?,
        ) {
            // handle response
        }

        override fun alertError(error: IntentError) {
            // handle error
        }
    },
).build().searchTransaction(searchParams)