Skip to content

SDKs

Android SDK

Install the Raïs SDK for Android, show the checkout from Views or Jetpack Compose, match your app's look and handle the result.

Raïs for Android puts the Raïs payment page inside your Android app: a native screen that shows the hosted checkout, takes the payer through card entry and 3-D Secure, and hands your app a typed result. It has light and dark mode, an appearance you can customize, and a keyboard that never makes the page jump.

  • Android 7.0+ (API 24), Kotlin or Java, Views or Jetpack Compose
  • Depends only on AndroidX (activity, core, webkit), and no Raïs key in your app
  • Version 1.0.0 · Changelog · Source

This is the Android guide of Mobile SDKs, which explains how a payment flows between your app, your server and Raïs. Short address: rais.app/sdk/android.

How it works

Your server creates the payment with its secret key and gives the app the checkout_url. The app shows it with RaisCheckout, and your server confirms the payment before anything is shipped.

your app ──(1) "pay for order 1042"──▶ your server ──(2) POST /payments (secret key)──▶ Raïs
your app ◀─(3) checkout_url ───────── your server
your app ──(4) checkout.present(checkoutUrl)──▶ the payer pays in the checkout screen
your app ◀─(5) Completed / Cancelled / Failed
your app ──(6) "what is the status of order 1042?"──▶ your server (webhook / GET /payments/{id})

The result in step 5 is what the payer saw, not proof of payment: ship the order on step 6.

Install

// build.gradle.kts (app)
dependencies {
    implementation("app.rais:rais-android:1.0.0")
}

The SDK adds the INTERNET permission and one activity (not exported) to your manifest by itself.

Show the checkout

Create RaisCheckout before your activity or fragment is started (in onCreate, or as a property), exactly as you register for any activity result, then call present when the payer taps Pay:

class CartActivity : ComponentActivity() {
    private val checkout = RaisCheckout(this) { result ->
        when (result) {
            is RaisCheckout.Result.Completed -> askMyServerAbout(result.payment.id)   // paid: payment.reference, payment.orderNumber
            RaisCheckout.Result.Cancelled -> Unit                                      // the payer closed the checkout
            is RaisCheckout.Result.Failed -> show(result.failure.message)              // code: InvalidUrl, LoadFailed, Declined, Expired, UnsupportedWebView
        }
    }

    private fun onPayTapped(checkoutUrl: String) = checkout.present(checkoutUrl)   // the checkout_url from your server
}

In a Fragment: private val checkout = RaisCheckout(this) { … }, the same.

Jetpack Compose

Android only lets an activity register for a result before it is started, so create RaisCheckout as a property of the activity (not inside a composable, which may first run later, for example on a navigation destination) and hand present down:

class CartActivity : ComponentActivity() {
    private val checkout = RaisCheckout(this) { result -> /* … */ }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent { CartScreen(onPay = { checkoutUrl -> checkout.present(checkoutUrl) }) }
    }
}

@Composable
fun CartScreen(onPay: (String) -> Unit) {
    Button(onClick = { onPay(checkoutUrlFromYourServer) }) { Text("Pay") }
}

Results and errors

ResultWhenWhat to do
Completed(payment)The payer paid and saw the receipt. payment.id is the payment's id, payment.reference is the reference you gave it (null when you gave none), payment.orderNumber is on the receipt.Ask your server for the order's real status.
CancelledThe payer closed the checkout (or went back to your app) without paying.Nothing was charged: offer to try again.
Failed with DeclinedThe payer saw the bank's refusal (or an error) and left. failure.paymentId names the payment.Show failure.message. Your server knows the final state.
Failed with ExpiredThe payment expired before it was paid.Create a new payment.
Failed with LoadFailedThe checkout page could not be loaded and the payer closed the screen.Check the connection; offer to try again.
Failed with InvalidUrlcheckoutUrl is not an https address on rais.app (or a trusted host: see Security).Check the checkout_url your server sent.
Failed with UnsupportedWebViewThis device's WebView is older than version 86.Ask the user to update "Android System WebView".

Customize it

Everything is optional. What you leave null keeps Raïs' value, which already has a light and a dark palette.

val configuration = RaisCheckout.Configuration(
    appearance = RaisCheckout.Appearance(
        colorScheme = RaisCheckout.ColorScheme.Automatic,                       // Light, Dark, or follow the device (default)
        colorsLight = RaisCheckout.Colors(primary = 0xFF5B5BD6.toInt()),        // the pay button and the accents
        colorsDark = RaisCheckout.Colors(primary = 0xFF8B8BFF.toInt()),
        cornerRadiusDp = 12f,                                                   // buttons and fields (0–24)
        fontFamily = RaisCheckout.FontFamily.System,                            // Default (Inter), System, Serif, Monospace
    ),
    language = RaisCheckout.Language.French,                                    // Automatic (default), English, French, Arabic
)
checkout.present(checkoutUrl, configuration)
ColorsWhat it colors
primaryThe pay button, the accents and the focus ring of the fields.
onPrimaryText on primary. When null, black or white for the best contrast.
background, surfaceThe page, and cards on it.
text, textSecondaryMain text, and labels and hints.
borderThe border of the fields.
danger, successErrors, and the success state.

