iOS SDK - Quick start

https://github.com/payrails/ios-sdk.git

dependencies: [
    .package(url: "https://github.com/payrails/ios-sdk.git", from: "3.2.0")
]

// Your backend call — implementation depends on your networking layer
func fetchInitPayload() async throws -> (data: String, version: String) {
    // Call your backend, which calls the Payrails /checkout/initialize endpoint
    // Returns the `data` and `version` fields from the Payrails response
}

import Payrails

let initData = Payrails.InitData(
    version: "2",          // version returned from your backend
    data: "<base64-payload>"  // data returned from your backend
)

let configuration = Payrails.Configuration(
    initData: initData,
    option: Payrails.Options(env: .production) // use .test for sandbox
)

do {
    let session = try await Payrails.createSession(
        with: configuration,
        onSessionExpired: { completion in
            // Re-run your backend's init flow (authentication + initSdk) and hand
            // the fresh InitData back. The SDK swaps its internal config in place —
            // your `session` reference and any cached buttons / forms keep working.
            fetchFreshPayrailsInitData { result in
                completion(result)
            }
        }
    )
    // session is ready; store it or proceed to build your UI
} catch {
    print("SDK initialization failed:", error.localizedDescription)
}

Payrails.createSession(with: configuration) { result in
    switch result {
    case .success(let session):
        // session is ready
    case .failure(let error):
        print("SDK initialization failed:", error.localizedDescription)
    }
}

import UIKit
import Payrails

class CheckoutViewController: UIViewController, PaymentPresenter {

    var encryptedCardData: String?

    override func viewDidLoad() {
        super.viewDidLoad()

        // 1. Create the card form
        let cardForm = Payrails.createCardForm()

        // 2. Create the pay button
        let payButton = Payrails.createCardPaymentButton(
            translations: CardPaymenButtonTranslations(label: "Pay now")
        )
        payButton.delegate = self
        payButton.presenter = self  // PaymentPresenter: required to present 3DS challenges

        // 3. Add to view hierarchy
        view.addSubview(cardForm)
        view.addSubview(payButton)

        // 4. Layout (use Auto Layout or frames as preferred)
        cardForm.translatesAutoresizingMaskIntoConstraints = false
        payButton.translatesAutoresizingMaskIntoConstraints = false

        NSLayoutConstraint.activate([
            cardForm.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 24),
            cardForm.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 16),
            cardForm.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16),

            payButton.topAnchor.constraint(equalTo: cardForm.bottomAnchor, constant: 16),
            payButton.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 16),
            payButton.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16),
        ])
    }

    // PaymentPresenter: called when a view controller must be presented (e.g. 3DS)
    func presentPayment(_ viewController: UIViewController) {
        present(viewController, animated: true)
    }
}

extension CheckoutViewController: PayrailsCardPaymentButtonDelegate {

    func onPaymentButtonClicked(_ button: Payrails.CardPaymentButton) {
        // Notification only — the SDK does not wait for this. Use it for analytics or a
        // loading indicator. To make the payment conditional on your own check, see
        // How to Run a Merchant Check Before Authorization.
    }

    func onAuthorizeSuccess(_ button: Payrails.CardPaymentButton) {
        // Payment succeeded — navigate to confirmation screen
    }

    func onAuthorizeFailed(_ button: Payrails.CardPaymentButton, failure: AuthorizationFailure) {
        switch failure.code {
        case .userCancelled:
            // User dismissed the 3DS sheet or otherwise abandoned the flow.
            // The SDK has already triggered the `onSessionExpired` refresh closure
            // (supplied at `createSession`) so retries continue to work against
            // the same `Session` reference.
            statusLabel.text = "Payment cancelled."
        case .authorizationError:
            // Issuer declined / 3DS rejected. `failure.message` is the backend's
            // extracted failure reason (e.g. "Insufficient funds") with a generic
            // fallback — never nil.
            statusLabel.text = "Declined: \(failure.message)"
        case .authenticationError:
            // Session token rejected (401 / 403). The SDK fires `onSessionExpired`
            // in the background; ask the user to retry.
            statusLabel.text = "Session expired. Please retry."
        case .unknownError:
            // Network, SDK, or other unexpected error. `failure.rawError` carries
            // the underlying error when one exists.
            statusLabel.text = "Payment failed: \(failure.rawError?.localizedDescription ?? failure.message)."
        }
    }

    func onThreeDSecureChallenge(_ button: Payrails.CardPaymentButton) {
        // 3DS challenge is being presented — optional hook
    }
}

let configuration = Payrails.Configuration(
    initData: initData,
    option: Payrails.Options(env: .test)
)