SDK API Reference

This document describes the public API surface of the Payrails Android SDK, including payment methods, configuration, styling, translations, and event delegates. For setup and dependencies, see the Quick Start.

Looking for guides? Quick Start | Styling Guide | Troubleshooting | SDK Concepts

Table of Contents

• Getting Started
• Custom UI Payment Launcher
• Core Concepts
• Logging
• Card Payments
• Card Tokenization
• Co-Branded Cards
• Google Pay
• Redirect Payments
• Stored Instruments
• Results and Errors

Compatibility Requirements

• JDK 17
• Android minSdk 21
• Android compileSdk 35

Public Artifact

• Distributed via Maven Central
• Maven coordinate: com.payrails.android:checkout:<version>
• Additional dependency: com.payrails.android:cse:<version>

Getting Started

Create a Session

Use a Configuration built from InitData plus optional Options.

Kotlin

val initData = InitData(version = "...", data = "...")
val configuration = Configuration(initData = initData, option = Options())

// Suspend API
val session = Payrails.createSession(configuration)

// Callback API
Payrails.createSession(configuration) { result ->
    result.onSuccess { /* session ready */ }
    result.onFailure { /* initialization failed */ }
}

Java

// Java — use the callback API (suspend functions are not callable from Java)
InitData initData = new InitData("...", "...");
Configuration configuration = new Configuration(initData, new Options());

Payrails.createSession(configuration, result -> {
    if (result.isSuccess()) {
        Session session = result.getOrNull();
        // session ready
    } else {
        // initialization failed
    }
    return kotlin.Unit.INSTANCE;
});

To enable automatic SDK-managed recovery when a redirect flow is abandoned or remains non-terminal, pass onSessionExpired in Options.redirectSessionLifecycle:

val configuration = Configuration(
    initData = initData,
    option = Options(
        redirectSessionLifecycle = RedirectSessionLifecycle(
            onSessionExpired = {
                // Merchant callback: run your client-init call and return fresh init payload
                val refreshed = fetchInitPayloadFromBackend()
                InitData(version = refreshed.version, data = refreshed.data)
            }
        )
    )
)

Session-Scoped Helpers

Session is the merchant's handle to all runtime SDK operations. Keep the reference returned by createSession(...) and call query/update/instrument/payment methods on it directly.

val session = Payrails.createSession(configuration)
val instruments = session.getStoredInstruments()
val cardInstruments = session.getStoredInstruments(forType = PaymentMethod.card)

Breaking change: Payrails.getCurrentSession() is not part of the public API. Hold the Session returned by createSession(...) — methods like query, update, getStoredInstruments, deleteInstrument, updateInstrument, and getPaymentMethodConfig now live on Session. (Payment execution is not on Session; use PayrailsPaymentLauncher.)

Querying Session Data

Use Session.query() to read data from the active session.

Session.query(key)

fun <T> query(key: PayrailsQuery<T>): T

Returns the value for key from the session, or null if the requested data is not present. Never throws.

Example

val executionId: String? = session.query(PayrailsQuery.ExecutionId)
val amount: PayrailsAmount? = session.query(PayrailsQuery.Amount)
val cardConfig: PayrailsPaymentMethodConfig? =
    session.query(PayrailsQuery.PaymentMethodConfig("card"))

PayrailsQuery<T>

Sealed class of typed query keys for Session.query(), in package
com.payrails.sdk.

Removed: PayrailsQuery.AvailableRedirectMethods. Use
Session.getPaymentMethodConfig(PaymentMethodFilter.Redirect)
instead.

PayrailsAmount

data class PayrailsAmount(
    val value: String,
    val currency: String
)

Represents the current checkout amount. value is the amount in wire format (e.g.
"54.99"), consistent with AmountUpdate.value. currency is the ISO 4217 code
(e.g. "EUR").

PayrailsLink

data class PayrailsLink(
    val href: String?,
    val method: String?
)

A backend action link. href is the URL to call; method is the HTTP method (e.g.
"POST", "DELETE"). Either field may be null if not provided by the backend.

PayrailsPaymentMethodConfig

data class PayrailsPaymentMethodConfig(
    val paymentMethodCode: String,
    val description: String?,
    val displayName: String?,
    val flow: String?,
    val supportsSaveInstrument: Boolean?,
    val supportsBillingInfo: Boolean?
)

Configuration for a payment method from the active session. All fields except
paymentMethodCode are optional and sourced from the session payload.

Updating Session State

Use Session.update() to change the checkout amount after createSession() has
completed, without reinitialising the session.

Session.update(changes)

fun update(changes: PayrailsUpdate)

Updates in-memory session state. No network request is made. The updated values take
effect on the next pay() call.

Throws

Example

session.update(
    PayrailsUpdate(
        amount = AmountUpdate(value = "54.98", currency = "EUR")
    )
)
cardPaymentButton.pay() // uses the updated amount

PayrailsUpdate

data class PayrailsUpdate(
    val amount: AmountUpdate? = null
)

Container for session updates passed to Session.update(), in package
com.payrails.sdk. Each field is optional —
null means "leave unchanged". Additional fields may be added in future SDK versions
without breaking existing call sites.

Session Payment APIs

