iOS SDK

Accept card payments and Apple Pay in your iOS app with lite’s Payment Sheet or embeddable payment form.

Overview

The lite iOS SDK lets customers pay without leaving your app. It provides two integration options:

Payment Sheet: a complete checkout presented over your existing interface.
Embeddable payment form: the same lite-managed checkout UI placed inside your SwiftUI layout.

The SDK collects and validates card details, encrypts them on the device, tokenizes the payment method, and submits the payment to lite. Raw card details are not sent to your server. Individual card elements are not part of the supported iOS SDK. Use the Payment Sheet for the quickest integration, or the embeddable form when you need control over where SDK appears inside your checkout page. The iOS SDK supports card payments, saved cards, Apple Pay, and 3D Secure.

How it works

Your server creates a checkout session with the lite API and receives a session secret.
Your app gives the session secret to the SDK.
The SDK loads the session and displays the payment methods enabled for it.
The customer enters or selects a payment method.
The SDK encrypts new card data, tokenizes the payment method, and submits the payment.
If required, the SDK presents and completes 3D Secure automatically.
Your server confirms the final payment result before fulfilling the order.

Before you begin

You need:

A lite account with a configured channel.
Valid lite API keys on your server.
A backend endpoint that creates lite checkout sessions.
Xcode and an app targeting iOS 15 or later.

Never place lite API keys in your iOS app. Create checkout sessions on your server and send only the session secret to the app.

Integrate the SDK

1. Install the SDK

The SDK is distributed through Swift Package Manager. CocoaPods is not supported. In Xcode, select File → Add Package Dependencies, then enter:

https://github.com/lite-sa/lite-ios.git

Select version 0.0.2 and add the LiteSDK product to your application target. If you manage dependencies in Package.swift, add:

dependencies: [
    .package(url: "https://github.com/lite-sa/lite-ios.git", exact: "0.0.2"),
]

Then add LiteSDK to your application target:

.product(name: "LiteSDK", package: "lite-ios")

Import the SDK where you integrate checkout:

import LiteSDK

2. Create a checkout session

Your server must create a checkout session using your lite API credentials and return its session secret to the app. Do not generate the session secret in the app and do not include your lite API keys in the application bundle.

curl https://api.lite.sa/api/v1/checkout/sessions \
  -H "x-api-key: $LITE_API_KEY" \
  -H "x-correlation-id: $(uuidgen)" \
  -H "x-idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 4999,
    "currency": "SAR",
    "customer": {
      "email": "john.doe@email.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "order": { "reference": "ORD-123456" },
    "redirect_urls": {
      "success": "https://example.com/return?session_id={SESSION_ID}",
      "failure": "https://example.com/checkout"
    },
    "expiry": 1800
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "client_secret": "cs_a1b2c3d4e5f6",
  "status": "Pending",
  "expires_on": "2026-06-01T12:30:00.000Z",
  "order_id": "ORD-123456",
  "amount": 4999,
  "currency": "SAR"
}

Return client_secret to your app, where the SDK takes it as clientSecret. Keep the session id on your server so you can confirm the payment afterwards. The session determines the amount, currency, enabled payment methods, available card networks, and eligible saved cards. Create a new session for each checkout attempt.

3. Present the Payment Sheet

The Payment Sheet is the recommended integration. Present it from a visible UIViewController:

import LiteSDK
import UIKit

LitePaymentSheet.present(
    from: self,
    clientSecret: sessionSecret,
    configuration: .init(
        cardLayout: .compact,
        defaultStoreForFuture: false,
        showResultBeforeDismiss: true,
        applePayEnabled: true,
        privacyPolicyUrl: "https://merchant.example/privacy"
    )
) { result in
    switch result.status {
    case .success:
        // Show success, then confirm result.paymentId from your server.
        break
    case .failure:
        // Show result.error and allow the customer to retry when appropriate.
        break
    case .processing:
        // Keep the order pending and confirm the result from your server.
        break
    case .cancelled:
        // The customer dismissed checkout or cancelled authentication.
        break
    case .alreadyCompleted:
        // This session had already completed. Confirm it from your server.
        break
    }
}

Only one Payment Sheet can be presented at a time. A second presentation attempt returns a failure with the error code already_presenting. The available card layouts are:

Layout	Behavior
`.compact`	A grouped, compact card-information form. This is the default.
`.form`	Separate card number, expiry, CVV, and optional cardholder fields.
`.line`	A condensed single-row card entry.

4. Embed the payment form

Use LitePaymentForm when checkout must appear inside your own SwiftUI screen. Keep one Lite instance alive for the checkout:

import LiteSDK
import SwiftUI

struct CheckoutView: View {
    let sessionSecret: String
    @StateObject private var lite = Lite()

    var body: some View {
        LitePaymentForm(
            lite: lite,
            cardLayout: .compact,
            clientSecret: sessionSecret,
            applePayEnabled: true,
            privacyPolicyUrl: "https://merchant.example/privacy"
        ) { result in
            handlePaymentResult(result)
        }
    }

