Configuration

6 min

Toro Config

The Toro SDK can be configured using the ToroConfig class. The default configuration is as follows:

data class ToroConfig(
    /**
     * The mode in which to capture payments.
     * - `AUTOMATIC` (default): The payment will be captured automatically when sent for authorisation.
     * - `MANUAL`: The payment will need to be captured later manually.
     */
    val captureMode: CaptureMode = CaptureMode.AUTOMATIC,

    /**
     * Whether to collect geolocation data for transactions.
     * - `false` (default): Geolocation data will not be collected.
     * - `true`: Geolocation data will be collected.
     */
    val collectGeolocation: Boolean = false,

    /**
     * Gratuity configuration for transactions.
     * Defaults to [GratuityMode.NONE] (no tipping prompt).
     * Can be overridden per-transaction via [TransactionMetadata.gratuityConfig].
     */
    val gratuityConfig: GratuityConfig = GratuityConfig(),

    /**
     * The mode in which to capture signatures.
     * - `DEVICE` (default): The signature will be captured on the Miura device (e.g. PED).
     * If the device does not support signature capture an [ToroException.DeviceNotSupported] will be thrown.
     * - `APP`: The signature will always be captured in the app.
     */
    val signatureMode: SignatureMode = SignatureMode.DEVICE,

    /**
     * The mode in which to connect to the Miura device.
     * - `BLUETOOTH` (default): The Miura device will be connected using Bluetooth.
     * - `USB`: The Miura device will be connected using USB. USB serial must be enabled on the device.
     */
    val connectionMode: ConnectionMode = ConnectionMode.BLUETOOTH,

    /**
     * Whether to allow partial approvals for transactions.
     * Default is false.
     */
    val allowPartialApprovals: Boolean = false,

    /**
     * Use this to override strings used in messages displayed on the device
     * and in the SignatureActivity
     */
    val strings: ToroStrings = ToroStrings(),

    /**
     * Maximum time to wait for a response from the Toro gateway.
     */
    val gatewayTimeoutSeconds: Long = 30L,

    /**
     * The passphrase used to generate MACs for requests sent to the Toro gateway.
     */
    val passphrase: String? = null,

    /**
     * The policy for verifying and generating security trailers.
     */
    val securityTrailerPolicy: SecurityTrailerPolicy = SecurityTrailerPolicy.VERIFY_AND_GENERATE,

    /**
     * Merchant details
     */
    val merchant: MerchantConfig,

    /**
     * Whether to preserve the session after a transaction ends.
     * When false (default), the session is automatically closed when onComplete, onCancel, or onError is called.
     * When true, the session remains open and must be manually closed using closeSession().
     */
    val preserveSessionOnTransactionEnd: Boolean = false,
  )

To set the configuration on app initialisation, the ToroClient constructor takes a ToroConfig instance as its second parameter:

val toro = ToroClient(applicationContext, ToroConfig(...))

The ToroConfig can also be updated during runtime using the setConfig method:

toro.setConfig(ToroConfig(...))

The config cannot be updated when a transaction is in progress. Doing so will result in an IllegalStateException being thrown.

String customisation

The SDK allows integrators to customise all user facing text through the strings property in ToroConfig. This includes messages displayed directly on the PED, as well is in the built-in SignatureActivity.

val config = ToroConfig(
    strings = ToroStrings(
        // Messages presented on PED
        processingMagSwipeTransaction = "Kártya feldolgozása...",
        uploadingConfigFiles = "Konfigurációs fájlok feltöltése...",
        enterSignaturePOS = "Adja meg aláírását a POS terminálon",
        // Other PED messages here...
        
        // SignatureActivity
        signatureHeading = "Aláírás szükséges",
        signatureClear = "Törlés",
        signatureCancel = "Mégsem"
        // Other strings here...
    )
)

This allows integrators to support different languages for their application. All strings have default English values if not specified otherwise.

Note that some messages displayed on the PED are determined by the configuration files stored directly on them, such as PIN entry messages. To amend these you will need to consult the Miura documentation, one such configuration file is MPI-Dynamic.cfg.

Logging

The ToroClient automatically selects an appropriate logger based on your build variant:

Debug builds use DebugLogger by default, which logs helpful messages using the Android Log class.

Release builds use MutedLogger by default, which disables logging entirely to prevent sensitive information leaks.

You can override this default behavior by implementing the ToroLogger interface and passing your own logger to the ToroClient constructor:

class CustomLogger: ToroLogger {

    override fun d(message: String) {
        saveLogMessage("debug", message)
    }

    override fun i(message: String) {
        saveLogMessage("info", message)
    }

    override fun w(message: String) {
        saveLogMessage("warning", message)
    }

    override fun e(message: String, e: ToroException) {
        saveLogMessage("error", message, e)
    }
}

ToroClient(applicationContext, ToroConfig(), CustomLogger())

This way you can retain logs for monitoring and debugging purposes in production, which is highly recommended.

Please be cautious with logging in production as it can potentially leak sensitive information.