Rinne API Documentation

This guide takes an Android app from nothing to an approved sandbox payment using Rinne’s managed checkout screens. Plan for about thirty minutes, most of it on the backend endpoint that mints the token.

Prerequisites

Beta access from Rinne: registry credentials, a sandbox API key with the tap_on_phone.* permission (or the *.* wildcard) and a merchant enabled for contactless capture. See how to request access. Looking transactions up afterwards requires the transaction.list permission on the same key, or a separate key that holds it.
A backend you control, where the API key lives. The app never holds it.
A physical Android phone on Android 10 or newer with NFC and Google Play services.
Any contactless card, phone or watch. The sandbox reads it and never charges it.

Never put your Rinne API key in the app. The SDK authenticates with a short-lived token that your backend mints from the key. A key extracted from an APK can do everything its permissions allow, for every merchant it covers.

Add the SDK to your Gradle build

The SDK lives in a private registry. Use the registry credentials you received with your beta access and keep them in local.properties or an environment variable, never in version control.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.pkg.github.com/rinnebr/rinne-tap-android")
            credentials {
                username = providers.gradleProperty("rinne.registry.user").get()
                password = providers.gradleProperty("rinne.registry.token").get()
            }
        }
    }
}

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.pkg.github.com/rinnebr/rinne-tap-android")
            credentials {
                username = providers.gradleProperty("rinne.registry.user").get()
                password = providers.gradleProperty("rinne.registry.token").get()
            }
        }
    }
}

dependencies {
    implementation("br.com.rinne:rinne-sdk-checkout-sandbox:0.1.0-alpha.4")
}

dependencies {
    implementation 'br.com.rinne:rinne-sdk-checkout-sandbox:0.1.0-alpha.4'
}

That one line brings the whole SDK, including Payments, CheckoutConfig and PaymentResult. Pin the version named in your beta access email.If your release build runs R8, nothing more is needed: the SDK ships consumer keep rules that protect its public API.

Gradle sync resolves the SDK. A 401 from the registry means the credentials are missing or wrong.

Subclass RinneApplication

The SDK runs its cryptography in a separate process that re-enters Application.onCreate. RinneApplication handles that for you. Put your own startup work in onRinneCreate, which runs only in the real app process.

MyApp.kt

import com.rinne.sdk.RinneApplication

class MyApp : RinneApplication() {
    override fun onRinneCreate() {
        // Your usual Application.onCreate work.
    }
}

AndroidManifest.xml

<application
    android:name=".MyApp"
    ...>

The app starts and onRinneCreate runs once. Startup work placed in onCreate of another base class would run twice, once in the crypto process.

Mint an access token on your backend

Expose an endpoint your app can call with its own session. Behind it, exchange your API key for a Tap on Phone token. With a merchant’s key the body is empty. An organization key passes the company_id of the merchant the token is for; a merchant outside the organization answers 404.

curl -X POST https://api-sandbox.rinne.com.br/core/v1/terminal/token \
  -H "x-api-key: $RINNE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST https://api-sandbox.rinne.com.br/core/v1/terminal/token \
  -H "x-api-key: $RINNE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "company_id": "6d1f0c3a-9b2e-4f57-8a41-2c7e5d9b1f03" }'

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0YXBfb25fcGhvbmUifQ.c2FuZGJveC1leGFtcGxl",
  "token_type": "Bearer",
  "expires_in": 900,
  "expires_at": "2026-09-16T14:35:00.000Z",
  "scope": "tap_on_phone.bootstrap tap_on_phone.config"
}

Return the access_token to the app. The token is valid for expires_in seconds, fifteen minutes by default, and cannot call any other endpoint. A key with neither tap_on_phone.* nor *.* gets 403. The full contract is in the API reference.

The response carries an access_token and a scope that grants the Tap on Phone permissions, tap_on_phone.bootstrap and tap_on_phone.config.

Prepare the terminal

Call Payments.getReady once, typically when the operator opens the sales screen. The token provider is a suspending lambda the SDK calls once per handshake, so fetch a fresh token inside it every time rather than caching one.

SalesActivity.kt

import com.rinne.sdk.CheckoutConfig
import com.rinne.sdk.Environment
import com.rinne.sdk.Payments
import com.rinne.sdk.ReadyResult

Payments.getReady(
    context = this,
    accessTokenProvider = { backend.fetchTapOnPhoneToken() },
    config = CheckoutConfig(
        primaryColor = 0xFF0E7C86.toInt(),
        merchantName = "Padaria Bela Vista",
    ),
    environment = Environment.SANDBOX,
) { result ->
    when (result) {
        is ReadyResult.Ready -> enablePayButton()
        is ReadyResult.Failed -> showSetupError(result.code, result.message)
    }
}

Always pass environment = Environment.SANDBOX. Without it the SDK does not target the sandbox your API key belongs to, and getReady fails with ACCESS_TOKEN_REJECTED.getReady is idempotent: on a prepared terminal it returns Ready at once, so calling it on every resume is safe. CheckoutConfig is applied when the terminal is created, so to change branding call Payments.dispose() and then getReady again. Design the brand in the simulator first and paste the Kotlin it writes.The three failures worth handling at setup are:

`ErrorCode`	Meaning	Who fixes it
`ACCESS_TOKEN_REJECTED`	The token was missing, expired or lacked the Tap on Phone scope. The SDK already asked your provider for a fresh one and retried once.	Your backend
`TAP_ON_PHONE_NOT_ENABLED`	The merchant has no active affiliation with contactless capture.	Rinne
`EMV_CONFIG_UNAVAILABLE`	No card configuration is published yet for this SDK version.	Rinne

Every other code is listed in Results and errors.

The callback receives ReadyResult.Ready and Payments.isReady is true. The first handshake takes a few seconds; later ones return at once.

Launch the checkout

Register the contract once, then launch it with a CheckoutRequest per sale. The result comes back through Android’s activity-result machinery, which is what keeps it safe when the system kills your process while the payment screen is up.

SalesActivity.kt

import com.rinne.sdk.PaymentMethod
import com.rinne.sdk.PaymentResult
import com.rinne.sdk.checkout.Checkout
import com.rinne.sdk.checkout.CheckoutRequest

private val checkout = registerForActivityResult(Checkout.Contract()) { result ->
    when (result) {
        is PaymentResult.Approved -> showReceipt(result.transactionId)
        is PaymentResult.Declined -> offerAnotherMethod(result.code)
        is PaymentResult.Failed -> showError(result.code, result.message)
        is PaymentResult.Cancelled -> Unit
    }
}

fun charge(order: Order) {
    checkout.launch(
        CheckoutRequest(
            amountCents = 4990,
            paymentMethod = PaymentMethod.CREDIT,
            installments = 3,
            requestId = order.id, // for example "order-2026-000418"
            metadata = mapOf("orderId" to order.id),
        ),
    )
}

paymentMethod is required. It is the credit-or-debit question every Brazilian point of sale asks before the tap, and it is recorded as the transaction’s payment method.
requestId is required on a purchase and is your idempotency key. Reuse the same value when you retry the same sale, and use it to find the transaction on the API.
metadata is stored against the transaction and returned with it. It is capped at 4 KB and rejected when a key looks like card data.

The operator reads the outcome and taps Done before your callback fires, so a second launch never races the first.

The checkout opens over your app with your brand colour in the header and the amount you passed.

Take a test payment

Run the app on the phone, prepare the terminal, launch a sale and hold the card against the back of the phone. The screens move through Getting ready, Tap to pay, Processing payment, the certified PIN pad when the card asks for one, and Payment approved. This is the same sequence the simulator plays:Confirm the transaction reached Rinne by looking it up with the requestId you sent, through the transactions list. This call requires the transaction.list permission; a key that holds only tap_on_phone.* can mint tokens but gets 403 here.

curl "https://api-sandbox.rinne.com.br/core/v1/transactions?request_id=order-2026-000418" \
  -H "x-api-key: $RINNE_API_KEY"

The response holds one transaction with the amount you charged, payment_method matching what the operator chose, and your metadata. A transaction.created webhook fires at the same time if you have one configured.

Bridges: React Native, Flutter and Cordova

Drive the contract without registerForActivityResult

A bridge that does not own an Activity at registration time can drive the same contract by hand. The result still arrives through onActivityResult, so the process-death guarantee holds.

val intent = Checkout.Contract().createIntent(context, request)
activity.startActivityForResult(intent, RC_CHECKOUT)

// in onActivityResult:
val result = Checkout.Contract().parseResult(resultCode, data)

Serialise PaymentResult to your bridge as the variant name plus code, transactionId and message; never forward raw to a web view.

Before the first real sale

Open the antenna guide once so the merchant knows where to hold the card, and run the readiness check during onboarding rather than with a customer waiting. Both are covered in Device setup.

Troubleshooting

Symptom	Likely cause
Gradle cannot resolve `br.com.rinne`	The registry credentials are missing or wrong. Check the values from your beta access email.
`IllegalStateException` from `getReady`	The `environment` does not match the artifact you installed. Pass `Environment.SANDBOX` with the sandbox artifact.
`ACCESS_TOKEN_REJECTED`	The token came from another environment or expired, or the key lacks `tap_on_phone.*`.
`ATTESTATION_FAILED`	Emulator, rooted device or no Google Play services. Use a physical, unmodified phone.
`LOCATION_UNAVAILABLE`	The operator denied location or location services are off. The failed screen offers a button to grant it.
The card is never read	Open the antenna guide to find the antenna, and check `Payments.checkDeviceReadiness` for NFC being switched off.

Next steps

Simulator

Brand the screens, play every outcome and copy the Kotlin.

Customization

Every CheckoutConfig field and how to override the copy.

Refunds

Refund a sale with a card re-tap or from your backend.

Testing in the sandbox

Pick the outcome with the amount and verify every test on the API.

Overview

Android

iOS

Quickstart

Prerequisites

Bridges: React Native, Flutter and Cordova

Before the first real sale

Troubleshooting

Next steps

Simulator

Customization

Refunds

Testing in the sandbox

​Prerequisites

​Bridges: React Native, Flutter and Cordova

​Before the first real sale

​Troubleshooting

​Next steps

Simulator

Customization

Refunds

Testing in the sandbox

Prerequisites

Bridges: React Native, Flutter and Cordova

Before the first real sale

Troubleshooting

Next steps