---
title: Purchase
slug: xfTY-purchase
docTags: 
createdAt: 2025-05-12T11:36:39.070Z
---

# Starting a purchase

Once a device has been selected, you can start a transaction using the `startTransaction` method on your `ToroClient` instance:

:::CodeblockTabs
```kotlin
toro.startTransaction(
    amount = 1000,  // £10.00
    type = TransactionType.Purchase
    currencyCode = CurrencyCode.GBP,
    metadata = TransactionMetadata(
        saleReferenceId = "ORDER-123",
    ),
    onCompleted = { receipt ->
        // Handle successful transaction
        println("Transaction completed: ${receipt.transactionId}")
    },
    onCancelled = { cancellationType ->
        when (cancellationType) {
            CancellationType.ATTENDANT -> println("Transaction cancelled in app")
            CancellationType.CUSTOMER -> println("Transaction cancelled on Miura device")
        }
    },
    onError = { error ->
        when (error) {
            is DeviceNotSelected -> handleDeviceError(error)
            is DeviceConnectionFailed -> reconnectDevice()
            is DeviceDisconnected -> showReconnectionPrompt()
            else -> showErrorMessage(error.message)
        }
    },
    onGratuityConfirmed = { gratuityAmount, gratuityPercentage ->
        // Handle gratuity confirmation
        println("Gratuity added: £${gratuityAmount / 100.0} ($gratuityPercentage%)")
    }
)
```

```java
toro.startTransaction(
        1000, // £10.00
        TransactionType.Purchase,
        CurrencyCode.GBP,
        new TransactionMetadata(
                "ORDER-123",
                0,
                null,
                Collections.emptyMap()
        ),
        result -> {
            // Handle successful transaction
            System.out.println("Transaction completed: " + result);
            return null;
        },
        cancellationType -> {
            if (cancellationType == CancellationType.ATTENDANT) {
                System.out.println("Transaction cancelled in app");
            } else if (cancellationType == CancellationType.CUSTOMER) {
                System.out.println("Transaction cancelled on Miura device");
            }
            return null;
        },
        error -> {
            if (error instanceof ToroException.DeviceNotSelected) {
                handleDeviceError((ToroException.DeviceNotSelected) error);
            } else if (error instanceof ToroException.DeviceConnectionFailed) {
                reconnectDevice();
            } else if (error instanceof ToroException.DeviceDisconnected) {
                showReconnectionPrompt();
            } else {
                showErrorMessage(error.getMessage());
            }
            return null;
        },
        (gratuityAmount, gratuityPercentage) -> {
            // Handle gratuity confirmation
            System.out.println("Gratuity added: £" + (gratuityAmount / 100.0) +
                    " (" + gratuityPercentage + "%)");
            return null;
        }
);
```
:::



# Parameters

| Parameter             | Type                           | Description                                                                                                                                                     |
| --------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`              | `Int`                          | The total amount to charge in the smallest unit of the currency (e.g., pence for GBP, cents for EUR/USD). For example, £10.00 would be passed as `1000`.        |
| `type`                | `TransactionType`              | Type of transaction to be performed. Currently only `Purchase` and `Refund` are supported.                                                                      |
| `currencyCode`        | `CurrencyCode`                 | The currency code for the transaction (e.g., `CurrencyCode.GBP`, `CurrencyCode.EUR`).                                                                           |
| `metadata`            | `TransactionMetadata?`         | Optional metadata to be included with the transaction. Can include reference numbers, order IDs, or other transaction-specific data.                            |
| `onCompleted`         | `(TransactionReceipt) -> Unit` | Callback triggered when the transaction successfully completes. Provides a `TransactionReceipt` containing transaction details.                                 |
| `onCancelled`         | `(CancellationType) -> Unit`   | Callback triggered when the transaction is cancelled. The `CancellationType` indicates whether it was user-initiated or due to a timeout.                       |
| `onError`             | `(ToroException) -> Unit`      | Callback triggered when an error occurs during the transaction. See [Exceptions](docId\:lHF0wYi0IDkQDsMvsmEca)  section for possible error types.               |
| `onGratuityConfirmed` | `((Int, Int) -> Unit)?`        | Optional callback triggered when gratuity is confirmed. Provides both the gratuity amount and percentage. Only called when gratuity is enabled in `ToroConfig`. |

##