Skip to content

SDKs

iOS SDK

Install the Raïs SDK for iOS, show the checkout from UIKit or SwiftUI, match your app's look and handle the result.

Raïs for iOS puts the Raïs payment page inside your iOS app: a native screen that shows the hosted checkout, takes the payer through card entry and 3-D Secure, and hands your app a typed result. It has light and dark mode, an appearance you can customize, and a keyboard that never makes the page jump.

  • iOS 15+, Swift 5.9+, UIKit and SwiftUI
  • No dependencies, and no Raïs key in your app
  • Version 1.0.0 · Changelog · Source

This is the iOS guide of Mobile SDKs, which explains how a payment flows between your app, your server and Raïs. Short address: rais.app/sdk/ios.

How it works

Your server creates the payment with its secret key and gives the app the checkout_url. The app shows it with RaisCheckout, and your server confirms the payment before anything is shipped.

your app ──(1) "pay for order 1042"──▶ your server ──(2) POST /payments (secret key)──▶ Raïs
your app ◀─(3) checkout_url ───────── your server
your app ──(4) RaisCheckout.present(checkoutURL)──▶ the payer pays in the checkout screen
your app ◀─(5) .completed / .cancelled / .failed
your app ──(6) "what is the status of order 1042?"──▶ your server (webhook / GET /payments/{id})

The result in step 5 is what the payer saw, not proof of payment: ship the order on step 6.

Install

In Xcode choose File ▸ Add Package Dependencies…, enter https://github.com/rais-app/rais-ios, and add the Rais library to your app target. Or in Package.swift:

.package(url: "https://github.com/rais-app/rais-ios", from: "1.0.0")

Show the checkout

Create a RaisCheckout with the checkout_url your server gave the app, and present it from a view controller:

import Rais

let checkout = RaisCheckout(checkoutURL: checkoutURL)   // the checkout_url from your server
checkout.present(from: self) { result in
    switch result {
    case .completed(let payment):  // paid: payment.id, payment.reference, payment.orderNumber
        askMyServerAbout(payment.id)
    case .cancelled:               // the payer closed the checkout
        break
    case .failed(let failure):     // failure.code: .invalidURL, .loadFailed, .declined, .expired, .cannotPresent
        show(failure.message)
    }
}

Results and errors

ResultWhenWhat to do
.completed(payment)The payer paid and saw the receipt. payment.id is the payment's id, payment.reference is the reference you gave it (nil 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 with .declinedThe payer saw the bank's refusal (or an error) and left. failure.paymentID names the payment.Show failure.message. Your server knows the final state.
.failed with .expiredThe payment expired before it was paid.Create a new payment.
.failed with .loadFailedThe checkout page could not be loaded and the payer closed the screen.Check the connection; offer to try again.
.failed with .invalidURLcheckoutURL is not an https address on rais.app (or a trusted host: see Security).Check the checkout_url your server sent.
.failed with .cannotPresentThere was no screen on top to present from.Present from a view controller that is on screen.

Customize it

Everything is optional. What you leave nil keeps Raïs' value, which already has a light and a dark palette.

var configuration = RaisCheckout.Configuration()
configuration.appearance.colorScheme = .automatic             // .light, .dark, or follow the device (default)
configuration.appearance.colors.primary = UIColor(named: "Brand")   // the pay button and the accents
configuration.appearance.colors.background = UIColor(named: "Background")
configuration.appearance.cornerRadius = 12                    // buttons and fields (0–24)
configuration.appearance.fontFamily = .system                 // .default (Inter), .system, .serif, .monospace
configuration.language = .french                              // .automatic (default), .english, .french, .arabic
configuration.presentationStyle = .sheet                      // .fullScreen (default)

let checkout = RaisCheckout(checkoutURL: checkoutURL, configuration: configuration)
Appearance.ColorsWhat it colors
primaryThe pay button, the accents and the focus ring of the fields.
onPrimaryText on primary. When nil, 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 may be dynamic UIColors: the SDK reads them for the scheme on screen and updates the open page when the device switches between light and dark.

ConfigurationDefault
appearanceuntouchedColors, cornerRadius, fontFamily, colorScheme.
language.automaticThe payer can still switch on the page.
presentationStyle.fullScreenOr .sheet.
showsCloseButtontrueThe system always lets the payer leave. Keep it unless you draw your own.
returnURLSchemenilYour 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 checkout address must be https://…rais.app, or a host you list in additionalTrustedHosts. Plain http is accepted for localhost and 127.0.0.1 only, so you can test against a local server: add NSAllowsLocalNetworking to your test app's App Transport Security settings.
  • The web view lives in its own non-persistent data store: nothing of a payment stays on the device.
  • The page can talk to the app only from the checkout's own origin, never from a bank's 3-D Secure page that the same screen navigates to.
  • Links on the checkout page that lead elsewhere (the terms, the Raïs site) open in Safari, so the payer can always come back.
  • The SDK never receives or exposes card data: card entry is the hosted page. If you want the payment to run outside your app's process entirely, use the system browser instead: see Mobile and app integrations.

Why the keyboard does not make the page jump

A hosted page inside a web view jumps when the keyboard opens because the web view, the page and the operating system all try to bring the focused field into view, each answering the others. In this SDK the native screen decides, once: the web view is pinned above the keyboard (keyboardLayoutGuide), so the keyboard never overlaps it and there is nothing to inset, pan or measure. The page is a shorter window, and it scrolls the focused field into view inside its own container.

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 checkout served from your computer. Plain http is accepted for localhost and 127.0.0.1. Add NSAllowsLocalNetworking to the App Transport Security settings of your test app.
  • The example app. The Example app of the repository has every option on one screen. Paste a checkout_url from your sandbox into it: cd Example && xcodegen generate && open RaisExample.xcodeproj.

Troubleshooting

.failed with .invalidURL

The SDK checks the address before it shows anything. It must be https://…rais.app, or a host you list in additionalTrustedHosts, and plain http is accepted for localhost and 127.0.0.1 only. Pass the checkout_url your server received from Raïs exactly as it is.

The checkout served from my computer does not load

iOS blocks plain http by default. Add NSAllowsLocalNetworking to the App Transport Security settings of your test app, and use localhost or 127.0.0.1 as the host.

.failed with .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. For a checkout served from your computer, see the entry above.

.failed with .cannotPresent

There was no screen on top to present from. Present from a view controller that is on screen.

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

The payer has to type everything again

By design. The web view lives in its own non-persistent data store, so nothing of a payment stays on the device.

Links that lead away from the checkout, such as the terms or the Raïs site, open in Safari so that the payer can always come back to your app.

I want to draw my own close button

showsCloseButton is true by default, and the system always lets the payer leave. Keep it unless you draw your own.

Next steps