iOS

Use WKWebView to embed frames in native iOS applications. The WebView communicates with frames via JavaScript message handlers and script injection.

Read the manual integration overview for core concepts before you continue.

Setup

Dependencies

The examples below use swift-crypto for X25519 key exchange, but you can use any library that supports X25519 and AES-GCM.

// Package.swift or via Xcode's Package Dependencies
dependencies: [
    .package(url: "https://github.com/apple/swift-crypto.git", from: "3.0.0"),
]

Key generation

import Crypto
import Foundation

struct MoonPayKeyPair {
    let privateKey: Curve25519.KeyAgreement.PrivateKey
    let publicKeyHex: String

    init() {
        self.privateKey = Curve25519.KeyAgreement.PrivateKey()
        self.publicKeyHex = privateKey.publicKey.rawRepresentation
            .map { String(format: "%02x", $0) }
            .joined()
    }
}

Decryption utility

import CryptoKit
import Foundation

struct MoonPayDecryptor {
    struct EncryptedPayload: Codable {
        let iv: String
        let ephemeralPublicKey: String
        let ciphertext: String
    }

    static func decrypt(_ encryptedValue: String, privateKey: Curve25519.KeyAgreement.PrivateKey) -> String? {
        // The frame returns the encrypted payload as a base64-encoded
        // JSON string. Decode the base64 first, then parse the JSON.
        guard let jsonData = Data(base64Encoded: encryptedValue),
              let encrypted = try? JSONDecoder().decode(EncryptedPayload.self, from: jsonData),
              let ephemeralPublicKeyData = Data(hexString: encrypted.ephemeralPublicKey),
              let ivData = Data(hexString: encrypted.iv),
              let ciphertextData = Data(hexString: encrypted.ciphertext),
              let ephemeralPublicKey = try? Curve25519.KeyAgreement.PublicKey(rawRepresentation: ephemeralPublicKeyData),
              let sharedSecret = try? privateKey.sharedSecretFromKeyAgreement(with: ephemeralPublicKey) else {
            return nil
        }

        // Derive AES key using HKDF
        let symmetricKey = sharedSecret.hkdfDerivedSymmetricKey(
            using: SHA256.self,
            salt: Data(),
            sharedInfo: Data(),
            outputByteCount: 32
        )

        // AES-GCM: ciphertext includes the auth tag at the end (last 16 bytes)
        guard ciphertextData.count > 16,
              let sealedBox = try? AES.GCM.SealedBox(
                  nonce: AES.GCM.Nonce(data: ivData),
                  ciphertext: ciphertextData.dropLast(16),
                  tag: ciphertextData.suffix(16)
              ),
              let decryptedData = try? AES.GCM.open(sealedBox, using: symmetricKey) else {
            return nil
        }

        return String(data: decryptedData, encoding: .utf8)
    }
}

extension Data {
    init?(hexString: String) {
        let len = hexString.count / 2
        var data = Data(capacity: len)
        var index = hexString.startIndex

        for _ in 0..<len {
            let nextIndex = hexString.index(index, offsetBy: 2)
            guard let byte = UInt8(hexString[index..<nextIndex], radix: 16) else { return nil }
            data.append(byte)
            index = nextIndex
        }

        self = data
    }
}

Base frame controller

Create a reusable base view controller for frame communication:

import UIKit
import WebKit

protocol MoonPayFrameDelegate: AnyObject {
    func frameDidReceiveMessage(_ message: [String: Any])
    func frameDidCompleteHandshake()
}

// WKUserContentController keeps a strong reference to its message handlers.
// Register this proxy instead of the view controller, so the view controller
// and its web view can deallocate.
final class WeakScriptMessageHandler: NSObject, WKScriptMessageHandler {
    weak var target: WKScriptMessageHandler?

    init(_ target: WKScriptMessageHandler) {
        self.target = target
    }

    func userContentController(_ userContentController: WKUserContentController,
                               didReceive message: WKScriptMessage) {
        target?.userContentController(userContentController, didReceive: message)
    }
}

class MoonPayFrameViewController: UIViewController {
    private(set) var webView: WKWebView!
    private(set) var channelId: String

    weak var delegate: MoonPayFrameDelegate?

    let frameHost = "platform.moonpay.com"
    var frameOrigin: String { "https://\(frameHost)" }

    init(channelId: String = UUID().uuidString) {
        self.channelId = channelId
        super.init(nibName: nil, bundle: nil)
    }

    required init?(coder: NSCoder) {
        self.channelId = UUID().uuidString
        super.init(coder: coder)
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        setupWebView()
    }

    private func setupWebView() {
        let config = WKWebViewConfiguration()
        let contentController = WKUserContentController()

        contentController.add(WeakScriptMessageHandler(self), name: "MoonPayBridge")

        // Expose window.MoonPayBridge so the frame can call postMessage directly
        let bridgeScript = WKUserScript(
            source: """
            window.MoonPayBridge = {
                postMessage: function(message) {
                    window.webkit.messageHandlers.MoonPayBridge.postMessage(message);
                }
            };
            """,
            injectionTime: .atDocumentStart,
            forMainFrameOnly: false
        )
        contentController.addUserScript(bridgeScript)

        config.userContentController = contentController

        webView = WKWebView(frame: view.bounds, configuration: config)
        webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        // Required for the test-mode Apple Pay flow — see "Handle JavaScript
        // dialogs" below.
        webView.uiDelegate = self
        view.addSubview(webView)
    }

