Skip to content

Transactions

Call startTransaction() after a successful device connection to initiate a card-present payment.

Function signature

fun startTransaction(
    amount: Long,
    idempotencyId: String? = null,
    transactionType: TransactionType,
    transactionCallback: MPOSTransactionCallback,
    splitTransfers: List<SplitTransfer>? = null,
    tags: Map<String, String>? = null,
    buyerIdentityId: String? = null,
    surcharge: Long? = null,
    tipAmount: Long? = null,
    promptForSignature: PromptForSignature = PromptForSignature.Never
)
ParameterTypeRequiredDescription
amountLongYesTransaction amount in cents (e.g., 1000 for $10.00).
idempotencyIdString?NoOptional identifier used to idempotently identify transfers, authorizations, or refund requests.
transactionTypeTransactionTypeYesType of transaction. Supported values: TransactionType.SALE, TransactionType.REFUND, TransactionType.AUTHORIZATION.
transactionCallbackMPOSTransactionCallbackYesCallback receiving the transaction result or error.
splitTransfersList<SplitTransfer>?NoSplit the transaction across multiple merchants. Requires ROLE_PARTNER credentials.
tagsMap<String, String>?NoCustom key-value metadata attached to the transaction.
buyerIdentityIdString?NoFinix Identity ID of the buyer.
surchargeLong?NoSurcharge amount in cents added to the transaction.
tipAmountLong?NoTip amount in cents.
promptForSignaturePromptForSignatureNoControls when to prompt for a buyer signature. Defaults to Never.

Callback

MPOSTransactionCallback

interface MPOSTransactionCallback {
    fun onSuccess(result: TransactionResult?)
    fun onError(errorMessage: String)
    fun onProcessing(currentStepMessage: String)
}
CallbackTrigger
onSuccessTransaction approved. result contains the transfer and authorization details.
onErrorTransaction declined or failed. Check errorMessage for details.
onProcessingStep in progress. Display currentStepMessage to the user if desired.

Transaction Controls

Transaction controls

MethodDescription
cancelTransaction()Cancels the transaction currently in progress.
finishTransaction()Signals that the transaction flow is complete and the SDK can clean up its state.

Signature Prompts

PromptForSignature

Controls when the SDK prompts the buyer to sign after a transaction.

Default suppresses all signature prompts

The SDK defaults to Never and will not prompt for a signature even when EMV or CVM logic recommends one.

sealed interface PromptForSignature {
    object Always : PromptForSignature
    object Never : PromptForSignature
    class ThresholdAmount(val thresholdAmount: Long) : PromptForSignature
    object OnNetworkRecommendation : PromptForSignature
}
ValueBehavior
AlwaysPrompt for signature after every transaction.
NeverNever prompt for signature. Default.
ThresholdAmount(amount)Prompt only when the transaction amount meets or exceeds the threshold.
OnNetworkRecommendationPrompt when the card network recommends it.
mpos.startTransaction(
    amount = 1000L,
    transactionType = TransactionType.SALE,
    transactionCallback = object : MPOSTransactionCallback {
        override fun onSuccess(result: TransactionResult?) { }
        override fun onError(errorMessage: String) { }
        override fun onProcessing(currentStepMessage: String) { }
    }
)

mpos.startTransaction(
    amount = 1000L,
    transactionType = TransactionType.SALE,
    transactionCallback = object : MPOSTransactionCallback {
        override fun onSuccess(result: TransactionResult?) {
            // transaction approved — result contains transfer details
        }
        override fun onError(errorMessage: String) {
            // transaction declined or failed
        }
        override fun onProcessing(currentStepMessage: String) {
            // show progress to the user
        }
    }
)

mpos.cancelTransaction()

mpos.finishTransaction()

mpos.startTransaction(
    amount = 5000L,
    transactionType = TransactionType.SALE,
    transactionCallback = myCallback,
    promptForSignature = PromptForSignature.ThresholdAmount(2500L)
)