### Complete Example in AppCompatActivity

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/google-pay

A full example demonstrating the integration of Google Pay within an `AppCompatActivity`, including session creation, UI setup with `SecureGooglePayButton`, and result handling.

```APIDOC
## Complete Google Pay Integration Example

### Description
This example illustrates a complete implementation of Google Pay integration within an `AppCompatActivity`. It covers the initialization of `ComgateSecureSession` with Google Pay details, setting up the Compose UI, and handling the payment results.

### Activity Setup
```kotlin
class PaymentActivity : AppCompatActivity() {

    private lateinit var session: ComgateSecureSession

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

        // 1. Create session with Google Pay configuration
        session = ComgateSecureSession(
            checkoutId = "your-checkout-id",
            context = applicationContext,
            googleMerchantId = "your-google-pay-merchant-id",
            googleMerchantName = "Store name",
            threeDSConfig = ThreeDSConfig(),
            lifecycleOwner = this,
            onInitialized = { result ->
                result.onFailure { e ->
                    Toast.makeText(this, "Error: ${e.message}", Toast.LENGTH_LONG).show()
                }
            }
        )

        // 2. Setup Compose UI
        setContent {
            MaterialTheme {
                Surface(modifier = Modifier.fillMaxSize()) {
                    GooglePayScreen(session)
                }
            }
        }
    }
}
```

### Composable Screen
```kotlin
@Composable
private fun GooglePayScreen(session: ComgateSecureSession) {
    var resultText by remember { mutableStateOf("") }

    Column(modifier = Modifier.fillMaxSize().padding(16.dp)) {
        // Google Pay button
        SecureGooglePayButton(
            session = session,
            onPaymentResult = { result ->
                resultText = when (result) {
                    is PaymentResult.Paid -> "Payment successful"
                    is PaymentResult.Pending -> "Payment is processing..."
                    is PaymentResult.Cancelled -> "Payment rejected: ${result.errorReason}"
                    is PaymentResult.Failed -> "Error: ${result.error.message}"
                    else -> ""
                }
            },
            paymentParamsProvider = {
                PaymentParams(
                    email = "customer@example.com",
                    price = 100,
                    curr = "CZK",
                    label = "Order #123",
                    refId = "order-123",
                    fullName = "John Smith",
                    country = "CZ"
                )
            },
            modifier = Modifier.fillMaxWidth().height(56.dp)
        )

        if (resultText.isNotEmpty()) {
            Text(text = resultText, modifier = Modifier.padding(top = 8.dp))
        }
    }
}
```
```

--------------------------------

### Initialize and Setup SecureLoadingOverlay

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/indikator-nacitani

Instantiate `SecureLoadingOverlay` and call `setup` with the session and activity. The overlay will automatically manage its visibility during payment processing and detach when the activity is destroyed if it implements `LifecycleOwner`.

```kotlin
import cz.comgate.sdk.ui.SecureLoadingOverlay

val loadingOverlay = SecureLoadingOverlay()
loadingOverlay.setup(session, this)   // 'this' is an Activity / AppCompatActivity

```

--------------------------------

### Example HTTP Redirect Request

Source: https://apidoc.comgate.cz/en/prubeh-platby

This is an example of an HTTP GET request used to redirect a payer to a client's website after a payment attempt. It includes payment identifiers as GET parameters.

```http
GET /result_ok.php?refId=2010102600&transId=AB12-EF34-IJ56 HTTP/2  
```

--------------------------------

### XML Loading Indicator Setup

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/indikator-nacitani

Add `SecureLoadingView` to your XML layout and then bind it to the payment session using the `setup` method in your activity or fragment.

```xml
<cz.comgate.sdk.SecureLoadingView
	android:id="@+id/loadingView"
	android:layout_width="match_parent"
	android:layout_height="wrap_content"
	android:layout_marginTop="12dp"
	app:loadingSpinnerColor="#1E88E5"
	app:loadingTrackColor="#BBDEFB"
	app:loadingStrokeWidth="5dp"
	app:loadingSpinnerSize="52dp"
	app:loadingBackgroundColor="#F5F9FF"
	app:loadingCornerRadius="12dp"
	app:loadingPaddingHorizontal="16dp"
	app:loadingPaddingVertical="20dp" />
```

```kotlin
binding.loadingView.setup(session)
```

--------------------------------

### Complete Apple Pay Integration Example

Source: https://apidoc.comgate.cz/en/mobilni-sdk/ios/apple-pay

A full example demonstrating the integration of Apple Pay, including session initialization, button display, and result handling.

```APIDOC
## Complete example

```swift
import SwiftUI
import ComgateSDK

@main
struct ApplePayApp: App {
    @StateObject private var session = ComgateSecureSession(
        checkoutId: "your-checkout-id",
        applePayMerchantIdentifier: "merchant.cz.example.production",
        applePayDisplayName: "Store name",
        threeDSConfig: ThreeDSConfig()
    )