    func loadFrame(path: String, params: [String: String]) {
        var components = URLComponents(string: "\(frameOrigin)\(path)")!
        components.queryItems = params.map { URLQueryItem(name: $0.key, value: $0.value) }
        load(components)
    }

    // URLComponents leaves `+` unencoded, and the server reads it as a
    // space. Encode it, so tokens and signatures that contain `+` survive.
    func load(_ components: URLComponents) {
        var components = components
        components.percentEncodedQuery = components.percentEncodedQuery?
            .replacingOccurrences(of: "+", with: "%2B")

        guard let url = components.url else { return }
        webView.load(URLRequest(url: url))
    }

    // Removes a frame you added as a child view controller. A frame you
    // present is torn down when it's dismissed, in viewDidDisappear.
    func dispose() {
        tearDownWebView()
        willMove(toParent: nil)
        viewIfLoaded?.removeFromSuperview()
        removeFromParent()
    }

    override func viewDidDisappear(_ animated: Bool) {
        super.viewDidDisappear(animated)
        if isBeingDismissed || isMovingFromParent {
            tearDownWebView()
        }
    }

    // Stops the page and its messages. Safe to call more than once.
    private func tearDownWebView() {
        webView?.stopLoading()
        webView?.configuration.userContentController
            .removeScriptMessageHandler(forName: "MoonPayBridge")
    }

    func sendMessage(kind: String, payload: [String: Any]? = nil) {
        var message: [String: Any] = [
            "version": 2,
            "meta": ["channelId": channelId],
            "kind": kind,
        ]
        if let payload = payload {
            message["payload"] = payload
        }

        guard let jsonData = try? JSONSerialization.data(withJSONObject: message),
              let jsonString = String(data: jsonData, encoding: .utf8) else { return }

        // Re-encode the JSON as a string literal. The frame's bridge
        // listens for `MessageEvent`s whose `data` is a string and ignores
        // anything else, so we must post a string — not an object literal.
        guard let stringLiteralData = try? JSONEncoder().encode(jsonString),
              let jsStringLiteral = String(data: stringLiteralData, encoding: .utf8) else { return }

        let script = "window.postMessage(\(jsStringLiteral), '*');"
        webView.evaluateJavaScript(script, completionHandler: nil)
    }

}

// MARK: - WKScriptMessageHandler

extension MoonPayFrameViewController: WKScriptMessageHandler {
    func userContentController(_ userContentController: WKUserContentController,
                               didReceive message: WKScriptMessage) {
        // The bridge script runs in every frame on the page
        // (forMainFrameOnly: false), so only accept messages from MoonPay
        guard message.name == "MoonPayBridge",
              message.frameInfo.securityOrigin.protocol == "https",
              message.frameInfo.securityOrigin.host == frameHost,
              let body = message.body as? String,
              let data = body.data(using: .utf8),
              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
              let meta = json["meta"] as? [String: Any],
              let messageChannelId = meta["channelId"] as? String,
              messageChannelId == channelId else { return }

        if let kind = json["kind"] as? String, kind == "handshake" {
            sendMessage(kind: "ack")
            delegate?.frameDidCompleteHandshake()
        }

        delegate?.frameDidReceiveMessage(json)
    }
}

Handle JavaScript dialogs

In test mode, the Buy Button frame renders a mock Apple Pay button for an Apple Pay quote and uses window.prompt to simulate the Apple Pay payment sheet. By default, WKWebView silently dismisses alert, confirm, and prompt: window.prompt returns null with no UI shown. The frame interprets that as the customer cancelling, so every test transaction comes back with status: "failed". This WKWebView requirement is captured on the Buy Button frame reference, which is the source of truth. To surface the simulated payment sheet, conform your base view controller to WKUIDelegate and present the text input panel as a UIAlertController with a text field. The confirm panel handler covers any other dialog the frame might show:

// MARK: - WKUIDelegate

extension MoonPayFrameViewController: WKUIDelegate {
    // The test-mode Apple Pay sheet: the prompt shows the total, and the
    // text field holds the billing contact JSON
    func webView(_ webView: WKWebView,
                 runJavaScriptTextInputPanelWithPrompt prompt: String,
                 defaultText: String?,
                 initiatedByFrame frame: WKFrameInfo,
                 completionHandler: @escaping (String?) -> Void) {
        let alert = UIAlertController(
            title: nil,
            message: prompt,
            preferredStyle: .alert
        )
        alert.addTextField { $0.text = defaultText }
        alert.addAction(UIAlertAction(title: "Cancel", style: .cancel) { _ in
            completionHandler(nil)
        })
        alert.addAction(UIAlertAction(title: "OK", style: .default) { _ in
            completionHandler(alert.textFields?.first?.text ?? defaultText)
        })
        present(alert, animated: true)
    }

    func webView(_ webView: WKWebView,
                 runJavaScriptConfirmPanelWithMessage message: String,
                 initiatedByFrame frame: WKFrameInfo,
                 completionHandler: @escaping (Bool) -> Void) {
        let alert = UIAlertController(
            title: nil,
            message: message,
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "Cancel", style: .cancel) { _ in
            completionHandler(false)
        })
        alert.addAction(UIAlertAction(title: "OK", style: .default) { _ in
            completionHandler(true)
        })
        present(alert, animated: true)
    }
}

In the prompt, OK authorizes the test payment with the billing contact in the text field (the frame emits complete with a non-failed status); Cancel declines it (the frame emits complete with status: "failed").

