SDKs
React Native and Expo SDK
Install the Raïs SDK for React Native and Expo, show the checkout with one call or a hook, match your app's look and handle the result.
Raïs for React Native and Expo puts the Raïs payment page inside your React Native or Expo app: a native screen that shows the hosted checkout, takes the payer through card entry and 3-D Secure, and resolves with a typed result. It has light and dark mode, an appearance you can customize, and a keyboard that never makes the page jump.
It is a thin Expo Module over the native iOS and Android SDKs, so the keyboard handling and the security rules are the same ones, tested natively.
- React Native 0.73+ or Expo SDK 50+, iOS 15+, Android 7.0+ (API 24)
- No Raïs key in your app
- Version 1.0.0 · Changelog · Source
This is the React Native guide of Mobile SDKs, which explains how a payment flows between your app, your server and Raïs. Short address: rais.app/sdk/react-native.
How it works
Your server creates the payment (POST /payments with your secret key) and returns its checkout_url to the app. The app never holds a Raïs key. The app shows the checkout, and your server confirms the payment (signed webhook, or GET /payments/{id}) before anything is shipped: the result in the app is what the payer saw, not proof of payment.
Install
npx expo install @rais-app/react-nativeThe SDK has native code: it does not run in Expo Go. Make a development build (npx expo run:ios, npx expo run:android, or EAS Build) after installing it. Without the native module, presentRaisCheckout resolves with { status: "failed", error: { code: "notLinked" } } instead of crashing.
The package always needs the iOS and Android SDKs of the same major version (the Rais pod and app.rais:rais-android).
Show the checkout
import { presentRaisCheckout } from "@rais-app/react-native";
async function pay() {
const { checkoutUrl } = await myServer.startPayment(cartId); // your server created the payment
const result = await presentRaisCheckout({ checkoutUrl });
switch (result.status) {
case "completed": // paid: result.payment.id, .reference, .orderNumber. Now ask YOUR server for the order's real status
break;
case "cancelled": // the payer closed the checkout
break;
case "failed": // result.error.code: invalidUrl, loadFailed, declined, expired, cannotPresent, unsupportedWebView, notLinked
break;
}
}presentRaisCheckout never rejects for a payment outcome. The hook is for a Pay button that must not be pressed twice.
Results and errors
result.status | When | What to do |
|---|---|---|
"completed" | The payer paid and saw the receipt. result.payment.id is the payment's id, .reference the reference you gave it (absent when you gave none), .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" | result.error is { code, message, paymentId? } with a code from the table below. | Show error.message. |
error.code | Meaning |
|---|---|
declined | The payer saw the bank's refusal (or an error) and left; paymentId names the payment. Your server knows the final state. |
expired | The payment expired before it was paid: create a new payment. |
loadFailed | The checkout page could not be loaded and the payer closed the screen. |
invalidUrl | checkoutUrl is not an https address on rais.app (or a trusted host: see Security). |
cannotPresent | There was no screen to present from, or a checkout is already open. |
unsupportedWebView | Android: the device's WebView is older than version 86. |
notLinked | The native module is not part of this build (Expo Go, or the app was not rebuilt after installing the SDK). |
Customize it
Everything is optional. What you leave out keeps Raïs' value, which already has a light and a dark palette.
await presentRaisCheckout({
checkoutUrl,
language: "fr", // "automatic" (default), "en", "fr", "ar"
appearance: {
colorScheme: "automatic", // "light", "dark", or follow the device (default)
colors: {
light: { primary: "#5b5bd6" }, // or one set for both: colors: { primary: "#5b5bd6" }
dark: { primary: "#8b8bff" },
},
cornerRadius: 12, // buttons and fields (0–24)
fontFamily: "system", // "default" (Inter), "system", "serif", "monospace"
},
presentationStyle: "sheet", // iOS only: "fullScreen" (default) or "sheet"
});colors | What it colors |
|---|---|
primary | The pay button, the accents and the focus ring of the fields. |
onPrimary | Text on primary. When left out, 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 hex strings (#rgb, #rrggbb, #rrggbbaa). A color given for one palette only is used for both. Options that are wrong in code throw a TypeError (a color that is not hex, an unknown language), so you see it in development.
| Option | Default | |
|---|---|---|
language | "automatic" | The payer can still switch on the page. |
showsCloseButton | true | The system back button always works on Android. Keep it unless you draw your own. |
returnUrlScheme | none | Your app's URL scheme, when the payment's success_url and cancel_url are deep links. See Return URLs. |
additionalTrustedHosts | [] | Extra hosts allowed as a checkout (staging). rais.app and loopback are always allowed. |
Security
The security rules are the ones of the native SDKs: see the Security sections of the iOS and Android guides.
- The checkout address must be
https://…rais.app, or a host you list inadditionalTrustedHosts. - The page can talk to the app only from the checkout's own origin.
- Links that lead elsewhere open in the system browser.
- The SDK never receives card data: card entry is the hosted page.
- Plain
httpis accepted for loopback addresses only, for testing against a local server:localhostand127.0.0.1on iOS, andlocalhost,127.0.0.1and10.0.2.2(the emulator's name for your computer) on Android. A debug build must allow it: see the platform guides.
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 development build. The SDK does not run in Expo Go. Make a development build of your app (
npx expo run:ios,npx expo run:androidor EAS Build). - A checkout served from your computer. See Mobile SDKs and the guides of the iOS and Android SDKs.
Troubleshooting
notLinked
The native module is not part of this build: the app runs in Expo Go, which cannot run it, or it was not rebuilt after installing the package. Make a development build (npx expo run:ios, npx expo run:android, or EAS Build) after installing the package. In a bare app, check that Expo modules are installed.
A TypeError when I call presentRaisCheckout
An option is wrong in code, for example a color that is not a hex string, or an unknown language. It throws in development so that you see it. Colors are #rgb, #rrggbb or #rrggbbaa, and the languages are "automatic", "en", "fr" and "ar".
unsupportedWebView
On Android, 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.
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.
cannotPresent
There was no screen to present from, or a checkout is already open. Present from a screen that is showing, and use isPresenting of useRaisCheckout to keep the Pay button from being pressed while a checkout is open.
invalidUrl
The SDK checks the address before it shows anything. It must be https://…rais.app, or a host you list in additionalTrustedHosts. Pass the checkout_url your server received from Raïs exactly as it is.
The screen looks corrupted on the Android 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 iOS the web view uses a non-persistent data store. On Android the SDK clears the cookies of the checkout host at the start and at the end of each checkout.
"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.