Colors are Color ints (0xAARRGGBB). Give colorsLight and colorsDark separately; the SDK picks the palette on screen and updates the open page when the device switches between light and dark.

ConfigurationDefault
appearanceuntouchedColors, cornerRadiusDp, fontFamily, colorScheme.
languageAutomaticThe payer can still switch on the page.
showsCloseButtontrueThe system back button always lets the payer leave. Keep it unless you draw your own.
returnUrlSchemenullYour app's URL scheme, when the payment's success_url and cancel_url are deep links. See Return URLs.
additionalTrustedHostsemptyExtra hosts allowed as a checkout (staging). rais.app and loopback are always allowed.

Security

  • The checkout address must be https://…rais.app, or a host you list in additionalTrustedHosts. Plain http is accepted for localhost, 127.0.0.1 and 10.0.2.2 (the emulator's name for your computer) only, so you can test against a local server: your debug build must allow cleartext traffic to it.
  • The page can talk to the app only from the checkout's own origin, never from a bank's 3-D Secure page that the same screen navigates to (WebViewCompat.addWebMessageListener with an origin rule). A device whose WebView is older than 86 gets a Failed(UnsupportedWebView) result instead of a weaker bridge.
  • TLS errors are never bypassed. Links on the checkout page that lead elsewhere (the terms, the Raïs site) open in the browser, so the payer can always come back. The system's algorithmic dark mode is switched off for the page, which has its own dark palette.
  • The SDK never receives or exposes card data: card entry is the hosted page. If you want the payment to run outside your app's process entirely, use Custom Tabs instead: see Mobile and app integrations.

Why the keyboard does not make the page jump

A hosted page inside a WebView jumps when the keyboard opens because the WebView and the page both try to bring the focused field into view, each answering the other. In this SDK the native screen decides, once: the window is edge to edge and the screen turns the keyboard's inset into the WebView's bottom margin, applied once at the start of the keyboard's animation. The keyboard never overlaps the WebView; the page is a shorter window, and it scrolls the focused field into view inside its own container. This is also why it keeps working when your app targets Android 15 (SDK 35), where adjustResize alone no longer resizes edge-to-edge windows.

For framework integrations

RaisCheckout.createIntent(context, checkoutUrl, configuration) and RaisCheckout.parseResult(resultCode, data) let a framework that starts activities itself (React Native, Flutter, Capacitor) show the checkout. Apps use RaisCheckout.

Test it

  • Sandbox. Give your server a sandbox key, and pay with a test card. The SDK shows the sandbox checkout of the payment. See Test cards and sandbox.
  • A checkout served from your computer. Plain http is accepted for localhost, 127.0.0.1 and 10.0.2.2, the emulator's name for your computer. Your debug build must allow cleartext traffic to it.
  • The example app. The example module of the repository has every option on one screen: ./gradlew :example:installDebug.

Troubleshooting

Failed(UnsupportedWebView)

The WebView of the device is older than version 86, and the SDK refuses to show the checkout instead of using a weaker bridge to the page. Ask the user to update "Android System WebView".

Failed(InvalidUrl)

The SDK checks the address before it shows anything. It must be https://…rais.app, or a host you list in additionalTrustedHosts. Plain http is accepted for localhost, 127.0.0.1 and 10.0.2.2 only. Pass the checkout_url your server received from Raïs exactly as it is.

The checkout served from my computer does not load

Use 10.0.2.2 as the host on the emulator, and make sure your debug build allows cleartext traffic to it.

Failed(LoadFailed)

The checkout page could not be loaded and the payer closed the screen. Check the connection of the device and offer to try again. For a checkout served from your computer, see the entry above.

The screen looks corrupted on the emulator

On the Android emulator, GPU rasterization of WebViews can corrupt what is drawn on screen for any WebView, plain WebViews too. Real devices have not been observed to be affected. If it happens in the emulator, restart it with different graphics settings, or test on a device.

Does anything of a payment stay on the device?

On Android the SDK clears the cookies of the checkout host at the start and at the end of each checkout. (On iOS the web view uses a non-persistent data store.)

RaisCheckout has to be created early

Android only lets an activity register for a result before it is started. Create RaisCheckout in onCreate or as a property of the activity or fragment, and never inside a composable that may first run later.

Completed, but the order is not paid in my system

The result is what the payer saw. Confirm on your server: the signed payment.succeeded webhook, or GET /payments/{id}. See Webhooks and Payments.

Next steps