Wire the UI delegate even if you only plan to ship live mode. The WKWebView default behavior applies to any window.confirm, alert, or prompt the frame might surface, and it makes test-mode debugging impossible without it.

Check frame

The check frame verifies whether a customer already has an active connection. It’s headless — no UI is rendered. Use it to skip the connect flow for returning customers. See check frame reference for event details.

Check controller

import UIKit

protocol CheckFrameDelegate: AnyObject {
    func checkDidFindActiveConnection(accessToken: String, clientToken: String, expiresAt: String)
    func checkDidRequireConnection(accessToken: String, clientToken: String)
    func checkDidFail(status: String, reason: String?)
    func checkDidError(code: String, message: String)
}

class MoonPayCheckViewController: MoonPayFrameViewController {
    private var keyPair: MoonPayKeyPair!
    private var sessionToken: String!

    weak var checkDelegate: CheckFrameDelegate?

    func configure(sessionToken: String) {
        self.sessionToken = sessionToken
        self.keyPair = MoonPayKeyPair()
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self

        guard sessionToken != nil else {
            fatalError("Call configure(sessionToken:) before presenting")
        }

        loadFrame(path: "/platform/v1/check-connection", params: [
            "sessionToken": sessionToken,
            "publicKey": keyPair.publicKeyHex,
            "channelId": channelId,
        ])
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayCheckViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "complete":
            handleComplete(message["payload"] as? [String: Any] ?? [:])

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            checkDelegate?.checkDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete — checking connection status
    }

    private func handleComplete(_ payload: [String: Any]) {
        guard let status = payload["status"] as? String else { return }

        switch status {
        case "active":
            guard let credentials = payload["credentials"] as? String,
                  let expiresAt = payload["expiresAt"] as? String,
                  let decryptedPayload = MoonPayDecryptor.decrypt(credentials, privateKey: keyPair.privateKey),
                  let credentialsData = decryptedPayload.data(using: .utf8),
                  let credentials = try? JSONSerialization.jsonObject(with: credentialsData) as? [String: String],
                  let accessToken = credentials["accessToken"],
                  let clientToken = credentials["clientToken"] else {
                checkDelegate?.checkDidError(code: "decryption", message: "Failed to decrypt credentials")
                return
            }

            let customer = payload["customer"] as? [String: Any]
            let country = customer?["country"] as? String
            let administrativeArea = customer?["administrativeArea"] as? String
            let area = customer?["area"] as? String
            // payload["capabilities"]["ramps"]["requirements"]["paymentDisclosures"] is deprecated.
            checkDelegate?.checkDidFindActiveConnection(accessToken: accessToken, clientToken: clientToken, expiresAt: expiresAt)

        case "connectionRequired":
            // payload["mismatch"] is true when the session's email and phone resolve to different customers — route through the connect flow first.
            guard let credentials = payload["credentials"] as? String,
                  let decryptedPayload = MoonPayDecryptor.decrypt(credentials, privateKey: keyPair.privateKey),
                  let credentialsData = decryptedPayload.data(using: .utf8),
                  let anonymousCredentials = try? JSONSerialization.jsonObject(with: credentialsData) as? [String: String],
                  let accessToken = anonymousCredentials["accessToken"],
                  let clientToken = anonymousCredentials["clientToken"] else {
                checkDelegate?.checkDidError(code: "decryption", message: "Failed to decrypt anonymous credentials")
                return
            }
            checkDelegate?.checkDidRequireConnection(accessToken: accessToken, clientToken: clientToken)

        case "pending", "unavailable", "failed":
            checkDelegate?.checkDidFail(status: status, reason: payload["reason"] as? String)

        default:
            break
        }
    }
}

Usage

class SplashViewController: UIViewController, CheckFrameDelegate {
    func checkConnection() {
        let checkVC = MoonPayCheckViewController()
        checkVC.configure(sessionToken: "your-session-token")
        checkVC.checkDelegate = self

        // The check frame is headless — add as a child without visible UI
        addChild(checkVC)
        checkVC.view.frame = .zero
        view.addSubview(checkVC.view)
        checkVC.didMove(toParent: self)
    }

    // MARK: - CheckFrameDelegate

    func checkDidFindActiveConnection(accessToken: String, clientToken: String, expiresAt: String) {
        // Customer is already connected — skip to payment
        CredentialsManager.shared.accessToken = accessToken
        CredentialsManager.shared.clientToken = clientToken

        let paymentVC = PaymentViewController()
        navigationController?.pushViewController(paymentVC, animated: true)
    }

    func checkDidRequireConnection(accessToken: String, clientToken: String) {
        // Store both tokens in memory, then show connect frame with the anonymous clientToken
        CredentialsManager.shared.accessToken = accessToken
        CredentialsManager.shared.clientToken = clientToken

        let connectVC = MoonPayConnectViewController()
        connectVC.configure(clientToken: clientToken)
        navigationController?.pushViewController(connectVC, animated: true)
    }

    func checkDidFail(status: String, reason: String?) {
        print("Check \(status): \(reason ?? "No reason provided")")
    }

    func checkDidError(code: String, message: String) {
        print("Check error: \(code) — \(message)")
    }
}

Connect frame

The connect frame establishes a customer connection to your application. See connect frame reference for event details.

Connect controller

import UIKit

protocol ConnectFrameDelegate: AnyObject {
    func connectDidComplete(accessToken: String, clientToken: String, expiresAt: String)
    func connectDidFail(status: String, reason: String?)
    func connectDidError(code: String, message: String)
}

