Rinne API Documentation

One object, CheckoutConfig, themes the SDK’s own screens and the certified PIN pad together. You pass it to Payments.getReady, and every checkout launched afterwards uses it.

Every field on this page has a control in the simulator, which also writes the Kotlin for the configuration you build and lets you walk through every screen with it.

CheckoutConfig

import com.rinne.sdk.BackgroundType
import com.rinne.sdk.CheckoutConfig
import com.rinne.sdk.PinPadType

val config = CheckoutConfig(
    primaryColor = 0xFF0E7C86.toInt(),
    headerTextColor = 0xFFFFFFFF.toInt(),
    iconColor = 0xFF0B2E31.toInt(),
    backgroundType = BackgroundType.FULL,
    displayFontResId = R.font.brand_display,
    labelFontResId = R.font.brand_text,
    merchantName = "Padaria Bela Vista",
    tapTitle = "Aproxime o cartão",
    tapSubtitle = "Cartão, celular ou relógio na parte de trás",
    pinPadType = PinPadType.SHUFFLED,
)

Int

default:"0xFF7A4CFF"

Brand colour as ARGB. Fills the header band, the primary button and the progress ring, and on the PIN pad the navigation bar, the entered-digit dots and the progress bar.

Int

default:"0xFFFFFFFF"

Text and icons drawn on primaryColor, including the PIN pad’s navigation bar text. Ignored on the screens when backgroundType is TRANSPARENT, where the header text is always the SDK’s dark ink so it stays readable on the wash. The pad’s navigation bar uses it either way.

Int

default:"0xFF15181E"

Icons on neutral surfaces, which today is the contactless artwork on the present-card screen.

BackgroundType

default:"FULL"

FULL draws a solid band of primaryColor with rounded bottom corners. TRANSPARENT draws a faint top-down wash of primaryColor fading into the page, with dark header text.

Int?

default:"null"

A @FontRes face for titles and the amount. null uses the SDK’s bundled Sora. A variable font renders its real weights; a static font renders its one weight.

Int?

default:"null"

A @FontRes face for labels, buttons and metadata. null uses the SDK’s bundled Space Grotesk.

String?

default:"null"

Shown centred in the header. null hides it.

String?

default:"null"

Headline on the present-card screen. null uses the SDK’s copy in the device language. Guidance from the card reader, such as “Present the card again”, still replaces the supporting line while it applies.

String?

default:"null"

Supporting line on the present-card screen. null uses the SDK’s copy.

PinPadType

default:"SHIFTED"

Key layout of the certified PIN pad. SHIFTED keeps the digits in their usual 1-2-3 order and moves the whole block to a different position on the pad for each transaction. SHUFFLED randomises the digit positions on every transaction. Both resist shoulder surfing; shuffling trades a little speed for it.

Branding is applied when the terminal is created. Changing CheckoutConfig after getReady has no effect until you call Payments.dispose() and prepare the terminal again, which repeats the attestation handshake. Set the brand once, at startup.

What you cannot change

The SDK fixes these so a checkout stays recognisable and an outcome cannot be recoloured into its opposite:

The neutral palette. Body text, subtitles and hairlines use the SDK’s own greys, never colours derived from your brand, so a pale brand colour cannot make the text unreadable.
The outcome colours. Approved is always green; declined, failed and cancelled are always red.
The marks. The contactless artwork and the Visa, Mastercard, Elo, Amex, Apple Pay and Google Pay marks keep their size and cannot be hidden.
The retry button. Whether it appears is decided per error code, as listed in Results and errors.
The PIN pad. Its layout, keys and spacing are the certified PIN provider’s and are fixed by PCI rules. Only its navigation bar colour and text, the entered-digit dots and the progress bar follow CheckoutConfig. Its copy is translatable through the rinne_pinpad_* resources described below, but the pad cannot be restructured, and a wrong-PIN message is always red.

Override the copy

Every string on the screens is an Android string resource prefixed rinne_, provided in English (values/) and Brazilian Portuguese (values-pt-rBR/). Override any of them in your app’s own strings.xml for each locale you ship.

res/values-pt-rBR/strings.xml

<resources>
    <string name="rinne_approved_title">Pagamento aprovado! 🎉</string>
    <string name="rinne_action_done">Voltar ao pedido</string>
</resources>

The most commonly overridden strings:

Resource	Default (pt-BR)
`rinne_tap_title`	Aproxime para pagar
`rinne_tap_subtitle`	Encoste o cartão, celular ou relógio na parte de trás deste aparelho
`rinne_pin_subtitle`	Entregue o aparelho ao cliente
`rinne_approved_title`	Pagamento aprovado
`rinne_declined_title`	Pagamento recusado
`rinne_failed_title`	Não foi possível concluir o pagamento
`rinne_action_done`	Concluir
`rinne_action_retry`	Tentar novamente
`rinne_error_declined_by_issuer`	O pagamento foi recusado. Peça outro cartão ou outra forma de pagamento ao cliente.
`rinne_pinpad_title`	Digite a senha

tapTitle and tapSubtitle on CheckoutConfig win over the string resources for those two lines, so use them for branding and the resources for translation. The PIN pad’s copy (rinne_pinpad_*) follows the device language the same way.

The header descriptor

The line under the amount is built from the CheckoutRequest, not from configuration:

Request	Descriptor (pt-BR)
`paymentMethod = DEBIT`	Débito
`paymentMethod = CREDIT`, `installments = 1`	Crédito · à vista
`paymentMethod = CREDIT`, `installments = 3` on R$ 49,90	Crédito · 3x de R$ 16,63
`type = REFUND`, `paymentMethod = CREDIT`	Estorno · Crédito · à vista

On a refund every headline changes with it: “Aproxime para estornar”, “Processando estorno”, “Estorno aprovado”.

Next steps

Simulator

Try every field, every screen and every outcome, then copy the Kotlin.

Results and errors

Every PaymentResult variant and ErrorCode, with the retry rule for each.

Overview

Android

iOS

Customization

CheckoutConfig

What you cannot change

Override the copy

The header descriptor

Next steps

Simulator

Results and errors

​CheckoutConfig

​What you cannot change

​Override the copy

​The header descriptor

​Next steps

Simulator

Results and errors

CheckoutConfig

What you cannot change

Override the copy

The header descriptor

Next steps