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

Source: https://rais.app/docs/sdk-ios

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](https://github.com/rais-app/rais-ios/blob/HEAD/CHANGELOG.md) · [Source](https://github.com/rais-app/rais-ios)

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


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


**Swift Package Manager**

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`:

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

**CocoaPods**

~~~ruby
pod 'Rais', '~> 1.0'
~~~


## Show the checkout

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


**UIKit**

~~~swift
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)
    }
}
~~~

**async/await**

~~~swift
let result = await checkout.present(from: self)
~~~

**SwiftUI**

~~~swift
Button("Pay") { showCheckout = true }
    .raisCheckout(isPresented: $showCheckout, checkoutURL: checkoutURL) { result in
        if case .completed(let payment) = result { askMyServerAbout(payment.id) }
    }
~~~


## Results and errors

| Result | When | What 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. |
| `.cancelled` | The payer closed the checkout (or went back to your app) without paying. | Nothing was charged: offer to try again. |
| `.failed` with `.declined` | The 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 `.expired` | The payment expired before it was paid. | Create a new payment. |
| `.failed` with `.loadFailed` | The checkout page could not be loaded and the payer closed the screen. | Check the connection; offer to try again. |
| `.failed` with `.invalidURL` | `checkoutURL` is not an `https` address on `rais.app` (or a trusted host: see [Security](#security)). | Check the `checkout_url` your server sent. |
| `.failed` with `.cannotPresent` | There was no screen on top to present from. | Present from a view controller that is on screen. |


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

~~~swift
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.Colors` | What it colors |
| --- | --- |
| `primary` | The pay button, the accents and the focus ring of the fields. |
| `onPrimary` | Text on `primary`. When `nil`, 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 may be dynamic `UIColor`s: the SDK reads them for the scheme on screen and updates the open page when the device switches between light and dark.

| `Configuration` | Default |  |
| --- | --- | --- |
| `appearance` | untouched | Colors, `cornerRadius`, `fontFamily`, `colorScheme`. |
| `language` | `.automatic` | The payer can still switch on the page. |
| `presentationStyle` | `.fullScreen` | Or `.sheet`. |
| `showsCloseButton` | `true` | The system always lets the payer leave. Keep it unless you draw your own. |
| `returnURLScheme` | `nil` | 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 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](https://rais.app/docs/mobile.md).

## 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](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 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](https://rais.app/docs/webhooks.md) and [Payments](https://rais.app/docs/payments.md#when-the-payer-pays-and-never-comes-back).

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

### A link on the page opens Safari

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


- [Mobile SDKs](https://rais.app/docs/sdks.md): how a payment flows, the security model and testing.
- [Android SDK](https://rais.app/docs/sdk-android.md): the same SDK for Android.
- [React Native and Expo SDK](https://rais.app/docs/sdk-react-native.md): one API for both platforms.
- [Webhooks](https://rais.app/docs/webhooks.md): confirm every payment on your server.
