# Transactions

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


```kotlin
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
)
```

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `amount` | `Long` | Yes | Transaction amount in cents (e.g., `1000` for $10.00). |
| `idempotencyId` | `String?` | No | Optional identifier used to idempotently identify transfers, authorizations, or refund requests. |
| `transactionType` | `TransactionType` | Yes | Type of transaction. Supported values: `TransactionType.SALE`, `TransactionType.REFUND`, `TransactionType.AUTHORIZATION`. |
| `transactionCallback` | `MPOSTransactionCallback` | Yes | Callback receiving the transaction result or error. |
| `splitTransfers` | `List<SplitTransfer>?` | No | Split the transaction across multiple merchants. Requires `ROLE_PARTNER` credentials. |
| `tags` | `Map<String, String>?` | No | Custom key-value metadata attached to the transaction. |
| `buyerIdentityId` | `String?` | No | Finix Identity ID of the buyer. |
| `surcharge` | `Long?` | No | Surcharge amount in cents added to the transaction. |
| `tipAmount` | `Long?` | No | Tip amount in cents. |
| `promptForSignature` | `PromptForSignature` | No | Controls when to prompt for a buyer signature. Defaults to `Never`. |


## Callback


```kotlin
interface MPOSTransactionCallback {
    fun onSuccess(result: TransactionResult?)
    fun onError(errorMessage: String)
    fun onProcessing(currentStepMessage: String)
}
```

| Callback | Trigger |
|  --- | --- |
| `onSuccess` | Transaction approved. `result` contains the transfer and authorization details. |
| `onError` | Transaction declined or failed. Check `errorMessage` for details. |
| `onProcessing` | Step in progress. Display `currentStepMessage` to the user if desired. |


## Transaction Controls

| Method | Description |
|  --- | --- |
| `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

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.


```kotlin
sealed interface PromptForSignature {
    object Always : PromptForSignature
    object Never : PromptForSignature
    class ThresholdAmount(val thresholdAmount: Long) : PromptForSignature
    object OnNetworkRecommendation : PromptForSignature
}
```

| Value | Behavior |
|  --- | --- |
| `Always` | Prompt for signature after every transaction. |
| `Never` | Never prompt for signature. Default. |
| `ThresholdAmount(amount)` | Prompt only when the transaction amount meets or exceeds the threshold. |
| `OnNetworkRecommendation` | Prompt when the card network recommends it. |