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

Source: https://rais.app/docs/sdk-react-native

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](https://rais.app/docs/sdk-ios.md) and [Android](https://rais.app/docs/sdk-android.md) 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](https://github.com/rais-app/rais-react-native/blob/HEAD/CHANGELOG.md) · [Source](https://github.com/rais-app/rais-react-native)

This is the React Native 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/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.


> [!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


**Expo**

~~~bash
npx expo install @rais-app/react-native
~~~

**Bare React Native**

Install the package in an app that has [Expo modules installed](https://docs.expo.dev/bare/installing-expo-modules/):

~~~bash
npm 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


**presentRaisCheckout**

~~~typescript
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;
  }
}
~~~

**useRaisCheckout**

~~~typescript
const { present, isPresenting } = useRaisCheckout();
<Button title="Pay" disabled={isPresenting} onPress={async () => { const result = await present({ checkoutUrl }); /* … */ }} />
~~~


`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](#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). |


> [!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 out keeps Raïs' value, which already has a light and a dark palette.

~~~typescript
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](https://rais.app/docs/checkout.md#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](https://rais.app/docs/sdk-ios.md#security) and [Android](https://rais.app/docs/sdk-android.md#security) 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](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 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](https://rais.app/docs/sdks.md#test-your-integration) and the guides of the [iOS](https://rais.app/docs/sdk-ios.md#test-it) and [Android](https://rais.app/docs/sdk-android.md#test-it) 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](https://docs.expo.dev/bare/installing-expo-modules/).

### 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](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 native SDK this one wraps on iOS.
- [Android SDK](https://rais.app/docs/sdk-android.md): the native SDK this one wraps on Android.
- [Webhooks](https://rais.app/docs/webhooks.md): confirm every payment on your server.