    var body: some Scene {
        WindowGroup {
            ApplePayScreen(session: session)
                .task {
                    if case .notInitialized = session.state {
                        try? await session.initialize()
                    }
                }
        }
    }
}

struct ApplePayScreen: View {
    @ObservedObject var session: ComgateSecureSession
    @State private var resultText = ""

    var body: some View {
        VStack(spacing: 16) {
            SecureApplePayButton(
                session: session,
                paymentParams: {
                    try! PaymentParams(
                        email: "customer@example.com",
                        price: 100,
                        curr: "CZK",
                        country: "CZ",
                        label: "Order #123",
                        refId: "order-123",
                        fullName: "John Doe"
                    )
                },
                onResult: { result in
                    switch result {
                    case .paid: resultText = "Payment successful"
                    case .authorized: resultText = "Payment authorized"
                    case .pending: resultText = "Payment pending…"
                    case .cancelled(let reason, _): resultText = "Cancelled: \(reason ?? "-")"
                    case .failed(let err): resultText = "Error: \(err.message)"
                    }
                }
            )
            .frame(height: 56)

            if !resultText.isEmpty {
                Text(resultText)
            }
        }
        .padding()
    }
}
```
```

--------------------------------

### Complete Apple Pay App Example

Source: https://apidoc.comgate.cz/en/mobilni-sdk/ios/apple-pay

A full SwiftUI application example demonstrating Apple Pay integration. It includes session initialization, displaying the SecureApplePayButton, and handling payment results.

```swift
import SwiftUI
import ComgateSDK

@main
struct ApplePayApp: App {
    @StateObject private var session = ComgateSecureSession(
        checkoutId: "your-checkout-id",
        applePayMerchantIdentifier: "merchant.cz.example.production",
        applePayDisplayName: "Store name",
        threeDSConfig: ThreeDSConfig()
    )

    var body: some Scene {
        WindowGroup {
            ApplePayScreen(session: session)
                .task {
                    if case .notInitialized = session.state {
                        try? await session.initialize()
                    }
                }
        }
    }
}

struct ApplePayScreen: View {
    @ObservedObject var session: ComgateSecureSession
    @State private var resultText = ""

    var body: some View {
        VStack(spacing: 16) {
            SecureApplePayButton(
                session: session,
                paymentParams: {
                    try! PaymentParams(
                        email: "customer@example.com",
                        price: 100,
                        curr: "CZK",
                        country: "CZ",
                        label: "Order #123",
                        refId: "order-123",
                        fullName: "John Doe"
                    )
                },
                onResult: { result in
                    switch result {
                    case .paid: resultText = "Payment successful"
                    case .authorized: resultText = "Payment authorized"
                    case .pending: resultText = "Payment pending…"
                    case .cancelled(let reason, _): resultText = "Cancelled: \(reason ?? "-")"
                    case .failed(let err): resultText = "Error: \(err.message)"
                    }
                }
            )
            .frame(height: 56)

            if !resultText.isEmpty {
                Text(resultText)
            }
        }
        .padding()
    }
}
```

--------------------------------

### Background Payment Setup - HTTP Response

Source: https://apidoc.comgate.cz/en/prubeh-platby

Example of a successful HTTP response from the Comgate payment gateway after a payment setup request. It includes a transaction ID and a redirect URL for the payer.

```http
HTTP/2 200 OK  
  
code=0&message=OK&transId=AB12-CD34-EF56&redirect=https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2Findex%3Fid%3DAB12-CD34-EF56  
```

--------------------------------

### Complete Google Pay Payment Flow in Activity

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/google-pay

A complete example demonstrating the setup of ComgateSecureSession with Google Pay configuration and the integration of SecureGooglePayButton within an AppCompatActivity. It handles payment results and displays them to the user.

```kotlin
class PaymentActivity : AppCompatActivity() {

	private lateinit var session: ComgateSecureSession

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

		// 1. Create session with Google Pay configuration
		session = ComgateSecureSession(
			checkoutId = "your-checkout-id",
			context = applicationContext,
			googleMerchantId = "your-google-pay-merchant-id",
			googleMerchantName = "Store name",
			threeDSConfig = ThreeDSConfig(),
			lifecycleOwner = this,
			onInitialized = {
				result.onFailure { e ->
					Toast.makeText(this, "Error: ${e.message}", Toast.LENGTH_LONG).show()
				}
			}
		)

		// 2. Setup Compose UI
		setContent {
			MaterialTheme {
				Surface(modifier = Modifier.fillMaxSize()) {
					GooglePayScreen(session)
				}
			}
		}
	}
}

@Composable
private fun GooglePayScreen(session: ComgateSecureSession) {
	var resultText by remember { mutableStateOf("") }

	Column(modifier = Modifier.fillMaxSize().padding(16.dp)) {
		// Google Pay button
		SecureGooglePayButton(
			session = session,
			onPaymentResult = {
				resultText = when (result) {
					is PaymentResult.Paid -> "Payment successful"
					is PaymentResult.Pending -> "Payment is processing..."
					is PaymentResult.Cancelled -> "Payment rejected: ${result.errorReason}"
				is PaymentResult.Failed -> "Error: ${result.error.message}"
				else -> ""
				}
			},
			paymentParamsProvider = {
				PaymentParams(
					email = "customer@example.com",
					price = 100,
					curr = "CZK",
					label = "Order #123",
					refId = "order-123",
					fullName = "John Smith",
					country = "CZ"
				)
			},
			modifier = Modifier.fillMaxWidth().height(56.dp)
		)

		if (resultText.isNotEmpty()) {
			Text(text = resultText, modifier = Modifier.padding(top = 8.dp))
		}
	}
}

```