class MoonPayConnectViewController: MoonPayFrameViewController {
    private var keyPair: MoonPayKeyPair!
    private var clientToken: String!

    weak var connectDelegate: ConnectFrameDelegate?

    func configure(clientToken: String) {
        self.clientToken = clientToken
        self.keyPair = MoonPayKeyPair()
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self

        guard clientToken != nil else {
            fatalError("Call configure(clientToken:) before presenting")
        }

        loadFrame(path: "/platform/v1/connect", params: [
            "clientToken": clientToken,
            "publicKey": keyPair.publicKeyHex,
            "channelId": channelId,
        ])
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayConnectViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "complete":
            handleComplete(message["payload"] as? [String: Any] ?? [:])

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            connectDelegate?.connectDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete — waiting for customer interaction
    }

    private func handleComplete(_ payload: [String: Any]) {
        guard let status = payload["status"] as? String else { return }

        switch status {
        case "active":
            guard let credentials = payload["credentials"] as? String,
                  let expiresAt = payload["expiresAt"] as? String,
                  let decryptedPayload = MoonPayDecryptor.decrypt(credentials, privateKey: keyPair.privateKey),
                  let credentialsData = decryptedPayload.data(using: .utf8),
                  let credentials = try? JSONSerialization.jsonObject(with: credentialsData) as? [String: String],
                  let accessToken = credentials["accessToken"],
                  let clientToken = credentials["clientToken"] else {
                connectDelegate?.connectDidError(code: "decryption", message: "Failed to decrypt credentials")
                return
            }

            let customer = payload["customer"] as? [String: Any]
            let country = customer?["country"] as? String
            let administrativeArea = customer?["administrativeArea"] as? String
            let area = customer?["area"] as? String
            // payload["capabilities"]["ramps"]["requirements"]["paymentDisclosures"] is deprecated.
            connectDelegate?.connectDidComplete(accessToken: accessToken, clientToken: clientToken, expiresAt: expiresAt)

        case "pending", "unavailable", "failed":
            connectDelegate?.connectDidFail(status: status, reason: payload["reason"] as? String)

        default:
            break
        }
    }
}

Usage

class MyViewController: UIViewController, ConnectFrameDelegate {
    // The clientToken is the anonymous token obtained from the check frame's
    // `connectionRequired` response.
    func showConnect(clientToken: String) {
        let connectVC = MoonPayConnectViewController()
        connectVC.configure(clientToken: clientToken)
        connectVC.connectDelegate = self
        connectVC.modalPresentationStyle = .fullScreen

        present(connectVC, animated: true)
    }

    // MARK: - ConnectFrameDelegate

    func connectDidComplete(accessToken: String, clientToken: String, expiresAt: String) {
        dismiss(animated: true)

        // Store credentials in memory
        CredentialsManager.shared.accessToken = accessToken
        CredentialsManager.shared.clientToken = clientToken

        print("Connected! Expires: \(expiresAt)")
    }

    func connectDidFail(status: String, reason: String?) {
        dismiss(animated: true)
        showAlert(title: "Connection \(status)", message: reason ?? "Please try again later.")
    }

    func connectDidError(code: String, message: String) {
        dismiss(animated: true)
        showAlert(title: "Error", message: message)
    }
}

Auth frame

The auth frame authenticates a customer with email or SMS one-time passcode and returns fully scoped credentials — without the hosted KYC UI in the connect frame. Launch it after the check frame returns connectionRequired, typically when you drive onboarding through the Customer API. See auth frame reference for event details.

Auth controller

import UIKit

protocol AuthFrameDelegate: AnyObject {
    func authDidReady()
    func authDidComplete(status: String, accessToken: String?, clientToken: String?, customerId: String?)
    func authDidError(code: String, message: String)
    func authDidClose()
}

class MoonPayAuthViewController: MoonPayFrameViewController {
    private var keyPair: MoonPayKeyPair!
    private var clientToken: String!

    weak var authDelegate: AuthFrameDelegate?

    func configure(clientToken: String) {
        self.clientToken = clientToken
        self.keyPair = MoonPayKeyPair()
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self
        view.isHidden = true

        guard clientToken != nil else {
            fatalError("Call configure(clientToken:) before presenting")
        }

        loadFrame(path: "/v2/auth", params: [
            "clientToken": clientToken,
            "publicKey": keyPair.publicKeyHex,
            "channelId": channelId,
        ])
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayAuthViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "ready":
            view.isHidden = false
            authDelegate?.authDidReady()

        case "complete":
            handleComplete(message["payload"] as? [String: Any] ?? [:])

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            authDelegate?.authDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )

        case "close":
            authDelegate?.authDidClose()

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete — waiting for OTP
    }

    private func handleComplete(_ payload: [String: Any]) {
        guard let status = payload["status"] as? String else { return }

        switch status {
        case "active":
            guard let credentials = payload["credentials"] as? String,
                  let decryptedPayload = MoonPayDecryptor.decrypt(credentials, privateKey: keyPair.privateKey),
                  let credentialsData = decryptedPayload.data(using: .utf8),
                  let credentials = try? JSONSerialization.jsonObject(with: credentialsData) as? [String: String],
                  let accessToken = credentials["accessToken"],
                  let clientToken = credentials["clientToken"] else {
                authDelegate?.authDidError(code: "decryption", message: "Failed to decrypt credentials")
                return
            }

            let customerId = (payload["customer"] as? [String: Any])?["id"] as? String
            authDelegate?.authDidComplete(
                status: status,
                accessToken: accessToken,
                clientToken: clientToken,
                customerId: customerId
            )

        case "termsAcceptanceRequired", "pending", "unavailable":
            authDelegate?.authDidComplete(status: status, accessToken: nil, clientToken: nil, customerId: nil)

        default:
            break
        }
    }
}