Session exposes a Google Pay capability check. Payment execution is not on Session —
it is public only via PayrailsPaymentLauncher.

Session.isGooglePayAvailable(context)

suspend fun isGooglePayAvailable(context: Context): Boolean

Returns true when Google Pay is configured for the session and the device reports
isReadyToPay() == true. Does not require a GooglePayButton to be rendered.

Executing a payment

Session exposes no public payment trigger. Payment execution is a public API only
through PayrailsPaymentLauncher.authorize(...), which owns the
Activity, the Google Pay sheet, and the 3DS / redirect Custom Tab, and handles frictionless
and step-up (3DS) outcomes uniformly. The SDK button components and the launcher delegate into
Session's internal networking; merchants do not call it directly.

The terminal outcome of any authorize(...) is the public ActionResult type.

ActionResult

sealed class ActionResult {
    data object Success : ActionResult()
    data class Failed(val failure: AuthorizationFailure) : ActionResult()
}

AuthorizationFailure

data class AuthorizationFailure(
    val code: AuthorizationFailureReason,
    val message: String,
    val rawError: Throwable? = null,
)

enum class AuthorizationFailureReason(val code: String) {
    AUTHORIZATION_ERROR, AUTHENTICATION_ERROR, USER_CANCELLED, UNKNOWN_ERROR
}

Session.getPaymentMethodConfig(filter)

fun getPaymentMethodConfig(
    filter: PaymentMethodFilter = PaymentMethodFilter.All
): List<PayrailsPaymentOption>

Returns the payment method options configured for the active session, filtered by the
supplied PaymentMethodFilter. Returns an empty list when no options match (never
null).

PaymentMethodFilter

sealed class PaymentMethodFilter {
    object All : PaymentMethodFilter()
    object Redirect : PaymentMethodFilter()
    data class Specific(val paymentMethodCode: String) : PaymentMethodFilter()
}

Example

val redirects = session.getPaymentMethodConfig(PaymentMethodFilter.Redirect)
redirects.forEach { option ->
    // option.paymentMethodCode, option.displayName
}

AmountUpdate

data class AmountUpdate(
    val value: String,
    val currency: String
)

Represents a new checkout amount. Both fields are required when updating the amount.

Note on value format: The SDK validates that value is parseable as a positive
number but does not reformat it. Pass the string in the exact format expected by your
backend (e.g. "49.99", not "4999").

Custom UI Payment Launcher

PayrailsPaymentLauncher lets you run a complete payment flow from your own button
while the SDK owns the post-tap work — opening the Google Pay sheet, the 3DS / PayPal /
redirect Custom Tab, and the polling. It is the public "bring-your-own-button" entry point —
and the only public way to execute a payment.

PayrailsPaymentLauncher

class PayrailsPaymentLauncher {
    fun authorize(
        type: PaymentMethod,
        paymentMethodCode: String? = null,
        saveInstrument: Boolean = false
    )

    fun authorize(storedInstrument: StoredInstrument)

    fun authorize(
        encryptedCardData: String,
        saveInstrument: Boolean = false
    )
}

Construct it with one of the factory functions below — never directly. Each pay(...)
call resolves to exactly one terminal ActionResult, delivered to the
onResult callback supplied at construction (user dismissal of the sheet or Custom Tab is
reported as Failed with code == USER_CANCELLED).

rememberPayrailsPaymentLauncher(session, onResult)

@Composable
fun rememberPayrailsPaymentLauncher(
    session: Session,
    onResult: (ActionResult) -> Unit
): PayrailsPaymentLauncher

Compose factory. Returns a launcher that is stable across recompositions and registers the
Google Pay Activity Result contract for the current activity. Call it during composition
(e.g. at the top of your checkout composable).

Payrails.createPaymentLauncher(activity, session, onResult)

fun Payrails.createPaymentLauncher(
    activity: ComponentActivity,
    session: Session,
    onResult: (ActionResult) -> Unit
): PayrailsPaymentLauncher

View / Activity factory. Must be called from Activity.onCreate — it registers a
Google Pay Activity Result contract, and the Android Activity Result API forbids
registration after the activity is STARTED (calling it later throws).

Example (Compose)

@Composable
fun CheckoutScreen(session: Session) {
    var status by remember { mutableStateOf<ActionResult?>(null) }
    val launcher = rememberPayrailsPaymentLauncher(session) { status = it }

    Button(onClick = { launcher.authorize(PaymentMethod.googlePay) }) { Text("Pay with Google Pay") }
}

See How to Build a Custom Pay Button for a full
dropdown-plus-single-button walkthrough.

Core Concepts

Payment Methods

PaymentMethod supports:

• PaymentMethod.card
• PaymentMethod.googlePay
• PaymentMethod.payPal
• PaymentMethod.genericRedirect

Card, Google Pay, and generic redirect flows are creatable via Payrails factories.

Options

Options configures SDK behavior:

• env: Env — Env.PRODUCTION (default) or Env.TEST
• collectMetadata: Boolean — whether the SDK collects client context metadata (default true)
• redirectSessionLifecycle: RedirectSessionLifecycle — configures automatic session recovery

Redirect Session Lifecycle (onSessionExpired)

