Installation and Initialization

Adding the library to your project

The library is distributed as an AAR artifact together with a POM dependency file. These files are provided to merchants on request.

Recommended integration steps:

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

Basic AAR inclusion example in build.gradle.kts:

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

Information

The POM file delivered with the AAR contains the library's declared dependencies. During integration, always rely on these delivered artifacts (AAR + POM).

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.
email	String	✅	Customer email address.
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.
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",
			email = "customer@example.com",
			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",
	email = "customer@example.com",
	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.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.

Tip

If you call initialize() again while session is in Initializing, callback immediately receives ComgateError.InitFailed. Wait for transition to Ready or Failed before retrying initialization.

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",
	email = "customer@example.com",
	context = applicationContext,
	threeDSConfig = ThreeDSConfig(),
	translation = translation,
	lifecycleOwner = this
)

Example with built-in translation:

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