Usage

class MyViewController: UIViewController, AuthFrameDelegate {
    func showAuth(clientToken: String) {
        let authVC = MoonPayAuthViewController()
        authVC.configure(clientToken: clientToken)
        authVC.authDelegate = self
        authVC.modalPresentationStyle = .fullScreen

        present(authVC, animated: true)
    }

    // MARK: - AuthFrameDelegate

    func authDidReady() {
        // Frame is visible — hide any loading UI
    }

    func authDidComplete(status: String, accessToken: String?, clientToken: String?, customerId: String?) {
        dismiss(animated: true)

        switch status {
        case "active":
            CredentialsManager.shared.accessToken = accessToken
            CredentialsManager.shared.clientToken = clientToken
            print("Authenticated: \(customerId ?? "")")
        case "termsAcceptanceRequired":
            showTermsAcceptanceFlow()
        default:
            showAlert(title: "Auth \(status)", message: "Please try again later.")
        }
    }

    func authDidError(code: String, message: String) {
        dismiss(animated: true)
        showAlert(title: "Error", message: message)
    }

    func authDidClose() {
        dismiss(animated: true)
    }
}

Add Card frame

The add card frame lets a customer save a new card to their account. See add card frame reference for event details.

Add Card controller

import UIKit

protocol AddCardFrameDelegate: AnyObject {
    func addCardDidComplete(card: [String: Any])
    func addCardDidError(code: String, message: String)
}

class MoonPayAddCardViewController: MoonPayFrameViewController {
    private var clientToken: String!

    weak var addCardDelegate: AddCardFrameDelegate?

    func configure(clientToken: String) {
        self.clientToken = clientToken
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self

        guard clientToken != nil else {
            fatalError("Call configure(clientToken:) before presenting")
        }

        loadFrame(path: "/platform/v1/add-card", params: [
            "clientToken": clientToken,
            "channelId": channelId,
        ])
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayAddCardViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "ready":
            break

        case "complete":
            let payload = message["payload"] as? [String: Any] ?? [:]
            let card = payload["card"] as? [String: Any] ?? [:]
            addCardDelegate?.addCardDidComplete(card: card)

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            addCardDelegate?.addCardDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete
    }
}

Usage

class SaveCardViewController: UIViewController, AddCardFrameDelegate {
    private var addCardVC: MoonPayAddCardViewController?

    override func viewDidLoad() {
        super.viewDidLoad()
        setupAddCardFrame()
    }

    private func setupAddCardFrame() {
        let addCardVC = MoonPayAddCardViewController()
        addCardVC.configure(clientToken: CredentialsManager.shared.clientToken!)
        addCardVC.addCardDelegate = self

        addChild(addCardVC)
        addCardVC.view.frame = view.bounds
        addCardVC.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(addCardVC.view)
        addCardVC.didMove(toParent: self)

        self.addCardVC = addCardVC
    }

    // MARK: - AddCardFrameDelegate

    func addCardDidComplete(card: [String: Any]) {
        print("Card saved: \(card["id"] ?? "")")
        // Proceed to payment with the saved card
    }

    func addCardDidError(code: String, message: String) {
        showAlert(title: "Error", message: message)
    }
}

Buy Button frame

The Buy Button frame takes a quote to payment. It renders the Apple Pay or card button that matches the payment method in your quote, and supports guest checkout when your quote allows it. For card and bank transfer quotes, you can also run it in headless mode behind your own purchase button. See the Buy Button frame reference for event details, and Pay with the buy button for the full walkthrough.

For the Apple Pay button, your base view controller must handle JavaScript dialogs. Google Pay isn’t available in a WKWebView, so offer another payment method. See Mobile WebViews.

What you’ll need

Before you initialize the Buy Button frame, you need:

A clientToken from a successful connect flow
A valid quote signature for the transaction

Buy Button controller

Pass headless: true to configure to run the purchase without a button, as described in Headless mode.

import UIKit

protocol BuyButtonFrameDelegate: AnyObject {
    func buyButtonDidBecomeReady()
    func buyButtonDidComplete(transactionId: String, status: String)
    func buyButtonDidFail(failureCode: String, reason: String)
    func buyButtonDidChallenge(url: String)
    func buyButtonDidCancel()
    func buyButtonDidError(code: String, message: String)
}

class MoonPayBuyButtonViewController: MoonPayFrameViewController {
    private var clientToken: String!
    private var quoteSignature: String!
    private var externalTransactionId: String?
    private var headless = false

    weak var buyButtonDelegate: BuyButtonFrameDelegate?

    func configure(
        clientToken: String,
        quoteSignature: String,
        externalTransactionId: String? = nil,
        headless: Bool = false
    ) {
        self.clientToken = clientToken
        self.quoteSignature = quoteSignature
        self.externalTransactionId = externalTransactionId
        self.headless = headless
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self

        guard clientToken != nil, quoteSignature != nil else {
            fatalError("Call configure(clientToken:quoteSignature:) before presenting")
        }

        var params: [String: String] = [
            "clientToken": clientToken,
            "channelId": channelId,
            "signature": quoteSignature,
        ]
        if let externalTransactionId = externalTransactionId {
            params["externalTransactionId"] = externalTransactionId
        }
        if headless {
            params["headless"] = "true"
        }

        loadFrame(path: "/platform/v1/buy-button", params: params)
    }

