Rinne API Documentation

The public surface of the SDK. Everything lives under com.rinne.sdk, and the managed checkout under com.rinne.sdk.checkout. Anything not on this page is internal and may change without notice.

Payments

object com.rinne.sdk.Payments, the terminal’s lifecycle.

fun getReady(
    context: Context,
    accessTokenProvider: suspend () -> String,
    config: CheckoutConfig = CheckoutConfig(),
    environment: Environment = Environment.default,
    installerPackageNames: List<String> = emptyList(),
    onResult: (ReadyResult) -> Unit,
)

fun dispose()
fun checkDeviceReadiness(context: Context): DeviceReadiness
fun kernelVersion(): String

val isReady: Boolean
val isPreparing: Boolean
val isCharging: Boolean
val checkoutConfig: CheckoutConfig

suspend () -> String

required

Supplies the token your backend minted at POST /v1/terminal/token. Called once per handshake and never stored. If the backend refuses it mid-handshake the SDK asks once more and retries that request, then reports ACCESS_TOKEN_REJECTED.

CheckoutConfig

default:"CheckoutConfig()"

The branding of the screens and the certified PIN pad. Applied when the terminal is created; to change it, dispose() and prepare again. See Customization.

Environment

default:"Environment.default"

The Rinne environment to prepare against. Must be one the installed artifact reaches, or getReady throws IllegalStateException.

List<String>

default:"emptyList()"

Installer packages to accept besides Google Play, for fleets distributed through a device-management tool. A build installed by an unlisted installer fails attestation in production.

(ReadyResult) -> Unit

required

Delivered once, on the main thread.

getReady is idempotent: on a prepared terminal it completes at once with Ready, and two concurrent calls share one handshake. dispose() releases the terminal so the next getReady creates a new one with the current CheckoutConfig. kernelVersion() returns the version of the certified card reader inside the SDK, as the reader reports it, and is safe to call before getReady. The managed checkout, launched through Checkout.Contract, is the supported way to take a payment during the closed beta.

Checkout.Contract

class com.rinne.sdk.checkout.Checkout.Contract : ActivityResultContract<CheckoutRequest, PaymentResult>

private val checkout = registerForActivityResult(Checkout.Contract()) { result -> /* PaymentResult */ }
checkout.launch(request)

// Without registerForActivityResult (bridges):
val intent = Checkout.Contract().createIntent(context, request)
val result = Checkout.Contract().parseResult(resultCode, data)

The only way to open the managed checkout. The result travels through Android’s activity-result machinery, so it survives the process being killed while the payment screen is up. Exactly one PaymentResult is delivered per launch, after the operator dismisses the outcome screen.

CheckoutRequest

data class com.rinne.sdk.checkout.CheckoutRequest, one sale described.

Field	Type	Default	Rules
`amountCents`	`Long`	required	Positive. BRL only.
`type`	`TransactionType`	`PURCHASE`	`REFUND` is a card re-tap for the full amount of a sale.
`paymentMethod`	`PaymentMethod`	required	The operator’s credit-or-debit choice. Recorded as the transaction’s payment method and used to select the card application.
`installments`	`Int`	`1`	Values above 1 are relayed to the acquirer.
`requestId`	`String?`	`null`	Required on a purchase, absent on a refund. Your idempotency key.
`originalRequestId`	`String?`	`null`	Required on a refund, absent on a purchase. The sale’s `requestId`.
`metadata`	`Map<String, Any?>?`	`null`	Stored with the transaction. Capped at 4 KB; rejected when a key looks like card data.

A request that breaks these rules throws IllegalArgumentException before the screen opens.

CheckoutConfig

data class com.rinne.sdk.CheckoutConfig, the branding of the screens and the PIN pad.