onSessionExpired is configured once through Options.redirectSessionLifecycle and is shared for redirect-capable flows (3DS now, other redirect methods in future). The callback should run the merchant client-init call and return fresh InitData.

Behavior:

• Triggered when redirect reconciliation is classified as abandoned or stuck non-terminal.
• If callback is configured and succeeds, SDK refreshes active session/execution state automatically.
• If callback is missing/fails/returns invalid data, SDK does not continue the stale execution.
• Current payment attempt still resolves through standard failure handling (the Failed path).

Client Context Metadata

The SDK collects client context and attaches it to authorize requests under meta.clientContext by default.

Collected fields:

• osType (android)
• userAgent
• acceptHeader
• language
• screenHeight
• screenWidth
• colorDepth
• timeZoneOffset
• javaEnabled
• javaScriptEnabled

Opt-out:

val configuration = Configuration(
    initData = initData,
    option = Options(collectMetadata = false)
)

Request Headers

The SDK attaches the following headers to every API request:

The x-client-version value is generated at build time from gradle.properties (sdk.version) and compiled into the SDK as an internal constant. Merchants do not need to configure it.

Logging

The SDK uses an internal logging system with two output channels:

• In-memory log store — Always active. The SDK maintains an in-memory buffer of the last 500 log entries (with timestamps). This is used by the built-in debug viewer (DebugManager).
• Logcat — Suppressed by default. Logcat output under the tag PayrailsSDK is gated behind Log.isLoggable(), so it produces no Logcat output unless explicitly enabled.

Enabling Logcat Output

To enable SDK debug logs in Logcat, run:

adb shell setprop log.tag.PayrailsSDK DEBUG

This persists until the device reboots. After enabling, filter Logcat by the PayrailsSDK tag:

adb logcat -s PayrailsSDK:D

To disable again:

adb shell setprop log.tag.PayrailsSDK INFO

Default State

Security

The SDK never logs raw card data, tokens, or PII through its logging system. Log messages contain only operational information (e.g., payment flow steps, error descriptions).

Card Payments

CardForm + CardPaymentButton

Create a CardForm, then a CardPaymentButton. Elements are decoupled and composed explicitly.

Kotlin/Compose only. Element creation and Render() calls require Kotlin and Jetpack Compose. The delegate callbacks below are Java-compatible.

Kotlin

val cardForm = Payrails.createCardForm(
    config = CardFormConfig(
        showCardHolderName = true,
        showStoreInstrumentCheckbox = true
    )
)

val payButton = Payrails.createCardPaymentButton(
    translations = CardPaymenButtonTranslations(label = "Pay Now")
)

payButton.delegate = object : PayrailsCardPaymentButtonDelegate {
    override fun onPaymentButtonClicked(button: CardPaymentButton) {}
    override fun onAuthorizeSuccess(button: CardPaymentButton) {}
    override fun onThreeDSecureChallenge(button: CardPaymentButton) {}
    override fun onAuthorizeFailed(button: CardPaymentButton) {}
}

// In Compose
cardForm.Render()
payButton.Render()

Java — setting the delegate

payButton.setDelegate(new PayrailsCardPaymentButtonDelegate() {
    @Override
    public void onPaymentButtonClicked(CardPaymentButton button) {}
    @Override
    public void onAuthorizeSuccess(CardPaymentButton button) {}
    @Override
    public void onThreeDSecureChallenge(CardPaymentButton button) {}
    @Override
    public void onAuthorizeFailed(CardPaymentButton button) {}
});

Order does not matter. If CardPaymentButton is created before CardForm, creating CardForm later will auto-attach it to the current button (web-sdk-aligned behavior).

Behavior model (aligned with web-sdk):

• Form mode: if no stored instrument is selected, the button validates/collects card form data, then authorizes.
• Stored-instrument mode: if a stored instrument is selected, the button authorizes with that instrument and bypasses card form collection/validation.
• Form interaction reset: if the user focuses/edits card fields, the selected stored instrument is cleared and button behavior returns to form mode.
• Guardrail: if no stored instrument is selected and no card form is attached, payment does not proceed and the button emits authorization failure.

3DS redirect behavior:

• The SDK opens 3DS URLs in a Custom Tab when available, falling back to the system browser.
• On app return, the SDK polls execution status until terminal success/failure or expiry classification.
• If status remains non-terminal through reconciliation window, SDK emits authorization failure and runs onSessionExpired callback (if configured).
• On terminal success/failure, SDK performs best-effort Custom Tab close/return-to-app handling.
• Avoid using WebView for 3DS challenge pages (issuer/ACS compatibility issues, reduced isolation, unreliable deep-link returns).

CardForm Configuration

CardFormConfig controls visibility and behavior:

• showCardHolderName: Boolean
• showStoreInstrumentCheckbox: Boolean
• showSingleExpiryDateField: Boolean
• layout: List<List<CardFieldType>>?
• alwaysStoreInstrument: Boolean
• defaultStoreInstrumentState: DefaultStoreInstrumentState (checked | unchecked)
• events: CardFormEvents? (onFocus, onChange, onReady, onSaveInstrumentCheckboxChanged)
• showCardIcon: Boolean (renders built-in Payrails network icons and default field icons)
• cardIconAlignment: CardIconAlignment (left or right)
• cardFieldIcons: CardFieldIcons? (custom icon URLs per field; overrides defaults when provided)
• styles: CardFormStylesConfig?
• translations: CardTranslations?