    func updateQuote(signature: String) {
        quoteSignature = signature
        sendMessage(kind: "setQuote", payload: [
            "quote": ["signature": signature]
        ])
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayBuyButtonViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "ready":
            buyButtonDelegate?.buyButtonDidBecomeReady()

        case "complete":
            handleComplete(message["payload"] as? [String: Any] ?? [:])

        case "challenge":
            let payload = message["payload"] as? [String: Any] ?? [:]
            let url = payload["url"] as? String ?? ""
            buyButtonDelegate?.buyButtonDidChallenge(url: url)

        case "cancelled":
            // The customer dismissed the Apple Pay sheet.
            // The button stays on screen, so the customer can tap it again.
            buyButtonDelegate?.buyButtonDidCancel()

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            buyButtonDelegate?.buyButtonDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete
    }

    private func handleComplete(_ payload: [String: Any]) {
        guard let transaction = payload["transaction"] as? [String: Any],
              let status = transaction["status"] as? String else { return }

        if status == "failed" {
            // Branch on failureCode; failureReason is developer-facing only
            buyButtonDelegate?.buyButtonDidFail(
                failureCode: transaction["failureCode"] as? String ?? "unknown",
                reason: transaction["failureReason"] as? String ?? "Transaction failed"
            )
        } else if let transactionId = transaction["id"] as? String {
            buyButtonDelegate?.buyButtonDidComplete(transactionId: transactionId, status: status)
        }
    }
}

Challenge handling

When the Buy Button frame emits a challenge event, for example for 3-D Secure, present a MoonPayChallengeViewController with the challenge URL. Opened without resume, as below, the challenge frame finishes the purchase for every payment method and sends complete. On completion, cancellation, or error, dismiss the challenge view controller, which tears down its web view, and call dispose() on the Buy Button view controller. To have the customer finish an Apple Pay purchase on your buy button instead, see Finish on your buy button.

protocol ChallengeFrameDelegate: AnyObject {
    func challengeDidComplete(transactionId: String, status: String)
    func challengeDidFail(failureCode: String, reason: String)
    func challengeDidCancel()
    func challengeDidError(code: String, message: String)
}

class MoonPayChallengeViewController: MoonPayFrameViewController {
    private var challengeUrl: String!
    private var clientToken: String!

    weak var challengeDelegate: ChallengeFrameDelegate?

    func configure(challengeUrl: String, clientToken: String) {
        self.challengeUrl = challengeUrl
        self.clientToken = clientToken
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self

        guard let rawUrl = challengeUrl,
              var components = URLComponents(string: rawUrl) else {
            fatalError("Call configure(challengeUrl:clientToken:) before presenting")
        }

        var queryItems = components.queryItems ?? []
        queryItems.append(URLQueryItem(name: "clientToken", value: clientToken))
        queryItems.append(URLQueryItem(name: "channelId", value: channelId))
        components.queryItems = queryItems
        load(components)
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayChallengeViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "ready":
            break

        case "complete":
            let payload = message["payload"] as? [String: Any] ?? [:]
            let transaction = payload["transaction"] as? [String: Any] ?? [:]
            let status = transaction["status"] as? String ?? ""
            if status == "failed" {
                // A failed transaction may have no id.
                // Branch on failureCode; failureReason is developer-facing only
                challengeDelegate?.challengeDidFail(
                    failureCode: transaction["failureCode"] as? String ?? "unknown",
                    reason: transaction["failureReason"] as? String ?? "Transaction failed"
                )
            } else {
                let transactionId = transaction["id"] as? String ?? ""
                challengeDelegate?.challengeDidComplete(transactionId: transactionId, status: status)
            }

        case "cancelled":
            challengeDelegate?.challengeDidCancel()

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            challengeDelegate?.challengeDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete
    }
}

Usage

Size the button container 44pt tall. See Size.

class PaymentViewController: UIViewController, BuyButtonFrameDelegate, ChallengeFrameDelegate {
    private var buyButtonContainer: UIView!
    private var buyButtonVC: MoonPayBuyButtonViewController?

    override func viewDidLoad() {
        super.viewDidLoad()
        setupBuyButtonFrame()
    }

    private func setupBuyButtonFrame() {
        buyButtonContainer = UIView(frame: CGRect(x: 20, y: 200, width: view.bounds.width - 40, height: 44))
        view.addSubview(buyButtonContainer)

        let buyButtonVC = MoonPayBuyButtonViewController()
        buyButtonVC.configure(
            clientToken: CredentialsManager.shared.clientToken!,
            quoteSignature: currentQuote.signature
        )
        buyButtonVC.buyButtonDelegate = self

        addChild(buyButtonVC)
        buyButtonVC.view.frame = buyButtonContainer.bounds
        buyButtonContainer.addSubview(buyButtonVC.view)
        buyButtonVC.didMove(toParent: self)

        self.buyButtonVC = buyButtonVC
    }

    // MARK: - BuyButtonFrameDelegate

    func buyButtonDidBecomeReady() {
        print("Buy Button frame is ready")
    }

