Skip to main content

​
Mental Model

The SDK is built around three layers:

​
Session

A Session is the foundation and the merchant’s handle to all runtime SDK operations. It holds your initialization data, manages communication with the Payrails API, and tracks payment state. You create one session per checkout flow.
The returned Session is a public class — keep the reference for the lifetime of the checkout. All runtime operations are called on it:
Session handles queries and configuration. To execute a payment you use PayrailsPaymentLauncher (see Custom UI: the launcher and the internal client). The Payrails object now exposes only createSession and UI factory methods (createCardForm, createCardPaymentButton, createPayPalButton, createGooglePayButton, createGenericRedirectButton). Most runtime operations — query, update, stored instruments, instrument management — live on the Session. Payment execution is the exception: it is public only through PayrailsPaymentLauncher. All UI elements (CardForm, CardPaymentButton, GooglePayButton, PayPalButton) are created after the session and operate within its context. If the session doesn’t exist, element creation throws an error.

​
Elements Are Decoupled

CardForm, CardPaymentButton, GooglePayButton, and PayPalButton are independent composable elements. They don’t need to be created together or rendered in the same container. The SDK links card elements automatically:
This design lets you:
  • Place the form and button in different parts of your layout
  • Create the button before the form (or vice versa)
  • Reuse the same button for both card form payments and stored instrument payments
  • Add Google Pay or PayPal alongside card payments as separate buttons

​
Delegates (Event Callbacks)

The SDK uses the delegate pattern for event callbacks. Each element type has a delegate interface: Delegates are set on the element instance, not passed as constructor parameters. This keeps the creation API clean and allows you to change handlers at runtime.
Stored instrumentsThe SDK does not provide a pre-built stored-instruments UI. Retrieve saved cards with session.getStoredInstruments(), build your own picker, and call cardPaymentButton.setStoredInstrument(instrument) to pay with one.

​
Payment Flow

​
Card Payment (Happy Path)

​
Stored Instrument Payment

When a stored instrument is selected, the button bypasses card form validation entirely:
If the user starts typing in the card form, the stored instrument selection is automatically cleared and the button returns to “form mode.”

​
Google Pay Payment

Google Pay uses a separate GooglePayButton element with its own self-contained flow:
Google Pay configuration (gateway, merchant info, allowed card networks) is provided entirely by the Payrails backend. The SDK reads it from clientConfig.additionalConfig and passes it through unchanged to the Google Pay API.

​
PayPal Payment

PayPal uses a separate PayPalButton element that routes through the same redirect infrastructure as 3DS:
Session expiry: Unlike Google Pay, when a user cancels a PayPal payment the Payrails session is expired and cannot be reused — onPaymentSessionExpired fires unconditionally after cancel. It also fires after onAuthorizeFailed when the payment attempt itself triggered session expiry (for example a failed redirect that left the session in an unusable state). The onPaymentSessionExpired callback is required — the merchant must fetch fresh init data from their backend before the user can attempt payment again. Stored instruments: Saved PayPal accounts are charged directly via the prebuilt button, or launcher.authorize(storedInstrument = storedInstrument) for a custom-UI flow. A frictionless charge opens no browser — the request goes straight to the API and returns onAuthorizeSuccess or onAuthorizeFailed.

​
3DS (3D Secure)

3DS is a security protocol that adds an extra verification step for card payments. Here’s what happens under the hood:

​
The Flow

  1. SDK requests authorization — The Payrails API may respond with a 3DS challenge URL
  2. Browser opens — The SDK opens the URL in a Chrome Custom Tab (preferred) or the system browser
  3. User completes challenge — The user interacts with their bank’s 3DS page
  4. User returns to app — The Custom Tab closes or the user navigates back
  5. SDK polls for result — The SDK checks the execution status until it reaches a terminal state
  6. Result delivered — onAuthorizeSuccess or onAuthorizeFailed fires

​
Why Custom Tabs (Not WebView)?

The SDK uses Chrome Custom Tabs instead of WebView for 3DS because:
  • Bank compatibility — Some issuer/ACS pages block or behave incorrectly in embedded WebViews
  • Security — Custom Tabs provide better isolation than WebViews, reducing compliance risk
  • User experience — Deep-link returns are more reliable from Custom Tabs; users are less likely to get stuck

​
Background Handling

When a user backgrounds your app during 3DS (e.g., switches to their banking app for OTP), the SDK uses a foreground service to keep polling alive. This ensures the payment result is captured even if the user takes time to complete the challenge.

​
Session Recovery

If the 3DS flow is abandoned (user closes the browser without completing) or remains non-terminal past the reconciliation window:
  1. The onAuthorizeFailed delegate callback fires
  2. If onSessionExpired is configured, the SDK calls it to get fresh init data
  3. The SDK refreshes the session state, allowing the user to retry
Configure this in your session setup:

​
Button Modes

CardPaymentButton operates in two mutually exclusive modes:
This means a single CardPaymentButton instance handles both new card payments and stored instrument payments. You don’t need separate buttons.

​
Custom UI: the launcher and the internal client

