Rinne API Documentation

Every checkout ends in exactly one PaymentResult, delivered to the callback you registered with Checkout.Contract after the operator dismisses the outcome screen. Preparing the terminal ends in exactly one ReadyResult. Both use the same eighteen ErrorCode values.

How a checkout ends

The operator reads the outcome and taps Done before your callback fires, so a second launch never races the first. Try every path in the simulator: the Scenario section picks the outcome and the error code.

PaymentResult

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

PaymentResult

Authorized. The money will move.

Show properties

String?

The card reader’s identifier for this attempt. It is not a Rinne id; find the record through transaction or your requestId.

String?

The accepted scheme: VISA, MASTERCARD or ELO.

TransactionRecord?

Rinne’s record of the transaction, with the receipt fields id, createdAt, authorizationCode, nsu and cardLastDigits. null when Rinne’s answer did not reach the phone; look the transaction up by requestId then.

PaymentResult

The issuer, the card or the device refused. The transaction completed correctly and the answer was no, so retrying the same card usually fails the same way.

Show properties

String?

The card reader’s identifier for this attempt.

ErrorCode

Why it was refused, and where: DECLINED_BY_ISSUER when the answer came back from online; DECLINED_OFFLINE, CARD_NOT_SUPPORTED or PAYMENT_METHOD_NOT_SUPPORTED when the device refused before anything went online; PIN_FAILED when the PIN was wrong. See Who refused a declined payment.

TransactionRecord?

Rinne’s record, when the refusal came back from online. null when the device refused the card, since nothing reached Rinne.

PaymentResult

Did not complete for a technical reason. This is a fault to fix, not an answer to relay to the customer. A card exchange that broke (CARD_ERROR) or authorization data that came back unusable (AUTHORIZATION_ERROR) arrives here, not as Declined, because nobody answered no.

Show properties

ErrorCode

The stable reason.

String?

Underlying detail, when there is one, such as the card reader’s cause name. Diagnostic text for your logs, never suitable to show a cardholder.

PaymentResult

Ended deliberately before an outcome existed, by the operator, the cardholder at the PIN pad or your app.

Show properties

ErrorCode

default:"CANCELLED"

CANCELLED for a real cancellation. Another code appears when the card reader abandoned the transaction for a reason worth surfacing, such as TERMINAL_NOT_READY.

Every variant also carries raw, a JSON snapshot of the card reader’s response for support triage, and diagnostics, decoded card diagnostics when the reader returned any. Neither ever contains cardholder data: the SDK withholds the card number, track data, cardholder name, expiry date, service code and cryptogram before either reaches your app.

Who refused a declined payment

The code on Declined tells you where the refusal happened, and that decides whether Rinne has a record of it:

`code`	Who refused	`transaction`
`DECLINED_BY_ISSUER`	The issuer, online	Rinne’s record, when Rinne’s answer reached the phone
`PIN_FAILED`	The issuer, because the PIN was wrong	Rinne’s record, when Rinne’s answer reached the phone
`DECLINED_OFFLINE`	The card, the phone or watch wallet, or the terminal’s own checks, on the device	`null`
`CARD_NOT_SUPPORTED`	The device: the card has no application this terminal accepts, such as American Express	`null`
`PAYMENT_METHOD_NOT_SUPPORTED`	The device: the card has no application for the chosen payment method	`null`

A null transaction with one of the last three codes means nothing reached Rinne, so there is nothing to look up or reverse. The phone cannot tell an issuer’s refusal from Rinne refusing the transaction: both arrive as DECLINED_BY_ISSUER. The case an operator can fix is a refund tapped with a card other than the sale’s. If a merchant reports declines on every card, send the requestId to support.

Print receipt fields only from Rinne’s transaction record: transaction on PaymentResult.Approved, or the record on the Rinne API when transaction is null. transactionId is the card reader’s own identifier, not a receipt field; building an authorization code or a card number from it puts fabricated data on a customer’s receipt.