--------------------------------

### Merchant List Response Example

Source: https://apidoc.comgate.cz/en/konfigurace-a-sprava-v2

Example of a successful response from the /v2.0/merchants endpoint, detailing store information.

```json
{
    "0": {
        "merchant": "123456",
        "secret": "M3hZVScYZKq9t...",
        "allowed_payment_creation_method": "REST/POST",
        "shop": "eshop.cz",
        "url": "https://eshop.cz/",
        "contract_status": "AKTIVNI",
        "store_in_production": true,
        "reported_to_card_schemes": true,
        "currencies": [
            "CZK",
            "EUR"
        ],
        "ip_addresses": [
            "185.123.45.67", 
            "185.123.45.68"
        ]
    },
    "code": 0,
    "message": "OK"
}

```

--------------------------------

### Background Payment Setup - HTTP Request using cURL

Source: https://apidoc.comgate.cz/en/prubeh-platby

Initiates a payment setup request to the Comgate payment gateway. Use this to ensure secure payment initiation and identify individual payments. Parameters are sent as POST data.

```bash
curl -X POST -i --data "merchant=123456&price=10000&curr=CZK&label=Beatles%20-0%Help&refId=2010102600&method=ALL&prepareOnly=true&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" https://payments.comgate.cz/v1.0/create  
```

--------------------------------

### Complete Payment Result Handling Example

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/vysledky-platby

A comprehensive example demonstrating how to handle different PaymentResult states (Paid, Authorized, Pending, Cancelled, Failed) within a Composable function. It updates the SecurePaymentStatusView, manages visibility, and logs errors.

```kotlin
@Composable  
private fun PaymentResultHandler(session: ComgateSecureSession) {  
	val statusState = rememberPaymentStatusState()  
	var resultText by remember { mutableStateOf("") }  
	var resultVisible by remember { mutableStateOf(false) }  
  
	// ... (card fields, collector, button - see Card Data section)  
  
	// Payment result handling:  
	fun handlePaymentResult(result: PaymentResult) {  
		when (result) {  
			is PaymentResult.Paid -> {  
				statusState.showStatus(result)  
				resultVisible = true  
				resultText = "Payment completed\nTransId: ${result.transId ?: "-"}"  
			}

			is PaymentResult.Authorized -> {  
				statusState.showStatus(result)  
				resultVisible = true  
				resultText = "Payment authorized\nTransId: ${result.transId}"  
			}

			is PaymentResult.Pending -> {  
				statusState.showStatus(result)  
				resultVisible = true  
				resultText = "Payment is processing\nTransId: ${result.transId ?: "-"}"  
			}

			is PaymentResult.Cancelled -> {  
				resultVisible = false  
				statusState.showStatus(result)  
				// Optional: Toast.makeText(context, "Payment canceled: ${result.errorReason ?: "no detail"}", Toast.LENGTH_LONG).show()  
			}

			is PaymentResult.Failed -> {  
				resultVisible = false  
				statusState.showStatus(result)  
				Log.w("PaymentResult", "Failed: ${result.error.code} - ${result.error.message}")  
				// Optional: Toast.makeText(context, "Error: ${result.error.message}", Toast.LENGTH_LONG).show()  
			}
		}
	}
  
	Column(modifier = Modifier.fillMaxWidth()) {  
		SecurePaymentStatusView(  
			state = statusState,  
			modifier = Modifier.fillMaxWidth()  
		)

		if (resultVisible) {
			Text(  
				text = resultText,  
				modifier = Modifier.padding(top = 8.dp)  
			)
		}
	}
}
```

--------------------------------

### SecureLoadingIndicator Compose Example

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/indikator-nacitani

Example of using SecureLoadingIndicator within a Compose `update` block, demonstrating how to apply various customization methods.

```APIDOC
## Compose Example (`update` block)

```kotlin
SecureLoadingIndicator(
	state = loadingState,
	modifier = Modifier.fillMaxWidth(),
	update = {
		setSpinnerColor(Color.parseColor("#FF0000"))
		setTrackColor(Color.parseColor("#FFEBEE"))
		setStrokeWidthDp(4f)
		setSpinnerSizeDp(48f)
		setLoadingBackgroundColor(Color.WHITE)
		setLoadingCornerRadiusDp(12f)
		setLoadingPaddingDp(16f, 20f)
	}
)
```
```

