SDKs
Mobile SDKs
Show the Raïs checkout inside your iOS, Android or React Native app with a native screen, and confirm every payment on your server.
The Raïs SDKs show the hosted checkout inside your app. A native screen loads the payment page, takes the payer through card entry and 3-D Secure, and hands your app a typed result. It follows the light or dark mode of the device, takes your colours, and owns the keyboard, so the page never jumps when it opens. There is an SDK for iOS, one for Android, and one for React Native and Expo.
An SDK only shows a payment. Your server still creates it with your secret key and confirms it afterwards, exactly as it does for a website: the app never holds a Raïs key and never calls the Raïs API.
You can also reach these guides at rais.app/sdk, rais.app/sdk/ios, rais.app/sdk/android and rais.app/sdk/react-native.
Which SDK to choose
| Your app | SDK | Install | Needs |
|---|---|---|---|
| iOS, Swift: UIKit or SwiftUI | Raïs for iOS | Rais: Swift Package Manager or CocoaPods | iOS 15+, Swift 5.9+, UIKit and SwiftUI. No dependencies |
| Android, Kotlin or Java: Views or Jetpack Compose | Raïs for Android | app.rais:rais-android: Gradle | Android 7.0+ (API 24), Kotlin or Java, Views or Jetpack Compose. Depends only on AndroidX |
| React Native or Expo | Raïs for React Native and Expo | @rais-app/react-native: npm | React Native 0.73+ or Expo SDK 50+, iOS 15+, Android 7.0+ (API 24) |
- A native iOS or Android app: use the SDK of that platform.
- A React Native or Expo app: use the React Native SDK. It is a thin Expo Module over the native iOS and Android SDKs, so the keyboard handling and the security rules are the native ones. It has native code and does not run in Expo Go: make a development build.
- The payment must run outside your app's process entirely, or your framework has no SDK (Flutter, for example): open the checkout in the system browser instead. See Mobile and app integrations.
How a payment flows
- 1Your app to Your server
Pay for order 1042 - 2Your server to Raïs
POST /v1/payments (secret key) - 3Raïs to Your server
payment with checkout_url - 4Your server to Your app
checkout_url - 5Your app to Checkout screen
Show the checkout_url - 6Checkout screen to Raïs
Hosted page: card, 3-D Secure - 7Checkout screen to Your app
completed, cancelled or failed - 8Raïs to Your server
Webhook payment.succeeded (signed) - 9Your app to Your server
What is the status of order 1042? - 10Your server to Your app
The status your server confirmed
- The app asks your server to start a payment for an order or a cart.
- Your server computes the amount and creates the payment with its secret key. See Payments.
- Raïs answers with the payment. Your server gives the app its
checkout_url, an address likehttps://pay.rais.app/pay/<id>. - The app shows the checkout with the SDK, and the payer pays in the checkout screen.
- The SDK hands the app a result: completed, cancelled or failed.
- The app asks your server for the status of the order. Your server knows it from the signed webhook, or by retrieving the payment. See Webhooks.
Your server owns the amount and the secret key. The app only receives the checkout_url, and uses it as it is: it never builds it.
curl https://api.rais.app/v1/payments \
-H "Authorization: Bearer rais_sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"amount": 500000,
"description": "Order #1042",
"reference": "order-1042"
}'A minimal start-payment endpoint of your own server then returns the address to the app:
// POST /api/checkout (authenticated by your own login)
const order = await orders.createFor(req.user, req.body.cartId); // the amount is computed here
const response = await fetch("https://api.rais.app/v1/payments", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.RAIS_SECRET_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": `order-${order.id}`,
},
body: JSON.stringify({ amount: order.amount, reference: `order-${order.id}` }),
});
const payment = await response.json();
await orders.attachPayment(order.id, payment.id);
res.json({ checkoutUrl: payment.checkout_url });The result is a hint
The result an SDK gives your app is what the payer saw, not proof of payment. Ship the order only when your server says it is paid: from the signed payment.succeeded webhook, or by retrieving the payment and checking its status, amount and reference against your order. See Never trust the redirect (the rule is the same for an app) and Webhooks.
Every ending of the checkout is a typed result: completed, cancelled or failed, and a failure has a code. They mean the same in the three SDKs, and in React Native a payment outcome is a result, never a rejection:
| Result | When | What to do |
|---|---|---|
| Completed | The payer paid and saw the receipt. payment.id is the payment's id, payment.reference is the reference you gave it (nil on iOS, null on Android, absent in React Native, 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, declined | The payer saw the bank's refusal (or an error) and left. The failure names the payment: failure.paymentID on iOS, failure.paymentId on Android, error.paymentId in React Native. | Show the message. Your server knows the final state. |
Failed, expired | The payment expired before it was paid. | Create a new payment. |
Failed, loadFailed | The checkout page could not be loaded and the payer closed the screen. | Check the connection; offer to try again. |
Failed, invalidUrl | The checkout address is not an https address on rais.app (or a trusted host): see Security. | Check the checkout_url your server sent. |
Failed, cannotPresent | iOS: there was no screen on top to present from. React Native: there was no screen to present from, or a checkout is already open. Android has no such result. | Present from a screen that is showing, with no checkout open. |
Failed, unsupportedWebView | Android: the WebView of the device is older than version 86. iOS has no such result. | Ask the user to update "Android System WebView". |
Failed, notLinked | React Native: the native module is not part of this build (Expo Go, or the app was not rebuilt after installing the SDK). | Make a development build, or rebuild the app. |
Each SDK spells them its own way:
| Result | iOS | Android | React Native |
|---|---|---|---|
| Completed | .completed(payment) | Completed(payment) | status: "completed" |
| Cancelled | .cancelled | Cancelled | status: "cancelled" |
| Failed | .failed(failure), failure.code | Failed, failure.code | status: "failed", with error: { code, message, paymentId? } |
declined | .declined | Declined | declined |
expired | .expired | Expired | expired |
loadFailed | .loadFailed | LoadFailed | loadFailed |
invalidUrl | .invalidURL | InvalidUrl | invalidUrl |
cannotPresent | .cannotPresent | none | cannotPresent |
unsupportedWebView | none | UnsupportedWebView | unsupportedWebView |
notLinked | none | none | notLinked |
What an SDK does
- Shows the hosted checkout, the page at
checkout_url, in a native screen of your app: card entry and 3-D Secure included. - Returns a typed result: completed, cancelled or failed.
- Follows the light or dark mode of the device live, or stays in the one you choose, and applies your colours, corner radius and font.
- Shows the page in English, French or Arabic: the
languageoption is automatic unless you choose one. - Owns the keyboard: the native screen decides once where the page goes, so the page never jumps when the keyboard opens.
- Checks the address it is asked to show, and lets the page talk to the app only from the checkout's own origin.
What an SDK does not do
- It does not create payments, hold a key or call the Raïs API. Your server does.
- It does not prove a payment: the result is a hint. Your server confirms it with the webhook or the API.
- It never receives or exposes card data: card entry is the hosted page.
- It does not run the payment outside your app's process. For that, use the system browser: see Mobile and app integrations.
Security model
- The key stays on your server. The app has no Raïs key, and there is nothing in the SDK to put one in.
- The server owns the amount. The app never sends an amount: your server computes it and creates the payment.
- The address is checked. The checkout address must be
https://…rais.app, or a host you list inadditionalTrustedHosts. Plainhttpis accepted only for the loopback addresses of local testing. - The page talks to the app from its own origin only, never from a bank's 3-D Secure page that the same screen navigates to.
- Other links leave the screen. Links on the checkout page that lead elsewhere, such as the terms or the Raïs site, open in the system browser, so the payer can always come back.
- No card data in the SDK. It never receives or exposes it: card entry is the hosted page.
Each platform guide lists the details that are specific to it: iOS, Android and React Native.
Customize the checkout
Everything is optional. What you leave out keeps Raïs' value, which already has a light and a dark palette.
Appearance
An appearance is a set of colours, a corner radius and a font family. The colours have the same roles in the three SDKs:
| Colour | What it colors |
|---|---|
primary | The pay button, the accents and the focus ring of the fields. |
onPrimary | Text on primary. Left out, black or white, whichever contrasts best. |
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. |
The corner radius of buttons and fields goes from 0 to 24. The font family is Inter by default (default), or the system font, a serif or a monospace font.
Light and dark
By default the checkout follows the device, and changes while it is open when the device switches between light and dark. You can fix it to light or to dark. Give your colours for the scheme on screen: iOS reads dynamic colours, Android takes separate light and dark sets, and React Native takes one set or separate light and dark sets. The page switches live, and its own palettes cover every colour you leave out.
Language
The checkout speaks English, French or Arabic, with right-to-left layout for Arabic. The language option is automatic by default; the payer can still switch on the page.
Every option
| Option | iOS (Configuration) | Android | React Native |
|---|---|---|---|
| Colours | appearance.colors | appearance.colorsLight, appearance.colorsDark | appearance.colors, one set or light and dark |
| Light, dark or the device | appearance.colorScheme | appearance.colorScheme | appearance.colorScheme |
| Corner radius (0 to 24) | appearance.cornerRadius | appearance.cornerRadiusDp | appearance.cornerRadius |
| Font family | appearance.fontFamily | appearance.fontFamily | appearance.fontFamily |
| Language | language | language | language |
| Full screen or sheet | presentationStyle | none | presentationStyle, iOS only |
| Close button | showsCloseButton | showsCloseButton | showsCloseButton |
| Your app's URL scheme, for deep link return URLs | returnURLScheme | returnUrlScheme | returnUrlScheme |
| Extra hosts allowed as a checkout (staging) | additionalTrustedHosts | additionalTrustedHosts | additionalTrustedHosts |
rais.app and the loopback addresses are always allowed. Set the return URL scheme when the success_url and cancel_url of your payments are deep links into your app: see Return URLs.
What changes on the checkout page
The checkout page is hosted by Raïs. When a Raïs SDK shows it, the page adopts the colours and the theme of your app, scrolls inside one container, and reports the result to the app. A browser sees no difference, the system browser of Mobile and app integrations included.
Test your integration
- Against the sandbox. Give your server a sandbox key (
rais_sk_test_...). The payments it creates are test payments, and the SDK shows their sandbox checkout, marked "Test mode". Pay with a test card. The app does not change when you go live: only the key on your server does. - Against a server on your computer. Your app reaches your own server as it reaches any server. On the Android emulator,
10.0.2.2is the emulator's name for your computer. - Against a checkout served from your computer. The
checkout_urlof a Raïs payment is alwayshttpsonpay.rais.app, so you need this only to point an SDK at a page you serve yourself. The SDKs accept plainhttpfor the loopback addresses only:localhostand127.0.0.1on iOS, andlocalhost,127.0.0.1and10.0.2.2on Android. React Native follows the native SDK of the platform it runs on. A debug build must also allow it (see the platform guides). - Every ending. Pay with the successful card and check that your server marks the order paid once, from the webhook. Pay with a declined card. Close the checkout before paying. Kill the app during a payment: the webhook still reaches your server, and the app shows the current status of the order when it restarts.
See Test cards and sandbox for the cards and for what the sandbox does and does not do.
Versions and releases
| SDK | Version | Package | Changelog |
|---|---|---|---|
| Raïs for iOS | 1.0.0 | Rais | Changelog · Source |
| Raïs for Android | 1.0.0 | app.rais:rais-android | Changelog · Source |
| Raïs for React Native and Expo | 1.0.0 | @rais-app/react-native | Changelog · Source |
The SDKs follow semantic versioning, and each has its own changelog, linked above. The React Native SDK always requires the iOS and Android SDKs of the same major version. The checkout page is hosted by Raïs and improves without an SDK release; a change to what the page sends the app is announced first in the changelogs of the iOS and Android SDKs.
Next steps
presentRaisCheckout and useRaisCheckout, for Expo development builds and bare apps.Mobile and app integrationsthe system browser and deep links, for payments that must run outside your app.Webhooksconfirm every payment on your server.