After a process death

If Android kills your process while the payment screen is up, the restored screen delivers Failed with a message telling you to reconcile against the Rinne API using your requestId. It is deliberately not Cancelled: nobody cancelled anything, and the transaction may well have been captured. Reconcile before charging the customer again, with a key that holds the transaction.list permission:

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

An approved transaction in the response means the sale went through; an empty list means it did not, and you can retry with the same requestId.

ReadyResult

Payments.getReady answers with Ready or Failed(code, message). Three codes are worth handling at setup, because each one names who fixes it:

Payments.getReady(context, accessTokenProvider = { backend.fetchTapOnPhoneToken() }, config = config, environment = Environment.SANDBOX) { result ->
    when (result) {
        is ReadyResult.Ready -> enablePayButton()
        is ReadyResult.Failed -> when (result.code) {
            ErrorCode.ACCESS_TOKEN_REJECTED -> refreshSessionAndRetry()
            ErrorCode.TAP_ON_PHONE_NOT_ENABLED -> showContactRinne()
            else -> showSetupError(result.code, result.message)
        }
    }
}

`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

ErrorCode

The code on Declined, Failed, Cancelled and ReadyResult.Failed is one of eighteen values, in a fixed order that only ever grows. The managed checkout shows the operator text in the device language and offers Try again only where retrying could work. If you build your own error screen, key it off the code and use ErrorCatalog[code] for a default message, retry hint and retriable flag.

`ErrorCode`	Meaning	Retriable	Operator text
`TERMINAL_NOT_READY`	No usable terminal: never prepared, disposed, or its session ended.	Yes	The card reader is not ready yet. Wait for setup to finish, then try again.
`ATTESTATION_FAILED`	The device failed integrity checks. Usually this phone can never take payments.	No	This device cannot accept payments. Check that the device is up to date and unmodified. If it keeps happening, this device may not be supported.
`CARD_READ_TIMEOUT`	The card was never read, or reading did not finish in time.	Yes	The card was not read. Hold the card flat against the back of the phone until it beeps.
`PIN_FAILED`	PIN entry failed, timed out, or the pad could not be shown safely; or the issuer refused a wrong PIN, delivered as `Declined`.	Yes	The PIN was not accepted. Ask the customer to try again, or use another card.
`DECLINED_BY_ISSUER`	The transaction went online and the issuer refused it. Not a technical fault. Rinne refusing the transaction, such as a refund tapped with a card other than the sale’s, arrives the same way.	No	The payment was declined. Ask the customer for another card or payment method.
`NETWORK`	The device could not reach the payment network.	Yes	No connection to the payment network. Check the internet connection and try again.
`CANCELLED`	Ended deliberately by the operator, the cardholder or your app.	Yes	The payment was cancelled. Start a new payment when you are ready.
`UNKNOWN`	No more specific code applies. `raw` carries the underlying cause.	Yes	The payment could not be completed. Try again. If it keeps happening, contact support.
`LOCATION_UNAVAILABLE`	Location permission is missing or location services are off. The failed screen offers a button to grant it.	Yes	Location is required to accept payments. Turn on location and allow it for this app, then try again.
`SECURE_ENTRY_BLOCKED`	The camera or microphone is in use, the screen is being recorded, or another app is drawing over the PIN pad. The device is fine; the moment is not.	Yes	The PIN cannot be entered safely right now. Close anything recording the screen or using the camera or microphone, and any app drawing over this one, then try again.
`ACCESS_TOKEN_REJECTED`	The token from your backend was missing, expired, minted for another purpose or lacked the Tap on Phone scope. The SDK already asked for a fresh one and retried once.	Yes	The app could not sign in to accept payments. Try again. If it keeps happening, sign out and back in, or contact support.
`TAP_ON_PHONE_NOT_ENABLED`	The merchant is not enabled for contactless capture. Contact Rinne to enable it.	No	This account is not enabled to accept card payments on a phone. Contact support to enable it.
`EMV_CONFIG_UNAVAILABLE`	No card configuration is available yet for this SDK version. Contact Rinne if it persists.	Yes	This version of the app is not ready to accept payments yet. Try again later, or check for an app update.
`PAYMENT_METHOD_NOT_SUPPORTED`	The card has no application for the chosen payment method, such as a credit-only card on a debit sale. Delivered as `Declined` and refused on the device before anything goes online, so no transaction exists. The same card usually goes through with the other method. On a refund it means the card or the `paymentMethod` does not match the sale: refund with the sale’s `paymentMethod`, on the card used for the sale.	No	This card does not accept the chosen payment method. Choose another payment method or use another card.
`CARD_NOT_SUPPORTED`	The card has no application this terminal accepts, such as an American Express card. Delivered as `Declined` and refused on the device before anything goes online, so no transaction exists.	No	This card is not accepted. Ask the customer for another card.
`DECLINED_OFFLINE`	Refused on the device without going online: the card or the phone or watch wallet declined, or the terminal’s own checks refused it. Also reported for a refusal that came with no reason and never reached Rinne. Delivered as `Declined`; neither the issuer nor Rinne ever saw it, so no transaction exists.	No	The transaction was declined. Ask the customer for another card or payment method.
`CARD_ERROR`	The card was read, but the exchange with it failed: the card answered with an error, returned data the reader could not use, or was pulled away too early. Delivered as `Failed`. A card that keeps failing is likely damaged.	Yes	The card could not be read correctly. Tap the card again. If it keeps happening, use another card.
`AUTHORIZATION_ERROR`	The transaction went online, but the authorization data that came back could not be processed. Delivered as `Failed`: nobody answered no.	Yes	The authorization could not be completed. Try again. If it keeps happening, contact support.

Declined and Failed are different screens on purpose. Showing a network failure as “payment declined” tells the operator to ask for another card when the real problem is connectivity, and offers a retry guaranteed to fail the same way.

Read the SDK logs

The SDK writes its own lines to Logcat under the RinneSDK tag, in debug and release builds alike. Filter by the tag to follow a payment on a connected phone:

adb logcat -s RinneSDK

Line starts with	What it carries
`getReady`	`ready`, or `failed` with the `ErrorCode` and message; the environment, the SDK and card reader versions, and how long preparing took
`bootstrap ok`	The merchant’s company id, the terminal’s merchant id and the card configuration in use
`charge start`	The transaction type, amount, payment method, `requestId` and company id
`charge payment.approved`, `.declined`, `.failed` or `.cancelled`	The `ErrorCode`, the card reader’s cause name, the payment stage it ended on, the duration, the `requestId` and `raw`

None of these lines carries card data, a PIN, an access token or the body of a response from Rinne. The raw they log is the same card reader snapshot your app receives, with cardholder data already withheld. When you report a payment to support, send its charge payment. line; the requestId in it ties the device to Rinne’s records.

Filter by the RinneSDK tag before you save or share a log. An unfiltered Logcat dump holds every other app’s and library’s lines too, and debug logging elsewhere on the phone can include access tokens.

Next steps

Simulator

Pick any error code and see the screen, the operator text and whether Try again appears.

Device setup

Catch NFC, location and connectivity problems before a customer is waiting.

Overview

Android

iOS

Results and errors

How a checkout ends

PaymentResult

Who refused a declined payment

After a process death

ReadyResult

ErrorCode

Read the SDK logs

Next steps

Simulator

Device setup

​How a checkout ends

​PaymentResult

​Who refused a declined payment

​After a process death

​ReadyResult

​ErrorCode

​Read the SDK logs

​Next steps

Simulator

Device setup

How a checkout ends

PaymentResult

Who refused a declined payment

After a process death

ReadyResult

ErrorCode

Read the SDK logs

Next steps