There is one public way to execute a payment — PayrailsPaymentLauncher — built on an internal networking client inside Session:
  • PayrailsPaymentLauncher is the public handle. You draw your own button; the launcher owns the post-tap UI hand-off. It is lifecycle-bound — construct it early (Activity.onCreate or a Compose remember) so it can register the Google Pay Activity Result contract before the host is STARTED. Because it always holds an Activity (and therefore a presenter), a single authorize(...) call handles both frictionless and 3DS/step-up outcomes — you never predict which path a charge will take.
  • Session holds the stateless networking (no Activity, no UI). Its authorize(...) overloads are internal — the launcher and the prebuilt buttons delegate into them, but they are not a public payment trigger. Session’s public surface is queries and configuration (query, update, getStoredInstruments, getPaymentMethodConfig, isGooglePayAvailable).
This mirrors the idiomatic Android “launcher owns the UI, client does the networking” split (e.g. Stripe’s PaymentLauncher, Braintree’s Launcher + Client) — with a single public trigger.

​
Why no encryption API

The launcher’s card path — authorize(encryptedCardData: String) — accepts an already-encrypted string only. The SDK deliberately exposes no client-side encryption API and no raw-card API on this surface: raw card fields never cross the public boundary, and producing the encrypted payload (via the client-side encryption library) stays the integrator’s responsibility. This keeps the PCI-sensitive surface area minimal and matches how the prebuilt CardForm already feeds an encrypted payload into the same internal flow (see Security Model).

​
Why there’s no public headless trigger

Session deliberately exposes no public authorize. Whether a charge needs a 3DS step-up is decided by the issuer at authorization time — not knowable up front — and ActionResult is terminal, with no “pending challenge” variant a presenter-less caller could resume. A public headless trigger would therefore fail unpredictably on 3DS. Instead, PayrailsPaymentLauncher (which always has a presenter) is the single public path and completes the challenge for you.

​
The Pre-Authorization Gate

Every element — card form, card button, PayPal, Google Pay, generic redirect, stored instrument and the headless launcher — starts its payment inside Session, not inside the element. That is what lets one merchant-supplied gate cover all of them rather than each element carrying its own hook: the gate lives on Session’s authorization entry points, so an element cannot accidentally skip it and a new element inherits it. The gate sits before the authorization request and before any provider UI — including the Google Pay sheet, which the UI layer opens itself, so the SDK consults the gate there rather than when the token comes back. That position is the whole point: a merchant revalidating a voucher, wallet balance or loyalty points needs the answer while the customer is still on the checkout screen, not after they have approved a payment in PayPal. Validating when the element is first drawn would answer against a basket the customer can still change; the further the tap drifts from the check, the staler the answer. Two design consequences follow. Silence is a refusal, not a pass. If the handler never returns, the SDK stops the payment after ten seconds; if it throws, the SDK stops it too. A gate whose failure mode is “authorize anyway” gives no guarantee at all, and the alternative — a button spinning indefinitely because a merchant endpoint hung — is worse than a refused payment the customer can retry. A block is not a decline. It surfaces as AuthorizationFailureReason.VALIDATION_FAILED, distinct from AUTHORIZATION_ERROR, so your own decision never lands in your analytics as an issuer rejection. Nothing reached the backend, so there is no payment attempt to reconcile. The refusal carries its own reason. RequestStartDecision.Refuse(message) rather than a bare false, because only the merchant knows why they refused — an expired voucher reads differently to a changed basket — and only they can phrase it for their customer. The message arrives as AuthorizationFailure.message, the same place all other failure text comes from, so it needs no separate channel and no correlation by executionId. The SDK’s own diagnostics for a silent or throwing handler are deliberately not delivered this way: those describe an integration fault, and an exception string may carry internals no customer should see. The handler receives paymentMethodCode and can therefore gate one method while leaving the rest untouched. It is opt-in: sessions created without it keep a fully synchronous payment path.

​
Why not onPaymentButtonClicked?

The two hooks look adjacent but answer different questions, and conflating them is the mistake worth avoiding: onPaymentButtonClicked is deliberately a notification. It cannot gate anything, because the SDK never inspects it and does not wait — work started inside it races the authorization rather than preceding it. The Web SDK draws the same line between its buttonClicked and requestStart events. See How to gate payment authorization.

​
Security Model

​
Card Data

Card data never leaves the device in plain text. The flow is:
  1. User enters card details into CardForm (Compose text fields)
  2. On payment, the SDK uses the CSE (Client-Side Encryption) library to encrypt card data
  3. Only the encrypted payload is sent to the Payrails API
  4. The SDK never stores raw card data beyond the current form state

​
Logging

The SDK has two logging channels:
  • In-memory buffer — Always active. Stores the last 500 timestamped log entries for the built-in debug viewer.
  • Logcat — Off by default. Gated behind Log.isLoggable("PayrailsSDK", Log.DEBUG), so no log output appears in production unless explicitly enabled via adb shell setprop log.tag.PayrailsSDK DEBUG.
The SDK never logs raw card data, tokens, or PII through either channel. See Troubleshooting for how to enable Logcat output during development.

​
Client Context

