Skip to content

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 appSDKInstallNeeds
iOS, Swift: UIKit or SwiftUIRaïs for iOSRais: Swift Package Manager or CocoaPodsiOS 15+, Swift 5.9+, UIKit and SwiftUI. No dependencies
Android, Kotlin or Java: Views or Jetpack ComposeRaïs for Androidapp.rais:rais-android: GradleAndroid 7.0+ (API 24), Kotlin or Java, Views or Jetpack Compose. Depends only on AndroidX
React Native or ExpoRaïs for React Native and Expo@rais-app/react-native: npmReact 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

  1. 1Your app to Your server
    Pay for order 1042
  2. 2Your server to Raïs
    POST /v1/payments (secret key)
  3. 3Raïs to Your server
    payment with checkout_url
  4. 4Your server to Your app
    checkout_url
  5. 5Your app to Checkout screen
    Show the checkout_url
  6. 6Checkout screen to Raïs
    Hosted page: card, 3-D Secure
  7. 7Checkout screen to Your app
    completed, cancelled or failed
  8. 8Raïs to Your server
    Webhook payment.succeeded (signed)
  9. 9Your app to Your server
    What is the status of order 1042?
  10. 10Your server to Your app
    The status your server confirmed
  1. The app asks your server to start a payment for an order or a cart.
  2. Your server computes the amount and creates the payment with its secret key. See Payments.
  3. Raïs answers with the payment. Your server gives the app its checkout_url, an address like https://pay.rais.app/pay/<id>.
  4. The app shows the checkout with the SDK, and the payer pays in the checkout screen.
  5. The SDK hands the app a result: completed, cancelled or failed.
  6. 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:

ResultWhenWhat to do
CompletedThe 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.
CancelledThe payer closed the checkout (or went back to your app) without paying.Nothing was charged: offer to try again.
Failed, declinedThe 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, expiredThe payment expired before it was paid.Create a new payment.
Failed, loadFailedThe checkout page could not be loaded and the payer closed the screen.Check the connection; offer to try again.
Failed, invalidUrlThe checkout address is not an https address on rais.app (or a trusted host): see Security.Check the checkout_url your server sent.
Failed, cannotPresentiOS: 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, unsupportedWebViewAndroid: the WebView of the device is older than version 86. iOS has no such result.Ask the user to update "Android System WebView".
Failed, notLinkedReact 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:

ResultiOSAndroidReact Native
Completed.completed(payment)Completed(payment)status: "completed"
Cancelled.cancelledCancelledstatus: "cancelled"
Failed.failed(failure), failure.codeFailed, failure.codestatus: "failed", with error: { code, message, paymentId? }
declined.declinedDeclineddeclined
expired.expiredExpiredexpired
loadFailed.loadFailedLoadFailedloadFailed
invalidUrl.invalidURLInvalidUrlinvalidUrl
cannotPresent.cannotPresentnonecannotPresent
unsupportedWebViewnoneUnsupportedWebViewunsupportedWebView
notLinkednonenonenotLinked

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 language option 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 in additionalTrustedHosts. Plain http is 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:

ColourWhat it colors
primaryThe pay button, the accents and the focus ring of the fields.
onPrimaryText on primary. Left out, black or white, whichever contrasts best.
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.

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

OptioniOS (Configuration)AndroidReact Native
Coloursappearance.colorsappearance.colorsLight, appearance.colorsDarkappearance.colors, one set or light and dark
Light, dark or the deviceappearance.colorSchemeappearance.colorSchemeappearance.colorScheme
Corner radius (0 to 24)appearance.cornerRadiusappearance.cornerRadiusDpappearance.cornerRadius
Font familyappearance.fontFamilyappearance.fontFamilyappearance.fontFamily
Languagelanguagelanguagelanguage
Full screen or sheetpresentationStylenonepresentationStyle, iOS only
Close buttonshowsCloseButtonshowsCloseButtonshowsCloseButton
Your app's URL scheme, for deep link return URLsreturnURLSchemereturnUrlSchemereturnUrlScheme
Extra hosts allowed as a checkout (staging)additionalTrustedHostsadditionalTrustedHostsadditionalTrustedHosts

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.2 is the emulator's name for your computer.
  • Against a checkout served from your computer. The checkout_url of a Raïs payment is always https on pay.rais.app, so you need this only to point an SDK at a page you serve yourself. The SDKs accept plain http for the loopback addresses only: localhost and 127.0.0.1 on iOS, and localhost, 127.0.0.1 and 10.0.2.2 on 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

SDKVersionPackageChangelog
Raïs for iOS1.0.0RaisChangelog · Source
Raïs for Android1.0.0app.rais:rais-androidChangelog · Source
Raïs for React Native and Expo1.0.0@rais-app/react-nativeChangelog · 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