Skip to content

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-native

The 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.statusWhenWhat 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.codeMeaning
declinedThe payer saw the bank's refusal (or an error) and left; paymentId names the payment. Your server knows the final state.
expiredThe payment expired before it was paid: create a new payment.
loadFailedThe checkout page could not be loaded and the payer closed the screen.
invalidUrlcheckoutUrl is not an https address on rais.app (or a trusted host: see Security).
cannotPresentThere was no screen to present from, or a checkout is already open.
unsupportedWebViewAndroid: the device's WebView is older than version 86.
notLinkedThe 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"
});
colorsWhat it colors
primaryThe pay button, the accents and the focus ring of the fields.
onPrimaryText on primary. When left out, 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 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.

OptionDefault
language"automatic"The payer can still switch on the page.
showsCloseButtontrueThe system back button always works on Android. Keep it unless you draw your own.
returnUrlSchemenoneYour 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 in additionalTrustedHosts.
  • 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 http is accepted for loopback addresses only, for testing against a local server: localhost and 127.0.0.1 on iOS, and localhost, 127.0.0.1 and 10.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:android or 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.

Next steps