Installation and Initialization

Downloads

The library is distributed as an AAR artifact together with a POM dependency file. Download the version you want to integrate:

Version	AAR	POM
1.0.0	comgateSdk-1.0.0.aar	comgateSdk-1.0.0.pom

Adding the library to your project

Recommended integration steps:

Place the downloaded AAR file in your project (typically in app/libs).
Add the AAR as an app dependency.
Ensure dependencies listed in the POM file are available.

Basic AAR inclusion example in build.gradle.kts:

dependencies {
	implementation(files("libs/comgateSdk-1.0.0.aar"))
}

Information

The downloadable POM file contains the library's declared dependencies. Always integrate a matching AAR + POM pair of the same version.

Warning

The library requires compileSdk 34 and minSdk 28. Verify your app configuration meets these requirements.

AndroidManifest.xml configuration

The library manifest automatically declares required permissions and components. Make sure your app has internet permission:

<uses-permission android:name="android.permission.INTERNET" />

For Google Pay, the library manifest automatically registers this meta-data entry:

<meta-data
	android:name="com.google.android.gms.wallet.api.enabled"
	android:value="true" />

Creating session

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

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

Constructor parameters

Parameter	Type	Required	Description
`checkoutId`	`String`	✅	Checkout SDK connection identifier. Obtain it in the Comgate client portal.
`context`	`Context`	✅	Android app context (typically `applicationContext`).
`threeDSConfig`	`ThreeDSConfig`	✅	3D Secure configuration (UI, timeout, protocol version). See Card Data - 3D Secure.
`lifecycleOwner`	`LifecycleOwner`	✅	Lifecycle owner (for example `Activity`/`Fragment`). Session registers as observer and automatically frees resources on `onDestroy()`.
`devMode`	`Boolean`		Enables development/test mode (for example dev SSL). Also affects Google Pay environment: `true` switches to `TEST`, `false` to `PRODUCTION`. Default `false`.
`googleMerchantId`	`String?`		Google Pay Merchant ID. Required for production Google Pay.
`googleMerchantName`	`String?`		Merchant name shown in the Google Pay payment dialog.
`translation`	`Translation`		Component text translations. Default `Translation.English`.
`lang`	`String?`		BCP 47 / ISO 639-1 language code sent with the payment request (for example `"cs"`, `"en"`). When not provided, the device locale is used if supported. See `ComgateSecureSession.supportedLanguageCodes` for available codes.
`onInitialized`	`((Result<Unit>) -> Unit)?`		Optional callback for automatic session initialization from constructor.

Information

Network infrastructure and communication are managed internally by the library. With standard integration, nothing needs to be changed.

Initialization

The recommended initialization approach is passing the onInitialized callback directly to the ComgateSecureSession constructor.

Android context is passed directly to the constructor, where it is stored internally (application context). A separate initializeContext(...) call is no longer needed.

class MainActivity : AppCompatActivity() {

	private lateinit var session: ComgateSecureSession

	override fun onCreate(savedInstanceState: Bundle?) {
		super.onCreate(savedInstanceState)

		session = ComgateSecureSession(
			checkoutId = "your-checkout-id",
			context = applicationContext,
			threeDSConfig = ThreeDSConfig(),  // default 3DS configuration
			lifecycleOwner = this,
			onInitialized = { result ->
				result.onSuccess {
					// Session is ready - payments can be processed
				}.onFailure { e ->
					// Initialization error
					Log.e("Payment", "Init failed: ${e.message}")
				}
			}
		)

		setContent {
			MaterialTheme {
				Surface(modifier = Modifier.fillMaxSize()) {
					// Your payment form - see Card Data section
				}
			}
		}
	}

}

Information

onInitialized callback (and callback of initialize) is invoked on the main thread. You can update UI directly there.

Manual initialization (alternative)

If you need to start initialization later, you can call initialize() manually. The preferred approach is the suspending function called from a coroutine:

val session = ComgateSecureSession(
	checkoutId = "your-checkout-id",
	context = applicationContext,
	threeDSConfig = ThreeDSConfig(),
	lifecycleOwner = this
)

// Recommended — suspend fun called from coroutine
lifecycleScope.launch {
	val result = session.initialize()
	result.onSuccess {
		// Session is ready
	}.onFailure { e ->
		// Initialization error
	}
}

Session state (SessionState)

ComgateSecureSession exposes sessionState of type SessionState, which describes the current phase of the session lifecycle at any moment. For simple true/false checks, isInitialized is also available.

States

State	When it applies
`SessionState.NotInitialized`	Session was just created or `cleanup()` was called (lifecycle destroy). `initialize()` has not been called yet.
`SessionState.Initializing`	`initialize()` is currently running - network communication and 3DS SDK initialization are in progress.
`SessionState.Ready`	Initialization successfully completed. Session is ready to process payments.
`SessionState.Failed(error)`	Initialization failed. `error` (`ComgateError`) contains the specific cause. Session can be re-initialized by calling `initialize()`.

Typical lifecycle

NotInitialized → Initializing → Ready
							 ↘ Failed → Initializing → Ready   (retry)
Ready → NotInitialized                                         (lifecycle destroy)

Session properties

