# 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.

Source: https://rais.app/docs/sdk-android

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](https://github.com/rais-app/rais-android/blob/HEAD/CHANGELOG.md) · [Source](https://github.com/rais-app/rais-android)

This is the Android guide of [Mobile SDKs](https://rais.app/docs/sdks.md), 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.


> [!CAUTION]
> **Never ship a secret key in an app**
>
> The app only receives the `checkout_url`. A secret key inside an app can be extracted and lets anybody create payments and refunds in your name.


## Install

~~~kotlin
// 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:

~~~kotlin
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:

~~~kotlin
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

| Result | When | What 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. |
| `Cancelled` | The payer closed the checkout (or went back to your app) without paying. | Nothing was charged: offer to try again. |
| `Failed` with `Declined` | The 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 `Expired` | The payment expired before it was paid. | Create a new payment. |
| `Failed` with `LoadFailed` | The checkout page could not be loaded and the payer closed the screen. | Check the connection; offer to try again. |
| `Failed` with `InvalidUrl` | `checkoutUrl` is not an `https` address on `rais.app` (or a trusted host: see [Security](#security)). | Check the `checkout_url` your server sent. |
| `Failed` with `UnsupportedWebView` | This device's WebView is older than version 86. | Ask the user to update "Android System WebView". |


> [!CAUTION]
> **A result is not proof of payment**
>
> `Completed` is what the payer saw. Ask your server for the status of the order, and ship only when it says paid: it knows from the signed webhook, or by retrieving the payment. See [Webhooks](https://rais.app/docs/webhooks.md) and [Never trust the redirect](https://rais.app/docs/checkout.md#never-trust-the-redirect).


## Customize it

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

~~~kotlin
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)
~~~

| `Colors` | What it colors |
| --- | --- |
| `primary` | The pay button, the accents and the focus ring of the fields. |
| `onPrimary` | Text on `primary`. When `null`, black or white for the best contrast. |
| `background`, `surface` | The page, and cards on it. |
| `text`, `textSecondary` | Main text, and labels and hints. |
| `border` | The border of the fields. |
| `danger`, `success` | Errors, 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.

| `Configuration` | Default |  |
| --- | --- | --- |
| `appearance` | untouched | Colors, `cornerRadiusDp`, `fontFamily`, `colorScheme`. |
| `language` | `Automatic` | The payer can still switch on the page. |
| `showsCloseButton` | `true` | The system back button always lets the payer leave. Keep it unless you draw your own. |
| `returnUrlScheme` | `null` | Your app's URL scheme, when the payment's `success_url` and `cancel_url` are deep links. See [Return URLs](https://rais.app/docs/checkout.md#return-urls). |
| `additionalTrustedHosts` | empty | Extra 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](https://rais.app/docs/mobile.md).

## 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](https://rais.app/docs/testing.md#test-cards). The SDK shows the sandbox checkout of the payment. See [Test cards and sandbox](https://rais.app/docs/testing.md).
- **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](https://rais.app/docs/webhooks.md) and [Payments](https://rais.app/docs/payments.md#when-the-payer-pays-and-never-comes-back).

## Next steps


- [Mobile SDKs](https://rais.app/docs/sdks.md): how a payment flows, the security model and testing.
- [iOS SDK](https://rais.app/docs/sdk-ios.md): the same SDK for iOS.
- [React Native and Expo SDK](https://rais.app/docs/sdk-react-native.md): one API for both platforms.
- [Webhooks](https://rais.app/docs/webhooks.md): confirm every payment on your server.