Use CardFormConfig.defaultConfig as a baseline.
Payrails.createCardForm(...) reads save-instrument visibility only from CardFormConfig.showStoreInstrumentCheckbox; there is no separate standalone visibility argument on createCardForm(...).

Migration rules:

• defaultStoreInstrumentState defaults to unchecked. Visibility no longer implies a checked state.
• alwaysStoreInstrument = true forces submission behavior to store the instrument regardless of toggle state.

Card Form Layout Options

CardFormConfig also supports label placement and field variant:

• labelPlacement: LabelPlacement — FLOATING (default) or ABOVE. When ABOVE, labels render as separate Text composables above each field instead of floating inside the text field.
• labelSpacing: Dp? — spacing between label and field when labelPlacement = ABOVE. Default: 4.dp.
• fieldVariant: FieldVariant — OUTLINED (default) or FILLED. OUTLINED uses OutlinedTextField (full border); FILLED uses TextField (background fill with bottom indicator).

Card Form Styles

CardFormStylesConfig lets you style the wrapper, fields, labels, and errors. Key types:

• CardWrapperStyle
• CardFieldSpecificStyles
• CardStyle (alias of Style)

Card Form Spacing Tokens

CardFormStylesConfig exposes spacing tokens that replace previously hardcoded layout values:

All tokens are nullable. When null, the hardcoded default is used.

Card Translations

CardTranslations provides:

• placeholders: CardTranslations.Placeholders
• labels: CardTranslations.Labels
• error: CardTranslations.ErrorMessages

Each map is keyed by CardFieldType (alias of ElementType).

Network-Aware State

The card form exposes network-aware metadata derived from the card number:

• cardNetwork: CardNetwork (visa, mastercard, amex, discover, unknown)
• bin: String (policy-driven: first 6 or 8 digits based on card network and PAN length; empty until sufficient digits are entered)
• cvvMaxLength: Int

Field accessory behavior:

• Card number: when showCardIcon is enabled, the SDK shows the detected network icon (e.g., Visa, Mastercard). When no network is detected, a default card icon is shown (ic-card.png). Card number does not switch to the clear affordance.
• CVV: when showCardIcon is enabled, the field shows a default CVV icon (ic-cvv.png) while empty. When populated, it shows a clear affordance regardless of showCardIcon.
• Expiry date: when showCardIcon is enabled, the field shows a default expiration icon (ic-expiration.png) while empty. When populated, it shows a clear affordance regardless of showCardIcon.
• Split expiry month/year: when showCardIcon is enabled, both fields show the default expiration icon while empty. When populated, each field switches to a clear affordance independently regardless of showCardIcon.
• Cardholder name: has no default empty-state icon, but still shows a clear affordance while populated regardless of showCardIcon. Merchants can add a custom empty-state icon via cardFieldIcons.cardholderName when showCardIcon is enabled.

All default icons are loaded from the Payrails assets CDN. Merchants can override any default icon — or add a cardholder name icon — by providing custom URLs via cardFieldIcons:

CardFormConfig(
    showCardIcon = true,
    cardFieldIcons = CardFieldIcons(
        cardholderName = "https://example.com/my-name.png",  // adds a custom cardholder icon (no default)
        cardNumber = "https://example.com/my-card.png",      // replaces default card icon (network icons still show when detected)
        cvv = "https://example.com/my-cvv.png",              // replaces default CVV icon
        expiryDate = "https://example.com/my-expiry.png"     // replaces default expiry icon
    )
)

CardFieldIcons fields:

• cardholderName: String? — custom icon URL for the empty cardholder name field when showCardIcon is enabled. No default icon exists; when populated, the field shows the clear affordance instead.
• cardNumber: String? — custom icon URL for the card number field when no network is detected. Once a network is detected, the network icon takes precedence.
• cvv: String? — custom empty-state icon URL for the CVV field when showCardIcon is enabled.
• expiryDate: String? — custom empty-state icon URL for the expiration date field(s), including split expiry month/year fields, when showCardIcon is enabled.

Icon placement follows cardIconAlignment (left or right).

BIN length policy (PCI SSC FAQ 1091 aligned):

• 15-digit PANs (Amex): 6-digit BIN
• 16-digit PANs (Visa/Mastercard/Discover): 8-digit BIN
• 17–19 digit PANs or unknown networks: 6-digit BIN

Migration note: if your integration assumes a fixed 8-digit BIN, update routing/lookup logic to accept 6-digit BINs when provided. Do not infer or pad BIN length; rely on the SDK's bin value.

Card Payment Button Translations

CardPaymenButtonTranslations(label: String?) sets the pay button text.

Card Payment Button Styling

Button appearance is configured on the button component (for example via createCardPaymentButton(buttonStyle = ...)). CardFormStylesConfig no longer includes button styling.

Migration note: If you previously set CardFormStylesConfig.buttonStyle, move that styling to the button API (createCardPaymentButton(buttonStyle = ...)).
Migration note: CardPaymentButton no longer exposes instrument-specific style/translation buckets. Keep one button settings surface and configure stored-instrument list/item UI in StoredInstrumentsStyle / StoredInstrumentsTranslations.