    func buyButtonDidComplete(transactionId: String, status: String) {
        disposeBuyButton()
        print("Transaction \(transactionId) status: \(status)")
        // Navigate to transaction status screen
    }

    func buyButtonDidFail(failureCode: String, reason: String) {
        disposeBuyButton()
        showAlert(title: "Payment Failed", message: reason)
    }

    func buyButtonDidChallenge(url: String) {
        let challengeVC = MoonPayChallengeViewController()
        challengeVC.configure(challengeUrl: url, clientToken: CredentialsManager.shared.clientToken!)
        challengeVC.challengeDelegate = self
        challengeVC.modalPresentationStyle = .fullScreen
        present(challengeVC, animated: true)
    }

    func buyButtonDidCancel() {
        // The button stays on screen, so there's nothing to clean up
    }

    func buyButtonDidError(code: String, message: String) {
        if code == "quoteExpired" {
            // Fetch new quote and update
            Task {
                let newQuote = await fetchNewQuote()
                buyButtonVC?.updateQuote(signature: newQuote.signature)
            }
            return
        }
        disposeBuyButton()
        showAlert(title: "Error", message: message)
    }

    // MARK: - ChallengeFrameDelegate

    func challengeDidComplete(transactionId: String, status: String) {
        dismiss(animated: true)
        disposeBuyButton()
        print("Transaction \(transactionId) status: \(status)")
        // Navigate to transaction status screen
    }

    func challengeDidFail(failureCode: String, reason: String) {
        dismiss(animated: true)
        disposeBuyButton()
        showAlert(title: "Payment Failed", message: reason)
    }

    func challengeDidCancel() {
        dismiss(animated: true)
        disposeBuyButton()
    }

    func challengeDidError(code: String, message: String) {
        dismiss(animated: true)
        disposeBuyButton()
        showAlert(title: "Error", message: message)
    }

    // The purchase ended: remove the frame. Set up a new one to retry.
    private func disposeBuyButton() {
        buyButtonVC?.dispose()
        buyButtonVC = nil
    }
}

Headless mode

For card and bank transfer quotes, you can draw your own purchase button and pass headless: true to configure. The frame loads with headless=true, renders nothing, and starts the purchase as soon as it loads. Add it as a zero-size child when the customer confirms the purchase in your UI, not before. See Headless mode. In headless mode, the frame:

Sends ready, then exactly one of complete, challenge, or error.
Never sends buttonPressed or cancelled.
Accepts card and bank transfer (SEPA) quotes only. An Apple Pay or Google Pay quote returns error with unsupportedPaymentMethod.
Needs a connected customer. A guest checkout quote returns error with invalidQuote.
Reads setQuote only after an error with quoteExpired.

On challenge, present the challenge frame without resume, as in challenge handling. It finishes the purchase and sends its own complete. For a bank transfer (SEPA) quote, buyButtonDidComplete receives the transaction id. Fetch the transaction by ID, and show the customer the bank details from bankTransferDepositInfo and the amount to send from source.amount natively so they can send the transfer. See Pay with bank transfer.

For bank transfers, the customer must include the payment reference from bankTransferDepositInfo with their transfer, or it is rejected. Render the deposit details, including the reference, in your own UI. See the transaction object.

Reuse the BuyButtonFrameDelegate and ChallengeFrameDelegate methods from the usage example above. They dispose the frame and set buyButtonVC to nil after its final event: complete, or an error other than quoteExpired. Call this from your purchase button’s action:

private func confirmPurchase() {
    // A purchase is already running, so ignore a second tap
    guard self.buyButtonVC == nil else { return }

    let buyButtonVC = MoonPayBuyButtonViewController()
    buyButtonVC.configure(
        clientToken: CredentialsManager.shared.clientToken!,
        quoteSignature: currentQuote.signature,
        headless: true
    )
    buyButtonVC.buyButtonDelegate = self

    // Headless mode renders nothing, so add the frame as a zero-size child.
    // Keep the view in the window hierarchy and don't set isHidden, or
    // WebKit treats the page as hidden and throttles it.
    addChild(buyButtonVC)
    buyButtonVC.view.frame = .zero
    view.addSubview(buyButtonVC.view)
    buyButtonVC.didMove(toParent: self)

    self.buyButtonVC = buyButtonVC
}

To hand the whole purchase to MoonPay, including amount entry and payment method selection, use the widget frame. It renders the full MoonPay buy experience inside a WKWebView, including payment collection and transaction confirmation. See pay with widget for a full walkthrough.

import UIKit

protocol WidgetFrameDelegate: AnyObject {
    func widgetDidBecomeReady()
    func widgetDidCreateTransaction(transactionId: String, status: String)
    func widgetDidComplete(transactionId: String, status: String)
    func widgetDidFail(reason: String)
    func widgetDidError(code: String, message: String)
}

class MoonPayWidgetViewController: MoonPayFrameViewController {
    private var clientToken: String!
    private var quoteSignature: String!
    private var externalTransactionId: String?

    weak var widgetDelegate: WidgetFrameDelegate?

