Installation and initialization

Adding the library to your project

The library is distributed as a Swift Package. Add it to your project using Swift Package Manager.

Xcode

1. In Xcode, open File → Add Package Dependencies…
2. Enter the repository URL: https://github.com/comgate-payments/ios-checkout-sdk
3. Choose a version and the target you want to add the library to.
4. Once added, import the library in your source files:

import ComgateSDK

Package.swift

If you are using your own Swift Package, add the dependency like this:

dependencies: [
    .package(url: "https://github.com/comgate-payments/ios-checkout-sdk", from: "0.1.0")
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "ComgateSDK", package: "ComgateSDK")
        ]
    )
]

Warning

The library requires iOS 15.0 or later. Verify that your application's configuration meets this requirement (Deployment Target in the target settings).

Project configuration

Apple Pay capability

If you plan to use Apple Pay, you must:

1. In Xcode, on the Signing & Capabilities tab, add the Apple Pay capability.
2. Select (or create) all Merchant IDs you will use — typically one for sandbox and one for production.
3. In the Apple Developer portal (Identifiers → Merchant IDs), register the corresponding merchant identifier with the format merchant.<your-domain>.

The list of allowed merchant identifiers will appear in your entitlements file:

<key>com.apple.developer.in-app-payments</key>
<array>
    <string>merchant.cz.example.production</string>
    <string>merchant.cz.example.sandbox</string>
</array>

For full Apple Pay configuration details, see Apple Pay.

Third-party keyboards

Third-party keyboards may, in theory, intercept entered characters. For maximum protection of card data, we recommend disabling third-party keyboards in your AppDelegate:

Tip

func application(
    _ application: UIApplication,
    shouldAllowExtensionPointIdentifier extensionPointIdentifier: UIApplication.ExtensionPointIdentifier
) -> Bool {
    extensionPointIdentifier != .keyboard
}

Creating session

The ComgateSecureSession class is the main entry point for working with the library. The session handles:

• internal security initialization,
• 3D Secure initialization,
• card and Apple Pay payment processing.

Constructor parameters

Parameter	Type	Required	Description
checkoutId	String	✅	Checkout SDK connection identifier. Obtain it in the Comgate client portal.
threeDSConfig	ThreeDSConfig	✅	3D Secure configuration (UI, timeout, protocol version). See Card data — 3D Secure.
devMode	Bool		Enables development/testing mode. Default false.
applePayMerchantIdentifier	String?		Apple Pay Merchant ID in merchant.* format. Required for Apple Pay. When nil, Apple Pay is disabled.
applePayDisplayName	String?		Merchant display name shown in the Apple Pay payment sheet.
translation	Translation		Translations for component texts. Default .forCurrentLocale().
lang	String?		Language code (BCP 47 / ISO 639-1) sent with the payment request (e.g. "cs", "en"). When omitted, the device language is used (if supported).

Information

Network infrastructure and communication are managed internally by the library. With a standard integration, no additional setup is required.

Initialization

The recommended approach is to create the session as a @StateObject in your top-level App or root View and call initialize() asynchronously from the .task modifier:

import SwiftUI
import ComgateSDK

@main
struct MyApp: App {
    @StateObject private var session = ComgateSecureSession(
        checkoutId: "your-checkout-id",
        threeDSConfig: ThreeDSConfig()  // default 3DS configuration
    )

    var body: some Scene {
        WindowGroup {
            ContentView(session: session)
                .task {
                    do {
                        try await session.initialize()
                    } catch {
                        print("Init failed: \(error)")
                    }
                }
        }
    }
}

Information

The initialize() method is async throws and runs on the main thread (@MainActor). On failure it throws a ComgateException carrying the specific ComgateError.

Session state (SessionState)

ComgateSecureSession exposes a @Published property state of type SessionState that describes the current lifecycle phase of the session at any point. For simple checks, the isInitialized property is provided.

States

State	When it applies
.notInitialized	Session has just been created. initialize() has not been called yet.
.initializing	initialize() is in progress — network communication and 3DS SDK initialization are running.
.ready	Initialization completed successfully. The session is ready to process payments.
.failed(ComgateError)	Initialization failed. The associated value carries the specific cause. The session can be re-initialized by calling initialize() again.

Session properties

Property	Type	Description
state	SessionState	Current session state (@Published).
isInitialized	Bool	Shortcut: true if and only if state == .ready.
isApplePayConfigured	Bool	true when applePayMerchantIdentifier was supplied and Apple Pay is available.
isProcessingPayment	Bool	true while processPayment(...) or processApplePayPayment(...) is in flight.
translation	Translation	Translations of the current session (read-only).

Use in UI (SwiftUI)

struct ContentView: View {
    @ObservedObject var session: ComgateSecureSession

    var body: some View {
        switch session.state {
        case .notInitialized:
            Button("Initialize") {
                Task { try? await session.initialize() }
            }
        case .initializing:
            ProgressView()
        case .ready:
            PaymentForm(session: session)
        case .failed(let error):
            VStack {
                Text("Initialization error: \(error.message)")
                Button("Retry") {
                    Task { try? await session.initialize() }
                }
            }
        }
    }
}

Initialization errors

The .failed(error) state carries a ComgateError describing the cause. The most common initialization errors:

Error	Code	Description
.deviceRooted	DEVICE_ROOTED	Device appears to be jailbroken or otherwise tampered with. Initialization is blocked to protect card data. The check is skipped in devMode.
.initNetworkError	INIT_NETWORK_ERROR	Network error while loading configuration.
.initUnauthorized	INIT_UNAUTHORIZED	Server returned HTTP 401 during initialization — invalid or expired authorization.
.initFailed	INIT_FAILED	Initialization failed for another reason (e.g. invalid server response).
.applicationNotAllowed	APPLICATION_NOT_ALLOWED	The app's Bundle ID is not on the allow-list of applications.

Information

The state property is published via Combine (@Published) and all updates happen on the main thread. The state can be observed via .onReceive(session.$state) or directly within a SwiftUI body.

Translations (localization)

Component texts can be localized via Translation.

• Translations are passed to ComgateSecureSession through the translation parameter
• You can use a built-in preset, automatic device-language detection, or a custom Translation instance
• The following keys are user-overridable:

Key	Description
panLabel	Label above the card-number (PAN) field.
expiryLabel	Label above the expiry-date field.
cvvLabel	Label above the CVV field.
fullNameLabel	Label above the cardholder-name field.
panHint	Placeholder text in the card-number (PAN) field.
expiryHint	Placeholder text in the expiry-date field (e.g. MM/YY).
cvvHint	Placeholder text in the CVV field.
fullNameHint	Placeholder text in the cardholder-name field.
panInvalidError	Error message displayed under the PAN field when the card number is invalid.
expiryInvalidMonthError	Error message displayed under the expiry field when the month is invalid.
expiryExpiredError	Error message displayed under the expiry field when the card has expired.
fullNameRequiredError	Error message displayed under the name field when the field is empty.
payButtonText	Pay-button text in the idle (active) state.
payButtonProcessingText	Pay-button text while a payment is being processed.
statusPaid	Message shown in SecurePaymentStatusView for a successful payment.
statusAuthorized	Message shown in SecurePaymentStatusView for an authorized payment (preauthorization).
statusPending	Message shown in SecurePaymentStatusView while a payment is awaiting its final status.
loadingProcessingText	Text shown in SecureLoadingView while a payment is being processed.
threeDSCancelButton	Cancel-button text in the 3D Secure verification dialog.

Currently available translations

Translation	Value
English	Translation.english
Bulgarian	Translation.bulgarian
Czech	Translation.czech
Danish	Translation.danish
Estonian	Translation.estonian
Finnish	Translation.finnish
French	Translation.french
Croatian	Translation.croatian
Italian	Translation.italian
Lithuanian	Translation.lithuanian
Latvian	Translation.latvian
Hungarian	Translation.hungarian
German	Translation.german
Dutch	Translation.dutch
Norwegian	Translation.norwegian
Polish	Translation.polish
Portuguese	Translation.portuguese
Romanian	Translation.romanian
Russian	Translation.russian
Greek	Translation.greek
Slovak	Translation.slovak
Slovenian	Translation.slovenian
Spanish	Translation.spanish
Swedish	Translation.swedish
Ukrainian	Translation.ukrainian
Vietnamese	Translation.vietnamese

let translation = Translation(
    panLabel: "Card number",
    expiryLabel: "Expiry",
    cvvLabel: "CVC/CVV",
    fullNameLabel: "Cardholder name",
    panHint: "Card number",
    expiryHint: "MM/YY",
    cvvHint: "CVV",
    fullNameHint: "First and last name",
    panInvalidError: "Invalid card number",
    expiryInvalidMonthError: "Invalid month",
    expiryExpiredError: "Card has expired",
    fullNameRequiredError: "Cardholder name is required",
    payButtonText: "Pay",
    payButtonProcessingText: "Processing…",
    statusPaid: "Paid",
    statusAuthorized: "Authorized",
    statusPending: "Pending",
    loadingProcessingText: "Processing payment…",
    threeDSCancelButton: "Cancel"
)

let session = ComgateSecureSession(
    checkoutId: "your-checkout-id",
    threeDSConfig: ThreeDSConfig(),
    translation: translation
)

Example with a built-in translation:

let session = ComgateSecureSession(
    checkoutId: "your-checkout-id",
    threeDSConfig: ThreeDSConfig(),
    translation: .english
)

Supported language codes

ComgateSecureSession.supportedLanguageCodes returns an alphabetically sorted list of BCP 47 / ISO 639-1 language codes for which the library has built-in translations. This list can be used to populate a language picker in your UI or to check whether the device language is supported.

Currently available codes: bg, cs, da, de, el, en, es, et, fi, fr, hr, hu, it, lt, lv, nl, no, pl, pt, ro, ru, sk, sl, sv, uk, vi

Example — automatic device-language detection with a fallback to English:

let deviceLang = Locale.current.language.languageCode?.identifier ?? "en"
let resolvedLang = ComgateSecureSession.supportedLanguageCodes.contains(deviceLang) ? deviceLang : "en"

let session = ComgateSecureSession(
    checkoutId: "your-checkout-id",
    threeDSConfig: ThreeDSConfig(),
    translation: .forLanguageCode(resolvedLang),
    lang: resolvedLang
)

Example — populating a language picker and wiring it to translations:

// Get the list of supported codes
let languageCodes = ComgateSecureSession.supportedLanguageCodes

// After the user picks a language
let selectedCode = "sk"
let translation = Translation.forLanguageCode(selectedCode)