    private func handlePaymentResult(_ result: Lite.PayResult) {
        // Handle every result status and confirm the payment from your server.
    }
}

Passing clientSecret starts the SDK automatically. Alternatively, start it yourself and observe its state:

await lite.start(clientSecret: sessionSecret)

switch lite.phase {
case .idle, .loadingSession, .ready, .paying:
    break
case .failed(let message):
    // Show the customer-safe initialization error.
    print(message)
}

Do not create a new Lite instance during SwiftUI view updates. Use @StateObject or another owner with an equivalent lifetime.

5. Save and reuse cards

When the session contains eligible saved cards, the Payment Sheet and embeddable form display them automatically. The customer can select a saved card or enter a new one. For a new card, the form includes a Save card for future purchase control. To select it by default in the Payment Sheet:

let configuration = LitePaymentSheet.Configuration(
    defaultStoreForFuture: true
)

Saved cards are available only when the customer and checkout session are eligible for them. Your server remains responsible for creating the session with the correct customer context.

6. Handle 3D Secure

No separate 3D Secure integration is required. If authentication is needed, the SDK presents the issuer challenge in a secured in-app view and resumes payment processing when it finishes. Keep the presenting view controller and checkout screen alive until the result callback runs. Do not fulfill the order from the 3D Secure callback or redirect alone; wait for the lite payment result and verify it from your server.

7. Handle the result

The completion receives a Lite.PayResult:

struct PayResult {
    let status: PaymentOperationStatus
    let paymentId: String?
    let error: String?
    let errorCode: String?
}

Status	Meaning
`.success`	The payment was authorized or captured. `paymentId` identifies the payment.
`.failure`	The payment failed or was rejected. Display `error` and use `errorCode` for programmatic handling.
`.processing`	The payment has not reached a final state. Keep the order pending and check it from your server.
`.cancelled`	The customer dismissed checkout or cancelled authentication.
`.alreadyCompleted`	The opened session already had a completed payment. This is not a new payment attempt.

Concurrent payment calls are coalesced into the same in-flight operation, preventing double taps from creating duplicate SDK payment attempts.

8. Confirm the payment on your server

A client-side success result is not sufficient for order fulfillment. The app can close, lose connectivity, or be modified. Always retrieve the checkout session or payment from your server and verify its final state before fulfilling the order.

Enable Apple Pay

Apple Pay is not completely plug-and-play because Apple requires the host app to carry a signed Apple Pay entitlement. Before enabling Apple Pay:

Complete Apple Pay merchant onboarding with lite.
In Apple Developer, enable Apple Pay for your app’s identifier.
In Xcode, open your app target’s Signing & Capabilities settings.
Add the Apple Pay capability.
Select the Merchant ID provided during onboarding.
Regenerate or refresh the provisioning profile so it contains the Apple Pay entitlement.

The selected Merchant ID must match the merchant_identifier returned in the lite checkout session. The SDK reads this value from the session; you do not pass it in application code. The session must also return Apple Pay with an ACTIVE status. When applePayEnabled is true, the SDK displays Apple Pay only if the session enables it and the device can make payments using the configured card networks. Test Apple Pay end to end on a physical device with a supported card in Wallet. Missing capabilities, a mismatched Merchant ID, or an incorrectly signed provisioning profile can prevent the Apple Pay sheet from opening.

Clean up

The Payment Sheet clears card fields when it closes. For an embeddable integration, reset the SDK when the customer abandons the checkout or when you intentionally restart with a new flow:

lite.reset()

reset() cancels the active SDK payment task and removes the loaded session, collected card fields, selected saved card, and previous result.

Test your integration

Use lite test API keys and test cards to verify:

Successful card payments.
Declined and unsupported cards.
3D Secure success, failure, and cancellation.
Processing payments.
Saved-card display and payment.
Saving a new card for future use.
Payment Sheet dismissal.
Reopening a completed session.
Apple Pay on a correctly provisioned physical device.

Test that your server confirms the final payment state before your system fulfills an order.

Accept Payments

Tokenization

Account

Overview

How it works

Before you begin

Integrate the SDK

1. Install the SDK

2. Create a checkout session

3. Present the Payment Sheet

4. Embed the payment form

5. Save and reuse cards

6. Handle 3D Secure

7. Handle the result

8. Confirm the payment on your server

Enable Apple Pay

Clean up

Test your integration

​Overview

​How it works

​Before you begin

​Integrate the SDK

​1. Install the SDK

​2. Create a checkout session

​3. Present the Payment Sheet

​4. Embed the payment form

​5. Save and reuse cards

​6. Handle 3D Secure

​7. Handle the result

​8. Confirm the payment on your server

​Enable Apple Pay

​Clean up

​Test your integration

Overview

How it works

Before you begin

Integrate the SDK

1. Install the SDK

2. Create a checkout session

3. Present the Payment Sheet

4. Embed the payment form

5. Save and reuse cards

6. Handle 3D Secure

7. Handle the result

8. Confirm the payment on your server

Enable Apple Pay

Clean up

Test your integration