    func configure(clientToken: String, quoteSignature: String, externalTransactionId: String? = nil) {
        self.clientToken = clientToken
        self.quoteSignature = quoteSignature
        self.externalTransactionId = externalTransactionId
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self

        guard clientToken != nil, quoteSignature != nil else {
            fatalError("Call configure(clientToken:quoteSignature:) before presenting")
        }

        var params: [String: String] = [
            "flow": "buy",
            "clientToken": clientToken,
            "quoteSignature": quoteSignature,
            "channelId": channelId,
        ]
        if let externalTransactionId = externalTransactionId {
            params["externalTransactionId"] = externalTransactionId
        }

        loadFrame(path: "/platform/v1/widget", params: params)
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayWidgetViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "ready":
            widgetDelegate?.widgetDidBecomeReady()

        case "transactionCreated":
            let payload = message["payload"] as? [String: Any] ?? [:]
            let transaction = payload["transaction"] as? [String: Any] ?? [:]
            widgetDelegate?.widgetDidCreateTransaction(
                transactionId: transaction["id"] as? String ?? "",
                status: transaction["status"] as? String ?? ""
            )

        case "complete":
            handleComplete(message["payload"] as? [String: Any] ?? [:])

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            widgetDelegate?.widgetDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete — widget loading
    }

    private func handleComplete(_ payload: [String: Any]) {
        guard let transaction = payload["transaction"] as? [String: Any],
              let status = transaction["status"] as? String else { return }

        if status == "failed" {
            let reason = transaction["failureReason"] as? String ?? "Transaction failed"
            widgetDelegate?.widgetDidFail(reason: reason)
        } else if let transactionId = transaction["id"] as? String {
            widgetDelegate?.widgetDidComplete(transactionId: transactionId, status: status)
        }
    }
}

Usage

class WidgetPaymentViewController: UIViewController, WidgetFrameDelegate {
    private var widgetVC: MoonPayWidgetViewController?

    override func viewDidLoad() {
        super.viewDidLoad()
        setupWidget()
    }

    private func setupWidget() {
        let widgetVC = MoonPayWidgetViewController()
        widgetVC.configure(
            clientToken: CredentialsManager.shared.clientToken!,
            quoteSignature: currentQuote.signature
        )
        widgetVC.widgetDelegate = self

        addChild(widgetVC)
        widgetVC.view.frame = view.bounds
        widgetVC.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(widgetVC.view)
        widgetVC.didMove(toParent: self)

        self.widgetVC = widgetVC
    }

    // MARK: - WidgetFrameDelegate

    func widgetDidBecomeReady() {
        print("Widget loaded and visible")
    }

    func widgetDidCreateTransaction(transactionId: String, status: String) {
        print("Transaction created: \(transactionId) (\(status))")
        // Customer may still need to complete 3-D Secure
    }

    func widgetDidComplete(transactionId: String, status: String) {
        print("Transaction \(transactionId) status: \(status)")
        // Navigate to transaction status screen
    }

    func widgetDidFail(reason: String) {
        showAlert(title: "Payment Failed", message: reason)
    }

    func widgetDidError(code: String, message: String) {
        showAlert(title: "Error", message: message)
    }
}

Reset frame

The reset frame is headless. Use it when the customer signs out to clear MoonPay session state on MoonPay’s domain. See reset frame reference. Pass your clientToken so your app is authorized to embed the frame. Do not block sign-out if reset fails.

Reset controller

import UIKit

protocol ResetFrameDelegate: AnyObject {
    func resetDidComplete()
    func resetDidError(code: String, message: String)
}

class MoonPayResetViewController: MoonPayFrameViewController {
    private var clientToken: String!
    weak var resetDelegate: ResetFrameDelegate?

    func configure(clientToken: String) {
        self.clientToken = clientToken
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self
        view.isHidden = true

        loadFrame(path: "/platform/v1/reset", params: [
            "channelId": channelId,
            "clientToken": clientToken,
        ])
    }
}

extension MoonPayResetViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "complete":
            resetDelegate?.resetDidComplete()
        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            resetDelegate?.resetDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )
        default:
            break
        }
    }

    func frameDidCompleteHandshake() {}
}

Usage

func signOut(clientToken: String) {
    clearLocalCredentials()

    let resetVC = MoonPayResetViewController()
    resetVC.configure(clientToken: clientToken)
    resetVC.resetDelegate = self
    // Present off-screen or with zero-size container; dismiss after complete/error.
}

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

Setup

Dependencies

Key generation

Decryption utility

Base frame controller

Handle JavaScript dialogs

Check frame

Check controller

Usage

Connect frame

Connect controller

Usage

Auth frame

Auth controller

Usage

Add Card frame

Add Card controller

Usage

Buy Button frame

What you’ll need

Buy Button controller

Challenge handling

Usage

Headless mode

Widget frame

Widget controller

Usage

Reset frame

Reset controller

Usage

​Setup

​Dependencies

​Key generation

​Decryption utility

​Base frame controller

​Handle JavaScript dialogs

​Check frame

​Check controller

​Usage

​Connect frame

​Connect controller

​Usage

​Auth frame

​Auth controller

​Usage

​Add Card frame

​Add Card controller

​Usage

​Buy Button frame

​What you’ll need

​Buy Button controller

​Challenge handling

​Usage

​Headless mode

​Widget frame

​Widget controller

​Usage

​Reset frame

​Reset controller

​Usage

Setup

Dependencies

Key generation

Decryption utility

Base frame controller

Handle JavaScript dialogs

Check frame

Check controller

Usage

Connect frame

Connect controller

Usage

Auth frame

Auth controller

Usage

Add Card frame

Add Card controller

Usage

Buy Button frame

What you’ll need

Buy Button controller

Challenge handling

Usage

Headless mode

Widget frame

Widget controller

Usage

Reset frame

Reset controller

Usage