Field	Type	Default
`primaryColor`	`Int` (ARGB)	`0xFF7A4CFF`
`onPrimaryColor`	`Int?` (ARGB)	`null`
`iconColor`	`Int` (ARGB)	`0xFF15181E`
`backgroundType`	`BackgroundType`	`FULL`
`displayFontResId`	`@FontRes Int?`	`null`
`labelFontResId`	`@FontRes Int?`	`null`
`merchantName`	`String?`	`null`
`tapTitle`	`String?`	`null`
`tapSubtitle`	`String?`	`null`
`pinPadType`	`PinPadType`	`SHIFTED`
`buttonColor`	`Int?` (ARGB)	`null`
`onButtonColor`	`Int?` (ARGB)	`null`

A null on-colour is the SDK’s dark ink or white, whichever has the higher contrast against the colour beneath it, and a null buttonColor is primaryColor. resolvedOnPrimaryColor, resolvedButtonColor and resolvedOnButtonColor return the colours the screens draw. enum class BackgroundType { FULL, TRANSPARENT } and enum class PinPadType { SHIFTED, SHUFFLED }. What each field does, with a live preview: Customization.

TransactionType and PaymentMethod

enum class TransactionType { PURCHASE, REFUND }
enum class PaymentMethod { CREDIT, DEBIT }

PaymentResult

sealed interface com.rinne.sdk.PaymentResult, delivered once per checkout.

Variant	Fields	Meaning
`Approved`	`transactionId: String?`, `cardScheme: String?`, `transaction: TransactionRecord?`	Authorised.
`Declined`	`transactionId: String?`, `code: ErrorCode`, `transaction: TransactionRecord?`	The issuer or the card refused.
`Failed`	`code: ErrorCode`, `message: String?`	A technical fault.
`Cancelled`	`code: ErrorCode = CANCELLED`	Ended deliberately before an outcome existed.

Every variant also carries raw: String?, a JSON snapshot of the card reader’s response, and diagnostics: EmvDiagnostics?, decoded card diagnostics for support triage. Neither contains cardholder data. transactionId is the card reader’s identifier for the attempt, not a Rinne id. cardScheme is VISA, MASTERCARD or ELO. Full behaviour: Results and errors.

TransactionRecord

data class com.rinne.sdk.TransactionRecord, Rinne’s record of the transaction, relayed to the phone during authorisation.

Field	Type	Meaning
`id`	`String`	The Rinne transaction id.
`createdAt`	`Instant?`	When Rinne recorded the transaction; the receipt’s date and time.
`authorizationCode`	`String?`	The acquirer’s authorisation code, when approved.
`nsu`	`String?`	The acquirer’s sequence number (NSU), when assigned.
`cardLastDigits`	`String?`	The last digits of the card, never more than four.

It is null on the result when the transaction never reached Rinne, as with a card refused on the device, or when Rinne’s answer did not reach the phone. Look the transaction up by requestId then.

ReadyResult

sealed interface ReadyResult {
    data object Ready : ReadyResult
    data class Failed(val code: ErrorCode, val message: String? = null) : ReadyResult
}

ErrorCode and ErrorCatalog

enum class com.rinne.sdk.ErrorCode, fourteen values in a fixed order that only ever grows: TERMINAL_NOT_READY, ATTESTATION_FAILED, CARD_READ_TIMEOUT, PIN_FAILED, DECLINED_BY_ISSUER, NETWORK, CANCELLED, UNKNOWN, LOCATION_UNAVAILABLE, SECURE_ENTRY_BLOCKED, ACCESS_TOKEN_REJECTED, TAP_ON_PHONE_NOT_ENABLED, EMV_CONFIG_UNAVAILABLE, PAYMENT_METHOD_NOT_SUPPORTED. ErrorCatalog[code] returns an ErrorInfo(message, retryHint, retriable) with English defaults for hosts that build their own error screens. The managed checkout uses its own localized copy for the same codes. Meanings, retry rules and operator text: Results and errors.

Environment

enum class Environment { LOCAL, DEV, SANDBOX, PRODUCTION }