CardButtonStyle is applied in CardPaymentButton.Render for:

• backgroundColor, textColor
• cornerRadius
• borderWidth, borderColor
• contentPadding
• font
• height, fillMaxWidth
• disabledStyle, loadingStyle (state-variant styles)
• loadingIndicatorColor

Additional design tokens:

These tokens participate in state-variant merging (disabledStyle, loadingStyle).

Stored Instrument Card Button

Single instrument mapping:

val cardForm = Payrails.createCardForm()
val button = Payrails.createCardPaymentButton(
    translations = CardPaymenButtonTranslations("Pay")
)
button.setStoredInstrument(instrument)

Coupled Wrappers (Breaking Change)

• CardPaymentForm has been removed from the element API.
• StoredInstrumentPaymentButton has been removed. Use CardPaymentButton + setStoredInstrument(...).
• The createCardPaymentButton(storedInstrument = ...) overload has been removed. Create the button first, then call setStoredInstrument(...).
• createStoredInstruments() and createStoredInstrumentView() have been removed. Use session.getStoredInstruments() to retrieve instruments and CardPaymentButton.setStoredInstrument(...) to pay with them.
• Migrate to explicit composition with CardForm + CardPaymentButton.

Card Tokenization

Save a card to the Payrails vault without initiating a payment. The tokenize flow encrypts card data using CSE, POSTs it to the vault endpoint from vaultConfiguration.links.saveInstrument, and returns a SaveInstrumentResponse containing an instrument ID for future use.

Requires vault configuration. The session init payload must include vaultConfiguration with a saveInstrument link. Contact Payrails to enable this for your merchant account.

Session.tokenize(request, options?) — suspend

Saves a reusable payment instrument from a payment method without running a payment. Mirrors the iOS SDK's session.tokenize(...).

suspend fun Session.tokenize(
    request: TokenizationRequest,
    options: TokenizeOptions = TokenizeOptions(),
): SaveInstrumentResponse

Parameters

Returns: SaveInstrumentResponse — the saved instrument record including id, status, and card metadata.

Throws

• PayrailsError.invalidCardData — card form validation failed; field errors are shown automatically on the form
• PayrailsError.missingData("Vault configuration with providerConfigId is required...") — session init payload is missing vaultConfiguration
• PayrailsError.missingData("holderReference is required...") — session init payload is missing holderReference

Defined as a Session extension in the checkout (UI) module. Import it from com.payrails.sdk; the call site is session.tokenize(...).

Example

val response = session.tokenize(
    TokenizationRequest.Card(cardForm),
    TokenizeOptions(storeInstrument = true, futureUsage = FutureUsage.CardOnFile),
)
val instrumentId = response.id

Session.tokenize(request, options?, onSuccess, onFailed, onCancelled) — callback

Callback variant for callers not using coroutines (and Java callers). Exactly one of the three callbacks is invoked, exactly once, on the main thread.

fun Session.tokenize(
    request: TokenizationRequest,
    options: TokenizeOptions = TokenizeOptions(),
    onSuccess: (SaveInstrumentResponse) -> Unit,
    onFailed: (PayrailsError) -> Unit,
    onCancelled: () -> Unit,
)

Callbacks

Example

session.tokenize(
    request = TokenizationRequest.Card(cardForm),
    onSuccess = { instrument -> /* instrument.id */ },
    onFailed = { error -> /* show error */ },
    onCancelled = { /* cancelled */ },
)

TokenizationRequest