--------------------------------

### Creating ComgateSecureSession

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/instalace

Example of creating an instance of ComgateSecureSession, the main entry point for payment processing, with necessary parameters and an initialization callback.

```APIDOC
## 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.

### 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.

```kotlin
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 {
					// Initialization error
					Log.e("Payment", "Init failed: ${it.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.
```

--------------------------------

### Example Content-Security-Policy Header

Source: https://apidoc.comgate.cz/en/zabezpeceni

Provides an example of a Content-Security-Policy header that allows Comgate's payment gateway to be displayed within an iframe. Ensure all necessary directives are included for proper security.

```http
Content-Security-Policy:  
    default-src 'self';  
    script-src 'self';  
    style-src 'self';  
    img-src 'self';  
    connect-src 'self';  
    form-action 'self';  
    frame-src *;  
    frame-ancestors 'none';  
    upgrade-insecure-requests  

```

--------------------------------

### Simple Integration - Redirection Link (GET)

Source: https://apidoc.comgate.cz/en/prubeh-platby

This HTML anchor tag provides a direct link for simple integration, redirecting the payer to the payment gateway via GET. Remember to include the `rel="nofollow"` parameter.

```html
<a href="https://payments.comgate.cz/v1.0/create?merchant=XXXX&price=100&curr=CZK&label=My%20service&refId=10980891&method=ALL&country=CZ" rel="nofollow">Pay</a>  

```

--------------------------------

### Example Payment Result Delivery - HTTP POST using cURL

Source: https://apidoc.comgate.cz/en/push-notifikace

This example demonstrates how to send payment result data using an HTTP POST request with cURL. Ensure all required parameters are included and correctly formatted.

```bash
curl -X POST -i --data "merchant=123456&test=false&price=10000&curr=CZK&label=Beatles%20-%20Help&refId=2010102600&method=CARD&email=info%40customer.com&phone=%2B420123456789&transId=AB12-EF34-IJ56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&status=PAID" https://example.com/handler.php  

```

--------------------------------

### Successful Configuration Response (JSON)

Source: https://apidoc.comgate.cz/en/api/post

This is an example of a successful response (HTTP 200) when updating the configuration. It confirms the update and returns the configured settings.

```json
{
  "code": 0,
  "message": "OK",
  "merchant": 123123,
  "secret": "secret",
  "gateway_logo": "data:image/png;base64,...",
  "gateway_background": "data:image/png;base64,...",
  "gateway_color_page": "#C2E7FF",
  "gateway_color_header": "#f2c7af",
  "gateway_signature": "string",
  "url_paid": "string",
  "url_cancelled": "string",
  "url_pending": "string",
  "url_push": "string",
  "ip_addresses": "{1.1.1.1/1,2.2.2.2/2}",
  "active": ""

}
```

--------------------------------

### Styling the Loading Overlay

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/indikator-nacitani

Customize the appearance of the loading overlay, including colors, sizes, text, and background. These methods can be called before or after `setup`.

```APIDOC
## Styling
The styling API of `SecureLoadingOverlay` mirrors `SecureLoadingView` exactly. All methods can be called before or after `setup`:

Method| Description| Default  
---|---|---  
`setSpinnerColor(color: Int)`| Rotating arc color| `#4287f5`  
`setTrackColor(color: Int)`| Static track color| `#E0E0E0`  
`setStrokeWidthDp(dp: Float)`| Spinner stroke width in dp| `4f`  
`setSpinnerSizeDp(dp: Float)`| Spinner size in dp| `48f`  
`setLoadingText(text: String?)`| Text below spinner; `null` or empty string hides label| auto from session translation  
`setLoadingTextColor(color: Int)`| Label text color| `#666666`  
`setLoadingTextSizeSp(sp: Float)`| Label text size in sp| `14f`  
`setLoadingTextGapDp(dp: Float)`| Gap between spinner and label in dp| `8f`  
`setLoadingFontFamily(family: String)`| Label font family (e.g. `"sans-serif-medium"`)| system default  
`setLoadingTypeface(typeface: Typeface)`| Label typeface directly| system default  
`setLoadingBackgroundColor(color: Int)`| Card background color; `Color.TRANSPARENT` for a card-less spinner| white  
`setLoadingCornerRadiusDp(dp: Float)`| Card corner radius in dp| `16f`  
`setLoadingPaddingDp(horizontalDp: Float, verticalDp: Float)`| Card inner padding in dp| `28f × 28f`  

### Example
```kotlin
val loadingOverlay = SecureLoadingOverlay()
loadingOverlay.setSpinnerColor(Color.parseColor("#1E88E5"))
loadingOverlay.setTrackColor(Color.parseColor("#BBDEFB"))
loadingOverlay.setStrokeWidthDp(4f)
loadingOverlay.setSpinnerSizeDp(52f)
loadingOverlay.setLoadingCornerRadiusDp(16f)
loadingOverlay.setLoadingPaddingDp(28f, 28f)
loadingOverlay.dimAmount = 0.6f
loadingOverlay.setup(session, this)
```
```

--------------------------------

### Adding the AAR library to your project

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/instalace

Example of how to include the Comgate SDK AAR file as a dependency in your Android project's build.gradle.kts file.

```APIDOC
## Adding the library to your project

Recommended integration steps:
  1. Place the downloaded AAR file in your project (typically in `app/libs`).
  2. Add the AAR as an app dependency.
  3. Ensure dependencies listed in the POM file are available.

Basic AAR inclusion example in `build.gradle.kts`:
```kotlin
dependencies {
	implementation(files("libs/comgateSdk-1.0.0.aar"))
}
```
```

--------------------------------

### Initialize ComgateSecureSession with Built-in English Translation

Source: https://apidoc.comgate.cz/en/mobilni-sdk/ios/instalace

Instantiate `ComgateSecureSession` using the default English translation. This is a quick way to get started if no custom translations are needed.

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

--------------------------------

### IP Whitelist Format Examples

Source: https://apidoc.comgate.cz/en/zabezpeceni

Illustrates the correct formatting for IP addresses and subnets when configuring an IP whitelist. Use '0.0.0.0/0' with caution as it allows access from any IP address.

```text
8.8.8.8 IP Google  
1.1.1.1 IP cloudflare  
8.8.0.0/16 Subnet Google  
1.1.1.0/24 Subnet Cloudflare  
0.0.0.0/0 Entire internet  

```

--------------------------------

### Get Payment Status using curl

Source: https://apidoc.comgate.cz/en/api/post

This example demonstrates how to retrieve the status of a payment using the Comgate API. You need to provide your merchant ID, the transaction ID, and your secret key.

```bash
curl -X POST https://payments.comgate.cz/v1.0/status \
--data "&merchant=123456&transId=1234567890&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'
```

--------------------------------

### Background Payment Setup - HTTP Request

Source: https://apidoc.comgate.cz/en/prubeh-platby

Initiates a payment with the payment gateway server using an HTTP POST request. Parameters are passed as POST parameters, and the response includes a transaction ID and a redirect URL.

```APIDOC
## POST /v1.0/create

### Description
Initiates a payment transaction with the payment gateway. This is an optional step for setting up a payment, especially when unique transaction identification is required.

### Method
POST

### Endpoint
https://payments.comgate.cz/v1.0/create

### Parameters
#### Query Parameters
- **merchant** (string) - Required - Your merchant ID.
- **price** (integer) - Required - The amount of the payment in the smallest currency unit (e.g., cents for USD, hellers for CZK).
- **curr** (string) - Required - The currency code (e.g., CZK, EUR, USD).
- **label** (string) - Optional - A description or label for the payment.
- **refId** (string) - Optional - A unique reference ID from your system for the payment.
- **method** (string) - Optional - Specifies the payment methods to offer. 'ALL' means all available methods.
- **prepareOnly** (boolean) - Optional - If true, creates the transaction without requiring immediate payment.
- **secret** (string) - Required - Your secret key for authentication.

### Request Example
```json
{
  "example": "curl -X POST -i --data \"merchant=123456&price=10000&curr=CZK&label=Beatles%20-0%Help&refId=2010102600&method=ALL&prepareOnly=true&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y\" https://payments.comgate.cz/v1.0/create"
}
```

### Response
#### Success Response (200)
- **code** (integer) - The response code. 0 indicates success.
- **message** (string) - The response message. 'OK' for success.
- **transId** (string) - The unique transaction ID generated by the Comgate payment system.
- **redirect** (string) - The URL to which the payer should be redirected to complete the payment.

#### Response Example
```json
{
  "example": "HTTP/2 200 OK\n\ncode=0&message=OK&transId=AB12-CD34-EF56&redirect=https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2Findex%3Fid%3DAB12-CD34-EF56"
}
```
```

--------------------------------

### Check GSA API Version

Source: https://apidoc.comgate.cz/en/terminaly/gsa-protokol

Iteratively check for the highest supported GSA API version by sending GET requests to versioned info endpoints. Start from the highest version and move downwards. A successful response includes a JSON object with protocol details; an unsupported version returns 'Endpoint not supported.' with a 404 status.

```HTTP
GET http://{terminal_ip_address}:{port}/api/switchio/pay/v8/info
```

```HTTP
GET http://{terminal_ip_address}:{port}/api/switchio/pay/v7/info
```

```HTTP
GET http://{terminal_ip_address}:{port}/api/switchio/pay/v6/info
```

```HTTP
GET http://{terminal_ip_address}:{port}/api/switchio/pay/v5/info
```

```HTTP
GET http://{terminal_ip_address}:{port}/api/switchio/pay/v4/info
```

```HTTP
GET http://{terminal_ip_address}:{port}/api/switchio/pay/v2/info
```

```HTTP
GET http://{terminal_ip_address}:{port}/paya/info
```

--------------------------------

### Create Initial Recurring Payment

Source: https://apidoc.comgate.cz/en/api/rest

This example demonstrates how to initiate a recurring payment. The first payment is processed like a standard payment, but includes the 'initRecurring' parameter. Subsequent payments are linked to this initial transaction.

```json
{
  "test": true,
  "price": 10000,
  "curr": "CZK",
  "label": "Test Product",
  "refId": "REF12345",
  "initRecurring": true
}
```

--------------------------------

### SecureLoadingOverlay Usage

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/indikator-nacitani

How to create and set up the SecureLoadingOverlay for displaying a floating loading indicator.

```APIDOC
## SecureLoadingOverlay

`SecureLoadingOverlay` is an alternative loading indicator variant that appears as a **floating panel rendered on top of the entire screen** with a dimmed background. It is not a `View` and should be created as a plain object.

### Usage

Create an instance, optionally configure styling, and call `setup(session, activity)`:

```kotlin
import cz.comgate.sdk.ui.SecureLoadingOverlay

val loadingOverlay = SecureLoadingOverlay()
loadingOverlay.setup(session, this) // 'this' is an Activity / AppCompatActivity
```

After calling `setup`, the overlay shows and hides automatically based on payment processing status. It detaches automatically if the activity implements `LifecycleOwner`. If not, call `detach()` manually in `onDestroy`.
```

--------------------------------

### Install Comgate Claude Plugin

Source: https://apidoc.comgate.cz/en/comgate-claude-plugin

Install the Comgate plugin for Claude Code from its marketplace. This command adds the plugin to your Claude Code environment.

```bash
/plugin marketplace add comgate-payments/claude-plugin
```

```bash
/plugin install comgate@comgate
```

--------------------------------

### Single Transfer JSON Response Example

Source: https://apidoc.comgate.cz/en/api/rest

This is an example of a successful JSON response when retrieving details for a single transfer. It includes various transaction-specific fields.

```json
[
  {
    "typ": 1,
    "Merchant": "123456",
    "Datum založení": "2023-01-06 14:11:30",
    "Datum zaplacení": "2023-01-06 14:21:30",
    "Datum převodu": "2023-01-10",
    "Měsíc fakturace": null,
    "ID Comgate": "AAAA-BBBB-CCCC",
    "Metoda": "Card payment",
    "Produkt": null,
    "Popis": "description eshop payment",
    "E-mail plátce": "name.lastname@email.cz",
    "Variabilní symbol plátce": "123456789",
    "Variabilní symbol převodu": "123456789",
    "ID od klienta": "1234",
    "Měna": "EUR",
    "Potvrzená částka": "10,00",
    "Převedená částka": "10,00",
    "Poplatek celkem": "0,35",
    "Poplatek mezibankovní": "0,25",
    "Poplatek asociace": "0,25",
    "Poplatek zpracovatel": "-0,15",
    "Typ karty": "EU_UNREGULATED"
}

]
```

--------------------------------

### Challenge Window Themes

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/karetni-data

Information on prebuilt themes for the challenge screen and how to apply them.

```APIDOC
## Challenge window themes

The library includes four prebuilt themes for challenge screen:

| Theme                           | Description                                           |
|---------------------------------|-------------------------------------------------------|
| `ComgateSdk`                    | Light dialog (90 % of screen width, centered) - **default** |
| `ComgateSdk.Dark`               | Dark dialog                                           |
| `Theme.SecureFields.3DS.FullScreen` | Light full-screen mode                                |
| `Theme.SecureFields.3DS.FullScreen.Dark` | Dark full-screen mode                                 |

To switch theme, add this style override in app `res/values/styles.xml`:

```xml
<!-- res/values/styles.xml -->
<style name="Theme.SecureFields.3DS.Challenge"
	   parent="Theme.SecureFields.3DS.FullScreen" />
```

### Tip
Dialog corner radius can be customized by defining `securefields_3ds_dialog_corner_radius` in your app resources:

```xml
<!-- res/values/dimens.xml -->
<dimen name="securefields_3ds_dialog_corner_radius">16dp</dimen>
```

Alternatively, set corner radius programmatically using `challengeWindowCornerRadiusDp` in `ThreeDSConfig`.
```

--------------------------------

### Populating Currency and Country Pickers

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/karetni-data

Use PaymentParams.supportedCurrencies and PaymentParams.supportedCountries to populate UI pickers for currency and country selection. The example shows how to initialize PaymentParams with selected values.

```kotlin
// Available currencies for a UI picker  
val currencies = PaymentParams.supportedCurrencies  // ["BGN", "CHF", "CZK", ...]  
  
// Available countries for a UI picker  
val countries = PaymentParams.supportedCountries    // ["ALL", "AT", "BE", "CY", "CZ", ...]  
  
PaymentParams(  
    email = "customer@example.com",  
    price = 10000,  
    curr = selectedCurrency,   // value from picker  
    country = selectedCountry, // value from picker  
    label = "Order",  
    refId = "order-123",  
    fullName = "John Doe"  
)

```

--------------------------------

### Configure SecureLoadingOverlay Styling

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/indikator-nacitani

Customize the appearance of the loading overlay by setting spinner color, track color, stroke width, size, text properties, background, corner radius, and padding. Call these methods before or after setup.

```kotlin
val loadingOverlay = SecureLoadingOverlay()
loadingOverlay.setSpinnerColor(Color.parseColor("#1E88E5"))
loadingOverlay.setTrackColor(Color.parseColor("#BBDEFB"))
loadingOverlay.setStrokeWidthDp(4f)
loadingOverlay.setSpinnerSizeDp(52f)
loadingOverlay.setLoadingCornerRadiusDp(16f)
loadingOverlay.setLoadingPaddingDp(28f, 28f)
loadingOverlay.dimAmount = 0.6f
loadingOverlay.setup(session, this)
```

--------------------------------

### Get Terminal Status

Source: https://apidoc.comgate.cz/en/api/rest-terminal

Checks if the payment terminal is online and available.

```APIDOC
## GET /v2.0/terminal.json

### Description
Verifies the online status of the payment terminal.

### Method
GET

### Endpoint
/v2.0/terminal.json

### Parameters
#### Header Parameters
- **authorization** (string) - Required - Authorization header in the format: `Authorization: Basic [base64_encode(merchant:secret)]`.

### Response
#### Success Response (200)
- **code** (integer) - Method return code. 0 indicates success.
- **message** (string) - Description of the return code.

#### Response Example
```json
{
  "code": 0,
  "message": "OK"
}
```
```

--------------------------------

### Get Payment Transaction Status

Source: https://apidoc.comgate.cz/en/api/rest

Retrieve the status of a payment transaction using its transaction ID.

```APIDOC
## GET /v2.0/payment/transId/{transId}.json

### Description
Retrieves the status and details of a specific payment transaction.

### Method
GET

### Endpoint
https://payments.comgate.cz/v2.0/payment/transId/{transId}.json

### Parameters
#### Path Parameters
- **transId** (string) - Required - The unique identifier of the transaction.

#### Header Parameters
- **Authorization** (string) - Required - Authorization header in the format: 'Authorization: Basic [base64_encode(merchant:secret)]'.

### Response
#### Success Response (200)
- **code** (integer) - Status code of the operation.
- **message** (string) - Description of the status.
- **test** (boolean) - Indicates if the transaction was a test.
- **price** (string) - The amount of the payment.
- **curr** (string) - The currency of the payment.
- **label** (string) - Short description of the product.
- **refId** (string) - Payment reference ID from the e-shop system.
- **payerId** (string) - Identifier for the payer.
- **method** (string) - Payment method used.
- **account** (string) - E-shop bank account identifier.
- **email** (string) - Payer's email address.
- **name** (string) - Product identifier.
- **phone** (string) - Payer's phone number.
- **transId** (string) - The unique transaction identifier.
- **status** (string) - The current status of the payment (e.g., PAID).
- **payerName** (string) - Name of the payer.
- **payerAcc** (string) - Payer's account information.
- **fee** (string) - Transaction fee.
- **vs** (string) - Variable symbol.
- **cardValid** (string) - Card validity information.
- **cardNumber** (string) - Masked card number.
- **appliedFee** (integer) - The applied fee amount.
- **appliedFeeType** (string) - Type of applied fee.
- **paymentErrorReason** (string) - Reason for payment error, if any.

### Response Example
```json
{
  "code": 0,
  "message": "OK",
  "test": "false",
  "price": "10000",
  "curr": "CZK",
  "label": "Beatles - Help",
  "refId": "2010102600",
  "payerId": "string",
  "method": "ALL",
  "account": "string",
  "email": "platce@email.com",
  "name": "string",
  "phone": "string",
  "transId": "AB12-CD34-EF56",
  "status": "PAID",
  "payerName": "string",
  "payerAcc": "string",
  "fee": "string",
  "vs": "string",
  "cardValid": "string",
  "cardNumber": "string",
  "appliedFee": 0,
  "appliedFeeType": "string",
  "paymentErrorReason": "string"
}
```
```

--------------------------------

### Get Refund Status

Source: https://apidoc.comgate.cz/en/api/rest-terminal

Retrieves the status of a refund transaction using its unique transaction ID.

```APIDOC
## GET /v2.0/terminalRefund/transId/{transId}.json

### Description
Retrieves the status of a refund transaction.

### Method
GET

### Endpoint
https://payments.comgate.cz/v2.0/terminalRefund/transId/{transId}.json

### Parameters
#### Path Parameters
- **transId** (string) - Required - Unique alphanumeric identifier (code) of the transaction.

#### Header Parameters
- **Authorization** (string) - Required - Authorization header in the format: `Authorization: Basic [base64_encode(merchant:secret)]`.

### Response
#### Success Response (200)
- **code** (integer) - Method return code.
- **message** (string) - Method return code and error description.
- **price** (string) - Price of refund in cents or pennies.
- **curr** (string) - Currency code according to ISO 4217.
- **refId** (string) - Refund reference.
- **transId** (string) - Unique alphanumeric identifier (code) of the transaction.
- **status** (string) - Current refund status (PENDING, PAID, CANCELLED).
- **cardNumber** (string) - Partial payer card number (if applicable).
- **reversed** (boolean) - Flag indicating whether the refund was reversed.

#### Response Example
```json
{
  "code": 0,
  "message": "OK",
  "price": "1000",
  "curr": "CZK",
  "refId": "2010102600",
  "transId": "AB-CD123-EF456",
  "status": "PAID",
  "cardNumber": "string",
  "reversed": true
}
```
```

--------------------------------

### Jetpack Compose Loading Indicator Setup

Source: https://apidoc.comgate.cz/en/mobilni-sdk/android/indikator-nacitani

Use `rememberLoadingIndicatorState` to create and bind the loading indicator state to a payment session in Jetpack Compose. No further initialization is needed.

```kotlin
import cz.comgate.sdk.compose.*

val loadingState = rememberLoadingIndicatorState(session)

SecureLoadingIndicator(
	state = loadingState,
	modifier = Modifier
		.fillMaxWidth()
		.padding(top = 12.dp)
)
```

--------------------------------

### ThreeDSConfig Initialization

Source: https://apidoc.comgate.cz/en/mobilni-sdk/ios/karetni-data

Demonstrates how to initialize the ThreeDSConfig struct and pass it to the ComgateSecureSession initializer for configuring 3DS behavior.

```APIDOC
## ThreeDSConfig Initialization

### Description
Configure 3DS by creating a `ThreeDSConfig` object and passing it to the `ComgateSecureSession` initializer. This allows customization of the challenge screen, default message version, timeouts, and corner radius.

### Parameters
#### `ThreeDSConfig` Parameters
- `uiCustomization` (ThreeDSUiCustomization?): Customizes the challenge screen appearance. Defaults to `nil` for default styles.
- `defaultMessageVersion` (String): Sets the 3DS protocol version. Defaults to `"2.2.0"`.
- `challengeTimeoutMinutes` (Int): Maximum time in minutes (1–30) to wait for challenge completion. Defaults to `5`.
- `challengeWindowCornerRadiusDp` (Int?): Corner radius of the challenge window (0–64). Defaults to `nil` for default radius.

### Code Example
```swift
let threeDSConfig = ThreeDSConfig(
    uiCustomization: threeDSUi,
    defaultMessageVersion: "2.2.0",
    challengeTimeoutMinutes: 5,
    challengeWindowCornerRadiusDp: 16
)

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

--------------------------------

### Get Terminal Status

Source: https://apidoc.comgate.cz/en/api/rest-terminal

Checks the current connection status of the terminal to the Comgate authorization server.

```APIDOC
## GET /v2.0/terminal.json

### Description
Retrieves the connection status of the terminal to the authorization server.

### Method
GET

### Endpoint
https://payments.comgate.cz/v2.0/terminal.json

### Parameters
#### Header Parameters
- **authorization** (string) - Required - Authorization header in the format: `Authorization: Basic [base64_encode(merchant:secret)]`.

### Response
#### Success Response (200)
- **status** (string) - Status of the connection test to the authorization server. Possible values: 'ONLINE', 'OFFLINE', 'BUSY', 'UNKNOWN'.

### Response Example
```json
{
  "status": "ONLINE"
}
```
```

--------------------------------

### Initiate Recurring Payment (cURL)

Source: https://apidoc.comgate.cz/en/api/post

Use this cURL command to initiate a recurring payment. Ensure all required parameters like merchant ID, price, currency, and secret are correctly provided. The 'initRecurringId' is crucial for linking to an initial payment.

```bash
curl -X POST https://payments.comgate.cz/v1.0/recurring \
--data "&merchant=123456&test=1&price=10000&curr=CZK&refId=2010102600&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&initRecurringId=AB12-CD34-EF56" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'
```

--------------------------------

### Retrieve Merchant List

Source: https://apidoc.comgate.cz/en/konfigurace-a-sprava-v2

Use this endpoint to get a list of all stores under your management. Requires developer credentials.

```php
$I->sendGet("https://payments.comgate.cz/v2.0/merchants", 
[
    'developer' => 'your_developer_id',
    'secret' => 'your_developer_secret'
]);

```

--------------------------------

### Get Payment Gateway Status

Source: https://apidoc.comgate.cz/en/status-api

Retrieves the current operational status of the payment gateway. The endpoint is hosted on status.comgate.cz.

```APIDOC
## GET /health

### Description
Returns the current status of the payment gateway.

### Method
GET

### Endpoint
https://status.comgate.cz/health

### Response
#### Success Response (200)
- **gateway** (string) - Status of the gateway: `OK` or `OUTAGE`.
- **date** (string) - Current server date and time in ISO 8601 format (UTC).

### Response Example
```json
{
  "gateway": "OK",
  "date": "2025-06-04T07:05:54Z"
}
```
```