The sandbox artifact reaches LOCAL, DEV and SANDBOX; the production artifact reaches PRODUCTION only. Environment.supported lists what the installed artifact reaches and Environment.default is its default, which for the sandbox artifact is DEV, so pass SANDBOX explicitly.

AntennaSetup.Contract

class com.rinne.sdk.checkout.AntennaSetup.Contract : ActivityResultContract<Unit, Boolean> Opens the antenna guide. Needs no terminal or token, reads no card data, inherits the last CheckoutConfig, and returns true when the merchant confirms the position with a test tap. See Device setup.

Nfc

object com.rinne.sdk.Nfc, platform helpers with no kernel and no credentials.

Member	Returns	Notes
`status(context)`	`NfcStatus`	`READY`, `DISABLED` or `UNAVAILABLE`.
`antennaInfo(context)`	`AntennaInfo?`	`null` below API 34 or when the device reports no antennas. Never guess a position in that case.
`enableTapTest(activity) { }`	`Boolean`	`false`, starting nothing, when the device has no NFC. Fires the callback when any contactless card touches the antenna; reads nothing. Pair with `disableTapTest(activity)` in `onPause`.
`keepAwake(activity)`	`AutoCloseable`	Keeps the screen on until closed. The managed checkout does this itself.

data class AntennaInfo(
    val deviceWidthMm: Int,
    val deviceHeightMm: Int,
    val foldable: Boolean,
    val antennas: List<Antenna>,   // Antenna(xMm, yMm), from the top-left of the back
)

DeviceReadiness

Returned by Payments.checkDeviceReadiness(context).

data class DeviceReadiness(val checks: List<ReadinessCheck>) {
    val blocking: List<ReadinessCheck>   // outcome FAIL on a blocking check
    val warnings: List<ReadinessCheck>   // outcome WARN
    val isReady: Boolean                 // no blocking failures
}

data class ReadinessCheck(val id: ReadinessCheckId, val outcome: ReadinessOutcome, val detail: String? = null)

enum class ReadinessCheckId { OS_PATCH_LEVEL, PLAY_SERVICES, CONNECTIVITY, NFC, LOCATION }
enum class ReadinessOutcome { PASS, WARN, FAIL }

OS_PATCH_LEVEL only warns; the other four block. Readiness is not attestation: a device can pass every check and still be refused with ATTESTATION_FAILED.

RinneApplication

abstract class com.rinne.sdk.RinneApplication : Application. Subclass it and put your startup work in onRinneCreate(). onCreate() is final: the card reader runs its cryptography in an isolated process that re-enters Application.onCreate, and the SDK returns early there before any host code runs.

Next steps

Quickstart

Every type above, in the order you use them.

Simulator

See what each CheckoutConfig and CheckoutRequest field does on the screens.

Overview

Android

iOS

API reference

Payments

Checkout.Contract

CheckoutRequest

CheckoutConfig

TransactionType and PaymentMethod

PaymentResult

TransactionRecord

ReadyResult

ErrorCode and ErrorCatalog

Environment

AntennaSetup.Contract

Nfc

DeviceReadiness

RinneApplication

Next steps

Quickstart

Simulator

​Payments

​Checkout.Contract

​CheckoutRequest

​CheckoutConfig

​TransactionType and PaymentMethod

​PaymentResult

​TransactionRecord

​ReadyResult

​ErrorCode and ErrorCatalog

​Environment

​AntennaSetup.Contract

​Nfc

​DeviceReadiness

​RinneApplication

​Next steps

Quickstart

Simulator

Payments

Checkout.Contract

CheckoutRequest

CheckoutConfig

TransactionType and PaymentMethod

PaymentResult

TransactionRecord

ReadyResult

ErrorCode and ErrorCatalog

Environment

AntennaSetup.Contract

Nfc

DeviceReadiness

RinneApplication

Next steps