By default, the SDK collects device metadata (OS type, screen size, timezone, language) and attaches it to authorization requests. This data helps with fraud detection and 3DS risk assessment. You can opt out:

​
Card Tokenization

Tokenization and payment are distinct operations that share the same card entry UI but diverge at the point of submission.

​
Two paths, one form

When a user fills in the CardForm, the SDK can do one of two things with the data:
  • Payment path — the CardPaymentButton triggers form collection, encrypts card data, and calls the Payrails authorize endpoint. A charge is attempted.
  • Tokenization path — session.tokenize(TokenizationRequest.Card(cardForm)) encrypts card data and calls the Payrails vault endpoint. No charge is attempted. The result is a saved instrument with an ID. (CardForm.tokenize() is a convenience wrapper over this same path.)
The encryption step is identical in both paths. What changes is the endpoint and the intent.

​
Why separate operations?

Card vaulting without payment is a common need in commerce: onboarding flows that save a card before the first transaction, subscription setups where billing happens later, in-app wallets where the user manages saved payment methods explicitly. Bundling vaulting into the payment flow would force merchants to make a charge to save a card, which is the wrong user experience in these cases. The SDK exposes tokenization as a first-class standalone method rather than a flag on the payment call to make this separation explicit and avoid ambiguity about what a given call will do.

​
Card and Google Pay

Tokenization supports two payment methods — card and Google Pay — mirroring the iOS SDK’s card and Apple Pay cases. Both go through the same session.tokenize(request, options) call and converge on one save-instrument request; only the source of the sensitive data differs: the card path encrypts the live card fields client-side, while the Google Pay path drives the Google Pay sheet (via a presenter) and saves the returned wallet token. Other payment methods are out of scope for tokenization.

​
What storeInstrument means

TokenizeOptions.storeInstrument controls whether the vault persists the instrument for repeated use after the tokenization call:
  • storeInstrument = false (default) — the card data is encrypted and vaulted for a single use. The instrument may be usable once, then expired.
  • storeInstrument = true — the instrument is retained in the holder’s vault and can be retrieved via session.getStoredInstruments() for future payments.
For save-card-for-later flows, always set storeInstrument = true.

​
What FutureUsage signals

FutureUsage is a signal to the card network about how the merchant intends to use the stored credential. Card networks use this to apply appropriate authorization rules:
  • CardOnFile — the cardholder is present and initiating the payment (the common case for checkout)
  • Subscription — a recurring, scheduled charge that the cardholder pre-authorized
  • UnscheduledCardOnFile — a merchant-initiated charge with no fixed schedule
Setting the right value helps reduce authorization declines and chargeback risk. It is not merely cosmetic — it affects how the issuer processes subsequent charges made with the stored credential.

​
Instrument lifecycle after tokenization

A tokenized card becomes a StoredInstrument with a stable id. That ID can be used to:
  • Pay: payButton.setStoredInstrument(instrument) or launcher.authorize(storedInstrument = instrument)
  • Delete: session.deleteInstrument(instrumentId)
  • Update (e.g., set as default): session.updateInstrument(instrumentId, UpdateInstrumentBody(default = true))
The SaveInstrumentResponse returned by tokenize() is the snapshot at creation time. Retrieve the live instrument list from session.getStoredInstruments().

​
Element Lifecycle

Elements are tied to the session lifecycle:
The SDK registers an ActivityLifecycleCallbacks listener internally. When the bound Activity is destroyed (and isFinishing is true), the SDK automatically cleans up the session and element state.

​
Co-Branded Cards

Some cards are co-branded (also called co-badged, or card brand choice): they carry two payment networks — a local/domestic scheme (e.g. mada, cartesbancaires) and an international one (e.g. visa, mastercard). The shopper — or merchant preference — decides which network the payment routes over, which has real cost and acceptance implications.

​
How it works

  1. As the shopper types, the SDK looks up the BIN (first 6–8 digits) against the binLookup endpoint — throttled (~500 ms), cached, and de-duplicated, with stale responses discarded so a slow lookup can never overwrite a newer card number.
  2. The detected schemes resolve into an ordered list of canonical codes (merchant preferredSchemes first, else local-first) with a default selection.
  3. When two or more schemes are detected, the Card Brand selector renders inside CardForm; the shopper can change the selection.
  4. The selected scheme is submitted as paymentInstrumentData.preferredScheme on the payment.

​
When it activates (gating)

Co-branded handling runs only when both hold: the backend featureConfig.coBrandedCardsRollout flag is active for the session (evaluated once, then cached) and the init response includes the binLookup link. Otherwise the form behaves exactly as a single-brand card form — no selector, no extra payload.

​
Design notes

  • Uniform tiles. All scheme tiles are styled identically — the only visual difference is the check mark on the selected one — satisfying the EU IFR 2015/751 visual-balance requirement. There is no per-scheme styling.
  • Canonical string codes. Schemes are plain strings (mada, mastercard, …), not a closed enum, so new networks never require an SDK release.
  • Resilient. A failed or unavailable BIN lookup degrades silently to a non-co-branded card; the public Session.binLookup returns null rather than throwing (matching the iOS and Web SDKs).

​
Further Reading

Last modified on September 30, 2026