Sealed type selecting what to tokenize. Card and Google Pay are supported (mirroring the iOS SDK's card / applePay cases).

sealed interface TokenizationRequest {
    data class Card(val cardForm: CardForm) : TokenizationRequest
    data class GooglePay(val presenter: GooglePayPresenter) : TokenizationRequest
}

GooglePayPresenter / rememberGooglePayPresenter(session)

GooglePayPresenter is an opaque handle that drives the Google Pay sheet for tokenize(TokenizationRequest.GooglePay(...)). It is obtained inside a Composable, which registers the Google Pay Activity-result launcher before the host reaches STARTED (Android requires this — a Google Pay token cannot be acquired from a plain suspend call).

interface GooglePayPresenter

@Composable
fun rememberGooglePayPresenter(session: Session): GooglePayPresenter

Returns: a GooglePayPresenter bound to the current composition.

Example

val presenter = rememberGooglePayPresenter(session)
// later, from a coroutine:
val response = session.tokenize(
    TokenizationRequest.GooglePay(presenter),
    TokenizeOptions(storeInstrument = true),
)

GooglePayTokenizeButton(...)

A compliant, Google-branded button that tokenizes via Google Pay (save, no charge). Wraps rememberGooglePayPresenter + Session.tokenize. Renders only when Google Pay is available for the session (config present and isReadyToPay succeeds). Exactly one of onSuccess/onFailed/onCancelled fires per tap, on the main thread.

@Composable
fun GooglePayTokenizeButton(
    session: Session,
    options: TokenizeOptions = TokenizeOptions(),
    style: GooglePayButtonStyle = GooglePayButtonStyle(),
    modifier: Modifier = Modifier,
    onSuccess: (SaveInstrumentResponse) -> Unit,
    onFailed: (PayrailsError) -> Unit,
    onCancelled: () -> Unit,
)

Example

GooglePayTokenizeButton(
    session = session,
    options = TokenizeOptions(storeInstrument = true),
    onSuccess = { instrument -> /* instrument.id */ },
    onFailed = { error -> /* show error */ },
    onCancelled = { /* dismissed */ },
)

CardForm.tokenize(options?)

Convenience wrapper that tokenizes this form via Session.tokenize. Equivalent to session.tokenize(TokenizationRequest.Card(cardForm), options).

suspend fun tokenize(options: TokenizeOptions = TokenizeOptions()): SaveInstrumentResponse

Parameters

Returns: SaveInstrumentResponse — the saved instrument record including id, status, and card metadata.

Throws

• PayrailsError.invalidCardData — card form validation failed; field errors are shown automatically on the form
• PayrailsError.missingData("Session is required for tokenization.") — CardForm was created without an active session
• PayrailsError.missingData("Vault configuration with providerConfigId is required...") — session init payload is missing vaultConfiguration
• PayrailsError.missingData("holderReference is required...") — session init payload is missing holderReference

Example

val response = cardForm.tokenize(
    options = TokenizeOptions(
        storeInstrument = true,
        futureUsage = FutureUsage.CardOnFile
    )
)
val instrumentId = response.id

TokenizeOptions

Options controlling card vault behavior during tokenization.

data class TokenizeOptions(
    val storeInstrument: Boolean = false,
    val futureUsage: FutureUsage = FutureUsage.CardOnFile
)

FutureUsage

Enum signaling intended future card use to the card network. Sent as part of the vault request.

enum class FutureUsage(val value: String) {
    CardOnFile("CardOnFile"),
    Subscription("Subscription"),
    UnscheduledCardOnFile("UnscheduledCardOnFile")
}

SaveInstrumentResponse

Response returned by tokenize(). Represents the saved instrument record from the vault.

@Serializable
data class SaveInstrumentResponse(
    val id: String,
    val createdAt: String,
    val holderId: String,
    val paymentMethod: String,
    val status: String,
    val data: InstrumentResponseData,
    val fingerprint: String? = null,
    val futureUsage: String? = null
)

SaveInstrumentResponse.InstrumentResponseData

InstrumentAPIResponse.Save

The Save variant of the InstrumentAPIResponse sealed class, returned when using lower-level instrument API calls. CardForm.tokenize() returns SaveInstrumentResponse directly rather than wrapping it.

sealed class InstrumentAPIResponse {
    data class Delete(val response: DeleteInstrumentResponse) : InstrumentAPIResponse()
    data class Update(val response: UpdateInstrumentResponse) : InstrumentAPIResponse()
    data class Save(val response: SaveInstrumentResponse) : InstrumentAPIResponse()
}

Google Pay

GooglePayButton

Create a GooglePayButton after initializing a session. The button handles Google Pay availability checks, payment sheet presentation, and authorization automatically.

Kotlin/Compose only. Element creation and Render() require Kotlin and Jetpack Compose. The delegate callbacks below are Java-compatible.

Kotlin

val googlePayButton = Payrails.createGooglePayButton(
    style = GooglePayButtonStyle(),
    translations = GooglePayButtonTranslations(),
    showStoreInstrumentCheckbox = false
)

googlePayButton.delegate = object : PayrailsGooglePayButtonDelegate {
    override fun onGooglePayAvailable(button: GooglePayButton) {
        // Google Pay is supported on this device
    }
    override fun onPaymentButtonClicked(button: GooglePayButton) {
        // User tapped the Google Pay button
    }
    override fun onAuthorizeSuccess(button: GooglePayButton) {
        // Payment succeeded
    }
    override fun onThreeDSecureChallenge(button: GooglePayButton) {
        // 3DS challenge started
    }
    override fun onAuthorizeFailed(button: GooglePayButton) {
        // Payment failed
    }
}

// In Compose
googlePayButton.Render()

Java — setting the delegate

googlePayButton.setDelegate(new PayrailsGooglePayButtonDelegate() {
    @Override
    public void onGooglePayAvailable(GooglePayButton button) {}
    @Override
    public void onPaymentButtonClicked(GooglePayButton button) {}
    @Override
    public void onAuthorizeSuccess(GooglePayButton button) {}
    @Override
    public void onThreeDSecureChallenge(GooglePayButton button) {}
    @Override
    public void onAuthorizeFailed(GooglePayButton button) {}
});

The button is hidden by default and becomes visible only after isReadyToPay() succeeds. The onGooglePayAvailable callback fires when the button becomes visible.

Google Pay Configuration

Google Pay configuration is provided by the Payrails backend through paymentCompositionOptions. The SDK reads clientConfig.additionalConfig for the Google Pay payment option, which contains:

• apiVersion / apiVersionMinor — Google Pay API version (defaults to 2 / 0)
• allowedPaymentMethods — Payment methods array including tokenizationSpecification (gateway configuration)
• merchantInfo — Merchant identifier and name (required in production)
• emailRequired — Whether to request the payer's email
• shippingAddressRequired / shippingAddressParameters — Shipping address collection

The countryCode for transactionInfo is extracted from meta.order.billingAddress.country.code in the execution metadata.

No client-side configuration of gateway credentials is needed. The PAYMENT_GATEWAY, gateway, and gatewayMerchantId values are provided by the backend.

GooglePayButtonStyle

GooglePayButtonStyle controls the button appearance:

GooglePayButtonTranslations

GooglePayButtonTranslations provides:

• storeInstrument: String? — Checkbox label text when showStoreInstrumentCheckbox is enabled. Defaults to "Save this payment method".

PayrailsGooglePayButtonDelegate

Store Instrument Checkbox

Pass showStoreInstrumentCheckbox = true to createGooglePayButton(...) to render a checkbox below the Google Pay button. When checked, the payment token is stored as an instrument for future use.

val googlePayButton = Payrails.createGooglePayButton(
    showStoreInstrumentCheckbox = true,
    translations = GooglePayButtonTranslations(storeInstrument = "Save for next time")
)

3DS for Google Pay

If the authorize response requires 3DS verification, the SDK opens the challenge URL in a Custom Tab and polls for the terminal result, following the same 3DS flow used for card payments. The onThreeDSecureChallenge delegate callback fires when this happens.

PayPal

PayPalButton

Create a PayPalButton after initializing a session. The button handles PayPal redirect presentation, polling for results, and authorization automatically.

Kotlin/Compose only. Element creation and Render() require Kotlin and Jetpack Compose. The delegate callbacks below are Java-compatible.

Kotlin

val payPalButton = Payrails.createPayPalButton(
    style = PayPalButtonStyle(height = 45.dp, width = 200.dp),
    translations = PayPalButtonTranslations()
)

payPalButton.delegate = object : PayrailsPayPalButtonDelegate {
    override fun onPaymentButtonClicked(button: PayPalButton) {
        // User tapped the PayPal button
    }
    override fun onAuthorizeSuccess(button: PayPalButton) {
        // Payment succeeded
    }
    override fun onAuthorizeFailed(button: PayPalButton) {
        // Payment failed or was rejected
    }
    override fun onPaymentSessionExpired(button: PayPalButton) {
        // Session is no longer usable — fetch a new init payload and call Payrails.createSession()
    }
}

// In Compose
payPalButton.Render()

PayPalButtonStyle

PayPalButtonTranslations

PayrailsPayPalButtonDelegate

Only onPaymentSessionExpired has no default implementation and must be provided — the session cannot be reused after a PayPal cancellation or expiry, so the merchant must handle this to allow retries.

Redirect Payments

GenericRedirectButton

Create a GenericRedirectButton for redirect-based payment methods (iDEAL, Bancontact, Sofort, etc.). Use Session.getPaymentMethodConfig(PaymentMethodFilter.Redirect) to discover which methods are configured.

Kotlin/Compose only. Element creation and Render() require Kotlin and Jetpack Compose. The delegate callbacks below are Java-compatible.

Discovering Available Redirect Methods

val redirectMethods: List<PayrailsPaymentOption> =
    session.getPaymentMethodConfig(PaymentMethodFilter.Redirect)

Returns an empty list if no redirect methods are configured. See
Session.getPaymentMethodConfig(filter) for the
full filter API.

PayrailsPaymentOption

Creating a Redirect Button

val button = Payrails.createGenericRedirectButton(
    translations = CardPaymenButtonTranslations(label = "Pay with iDEAL"),
    paymentMethodCode = "iDeal",
    buttonStyle = CardButtonStyle(/* optional styling */)
)

button.delegate = object : GenericRedirectPaymentButtonDelegate {
    override fun onPaymentButtonClicked(button: GenericRedirectButton) {}
    override fun onAuthorizeSuccess(button: GenericRedirectButton) {}
    override fun onAuthorizeFailed(button: GenericRedirectButton) {}
    override fun onPaymentSessionExpired(button: GenericRedirectButton) {}
    override fun onStateChanged(button: GenericRedirectButton, state: ButtonState) {}
}

// In Compose
button.Render()

Java — setting the delegate

button.setDelegate(new GenericRedirectPaymentButtonDelegate() {
    @Override
    public void onPaymentButtonClicked(GenericRedirectButton button) {}
    @Override
    public void onAuthorizeSuccess(GenericRedirectButton button) {}
    @Override
    public void onAuthorizeFailed(GenericRedirectButton button) {}
    // onPaymentSessionExpired and onStateChanged have default no-ops
});

GenericRedirectPaymentButtonDelegate

Redirect Flow Behavior

When the user taps the button, the SDK:

1. Opens the payment provider's redirect URL in a Custom Tab (falls back to system browser)
2. Polls the execution status in the background until terminal success/failure
3. Delivers the result through delegate callbacks

The redirect flow shares the same polling and session recovery infrastructure as card 3DS and Google Pay 3DS redirects. If the redirect is abandoned or remains non-terminal, or the provider reports an authentication/session-expiry error, the onPaymentSessionExpired callback (if implemented) is invoked for automatic recovery.

Button Styling

GenericRedirectButton accepts the same CardButtonStyle and CardPaymenButtonTranslations as CardPaymentButton. See Card Payment Button Styling for available properties.

Stored Instruments

StoredInstrument Interface

Each StoredInstrument exposes:

The SDK maps the backend instrument field default to StoredInstrument.isDefault.

CardInstrumentMetadata

Public data class with typed card presentation data:

Migration note: prefer displayName and cardMetadata over parsing the description string. description remains available for backwards compatibility.

Retrieving Stored Instruments

Use session.getStoredInstruments() to retrieve available instruments, then set one on the button:

Kotlin

val instruments = session.getStoredInstruments()
val cardInstruments = session.getStoredInstruments(forType = PaymentMethod.card)

// Set a stored instrument on the card payment button
payButton.setStoredInstrument(cardInstruments.first())

Java

List<StoredInstrument> instruments = session.getStoredInstruments(null);
List<StoredInstrument> cardInstruments = session.getStoredInstruments(PaymentMethod.card);

payButton.setStoredInstrument(cardInstruments.get(0));

Instrument Management APIs

Use typed methods on Session to delete or update stored instruments:

// Delete an instrument
val deleteResult: InstrumentAPIResponse.Delete = session.deleteInstrument(instrumentId)

// Update an instrument
val updateResult: InstrumentAPIResponse.Update = session.updateInstrument(
    instrumentId,
    UpdateInstrumentBody(default = true)
)

The return type is InstrumentAPIResponse, a sealed class with Delete, Update, and Save variants (capitalized). See Card Tokenization for the Save variant and the tokenize() method.

Results and Errors

Payment results are surfaced through delegate interfaces:

Card payments — PayrailsCardPaymentButtonDelegate:

• onAuthorizeSuccess — payment succeeded
• onAuthorizeFailed — payment failed (includes session-expiry outcomes from redirect reconciliation)
• onThreeDSecureChallenge — 3DS challenge started
• onPaymentButtonClicked — button was tapped

Google Pay — PayrailsGooglePayButtonDelegate:

• onAuthorizeSuccess — payment succeeded
• onAuthorizeFailed — payment failed
• onThreeDSecureChallenge — 3DS challenge started
• onPaymentButtonClicked — button was tapped
• onGooglePayAvailable — Google Pay is ready on this device

PayPal — PayrailsPayPalButtonDelegate:

• onAuthorizeSuccess — payment authorized
• onAuthorizeFailed — payment failed or was rejected
• onCancelled — user explicitly cancelled in the browser
• onPaymentSessionExpired — session expired and must be refreshed before retry (required)
• onPaymentButtonClicked — button was tapped

Generic Redirect — GenericRedirectPaymentButtonDelegate:

• onAuthorizeSuccess — payment authorized
• onAuthorizeFailed — payment failed or was rejected
• onCancelled — user explicitly cancelled the redirect
• onPaymentSessionExpired — redirect was abandoned or session expired
• onPaymentButtonClicked — button was tapped

Failed includes session-expiry outcomes from redirect reconciliation (for example browser abandoned/non-terminal timeout), including cases where automatic onSessionExpired recovery is attempted.

Errors are represented by PayrailsError (e.g., authenticationError, missingData).

Co-Branded Cards

Support for cards carrying two networks (a local scheme like mada plus an international one like mastercard). Activates only when the session is co-branded-enabled (backend featureConfig.coBrandedCardsRollout flag + a binLookup link). See the how-to and the concept.

Session.binLookup(bin)

suspend fun binLookup(bin: String): BinLookupResponse?

One-shot BIN lookup against the session's binLookup endpoint. Non-throwing: returns null on invalid input (not 6–8 digits), an inactive session, a missing endpoint, or a network error (coroutine cancellation propagates). No throttling or caching — the card form's internal as-you-type lookup handles that.

val result = session.binLookup("529741")
if (result?.localNetwork != null) { /* co-branded */ }

BinLookupResponse

IssuerCountry

CardFormEvents.onPreferredSchemeChanged

val onPreferredSchemeChanged: ((PreferredSchemeChange) -> Unit)? = null

Invoked when the shopper's preferred scheme changes: on resolution to a co-branded card (default selection), on a selection change, and once with an empty payload when co-branded state clears. De-duplicated.

PreferredSchemeChange

CardScheme

Selector UI, styling, and translations

The Card Brand selector renders automatically inside CardForm for co-branded cards. Customize:

• Text — CardTranslations.Labels.cardBrandSelectorTitle / cardBrandSelectorSubtitle (defaults "Card Brand" / "Select your preferred network").
• Look — CardFormStylesConfig.cardBrandSelector: CardBrandSelectorStyle?; see the Card Brand Selector styling reference.

Payment

When a co-branded card is paid, the selected scheme is submitted as paymentInstrumentData.preferredScheme on the authorize request; it is omitted for single-brand cards.

Further Reading

• Quick Start — Get a card payment working in 15 minutes
• How to Tokenize a Card — Save a card without charging the customer
• How to Accept Redirect Payments — Accept iDEAL, Bancontact, Sofort, and other redirect-based methods
• How to Update the Checkout Amount — Apply tips, discounts, or shipping costs after session creation
• Styling Guide — Customize form and button appearance
• SDK Concepts — Architecture, payment flows, 3DS, security model
• Troubleshooting — Common issues and solutions