Property	Type	Description
`sessionState`	`SessionState`	Current session state (see table above).
`isInitialized`	`Boolean`	Shortcut: `true` exactly when `sessionState == SessionState.Ready`.

UI usage (Compose)

By reading session.sessionState, you can react granularly to each state and display the corresponding UI:

val scope = rememberCoroutineScope()

// Composable reacting to session state
when (session.sessionState) {
	SessionState.NotInitialized -> {
		Button(onClick = { scope.launch { session.initialize() } }) {
			Text("Initialize")
		}
	}
	SessionState.Initializing -> {
		CircularProgressIndicator()
	}
	SessionState.Ready -> {
		// Payment form is ready
		PaymentForm(session = session)
	}
	is SessionState.Failed -> {
		val error = (session.sessionState as SessionState.Failed).error
		Text("Initialization error: ${error.message}")
		Button(onClick = { scope.launch { session.initialize() } }) {
			Text("Try again")
		}
	}
}

Initialization errors

SessionState.Failed carries ComgateError with cause details. Most common initialization errors:

Error	Code	Description
`ComgateError.DeviceRooted`	`DEVICE_ROOTED`	Device appears to be rooted or tampered with. Initialization is blocked to protect sensitive card data. Skipped in `devMode`.
`ComgateError.InitNetworkError`	`INIT_NETWORK_ERROR`	Network error while downloading configuration.
`ComgateError.InitUnauthorized`	`INIT_UNAUTHORIZED`	Server returned HTTP 401 during initialization — invalid or expired authorization.
`ComgateError.InitFailed`	`INIT_FAILED`	Initialization failed for another reason (for example invalid server response).
`ComgateError.ApplicationNotAllowed`	`APPLICATION_NOT_ALLOWED`	App package name is not on the allow-list.

Information

Callback passed to initialize() (or onInitialized) and the state transition to Ready/Failed are always delivered on the main thread. sessionState can be read safely from any thread (@Volatile), but always perform UI updates on the main thread.

Translations (localization)

Component texts can be localized using Translation.

Pass translations to ComgateSecureSession via translation
You can use a built-in preset or a custom Translation instance
Only these keys are user-configurable:

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 in card number (PAN) field.
`expiryHint`	Placeholder in expiry field (for example `MM/YY`).
`cvvHint`	Placeholder in CVV field.
`fullNameHint`	Placeholder in cardholder name field.
`panInvalidError`	Error shown below PAN field for invalid card number.
`expiryInvalidMonthError`	Error shown below expiry field for invalid month (for example `13`).
`expiryExpiredError`	Error shown below expiry field when card is expired.
`fullNameRequiredError`	Error shown below name field when empty.
`payButtonText`	Payment button text in idle (active) state.
`payButtonProcessingText`	Payment button text during payment processing.
`statusPaid`	Message displayed in `SecurePaymentStatusView` when payment succeeds.
`statusPending`	Message displayed in `SecurePaymentStatusView` when payment is awaiting final state.
`loadingProcessingText`	Text shown in `SecureLoadingView` (overlay) during payment processing.
`threeDSCancelButton`	Cancel button text in 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`

val 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 expired",
	fullNameRequiredError = "Enter cardholder name",
	payButtonText = "Pay",
	payButtonProcessingText = "Processing...",
	statusPaid = "Paid",
	statusPending = "Processing",
	loadingProcessingText = "Processing payment...",
	threeDSCancelButton = "Cancel"
)

val session = ComgateSecureSession(
	checkoutId = "your-checkout-id",
	context = applicationContext,
	threeDSConfig = ThreeDSConfig(),
	translation = translation,
	lifecycleOwner = this
)

Example with built-in translation:

val session = ComgateSecureSession(
	checkoutId = "your-checkout-id",
	context = applicationContext,
	threeDSConfig = ThreeDSConfig(),
	translation = Translation.English,
	lifecycleOwner = this
)

Supported language codes

ComgateSecureSession.supportedLanguageCodes returns an alphabetically sorted list of BCP 47 / ISO 639-1 language codes for which the library provides a built-in translation. Use this list to populate a language picker in your UI or to detect 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 — auto-detecting device language with fallback to English:

val deviceLang = Locale.getDefault().language.lowercase()
val resolvedLang = deviceLang
    .takeIf { it in ComgateSecureSession.supportedLanguageCodes }
    ?: "en"

val session = ComgateSecureSession(
    checkoutId = "your-checkout-id",
    context = applicationContext,
    threeDSConfig = ThreeDSConfig(),
    translation = Translation.forLanguageCode(resolvedLang),
    lang = resolvedLang,
    lifecycleOwner = this
)

Example — populating a language picker and pairing with a translation:

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

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

Downloads​

Adding the library to your project​

AndroidManifest.xml configuration​

Creating session​

Constructor parameters​

Initialization​

Manual initialization (alternative)​

Session state (SessionState)​

States​

Typical lifecycle​

Session properties​

UI usage (Compose)​

Initialization errors​

Translations (localization)​

Currently available translations​

Supported language codes​

Downloads

Adding the library to your project

AndroidManifest.xml configuration

Creating session

Constructor parameters

Initialization

Manual initialization (alternative)

Session state (SessionState)

States

Typical lifecycle

Session properties

UI usage (Compose)

Initialization errors

Translations (localization)

Currently available translations

Supported language codes