> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kotlin SDK

> Official Fyatu Kotlin SDK — card issuing and payment API client for Kotlin and Android applications.

<Warning>
  This SDK is coming soon. Subscribe to our [changelog](/v3/changelog/overview) to be notified when it's released.
</Warning>

The official Kotlin SDK for FYATU API v3, designed for Kotlin/JVM and Android development.

## Requirements

* Kotlin 1.9 or higher
* JVM 11+ or Android API 26+

## Installation

### Gradle (Kotlin DSL)

```kotlin theme={null}
dependencies {
    implementation("com.fyatu:fyatu-kotlin:1.0.0")
}
```

### Gradle (Groovy)

```groovy theme={null}
dependencies {
    implementation 'com.fyatu:fyatu-kotlin:1.0.0'
}
```

## Quick Start

```kotlin theme={null}
import com.fyatu.Fyatu
import com.fyatu.models.*

val fyatu = Fyatu(
    appId = "your_app_id",
    secretKey = "your_secret_key"
)

// Create a collection
val collection = fyatu.collections.create(
    CreateCollectionParams(
        amount = 10.00,
        currency = "USD",
        reference = "order_123",
        description = "Payment for Order #123",
        customer = Customer(
            email = "customer@example.com",
            name = "Alice Example"
        ),
        redirectUrl = "https://yoursite.com/payment/success",
        webhookUrl = "https://yoursite.com/webhooks/fyatu"
    )
)

println(collection.checkoutUrl)
```

## Coroutines Support

```kotlin theme={null}
import kotlinx.coroutines.*

suspend fun main() = coroutineScope {
    val fyatu = Fyatu(
        appId = "your_app_id",
        secretKey = "your_secret_key"
    )

    // Create multiple collections concurrently
    val collections = listOf("order_1", "order_2", "order_3").map { ref ->
        async {
            fyatu.collections.create(
                CreateCollectionParams(
                    amount = 10.00,
                    currency = "USD",
                    reference = ref
                )
            )
        }
    }.awaitAll()

    collections.forEach { println("Created: ${it.id}") }
}
```

## Android Integration

### Gradle Setup

```kotlin theme={null}
// app/build.gradle.kts
android {
    defaultConfig {
        buildConfigField("String", "FYATU_APP_ID", "\"${project.properties["fyatu.appId"]}\"")
        buildConfigField("String", "FYATU_SECRET_KEY", "\"${project.properties["fyatu.secretKey"]}\"")
    }
}

dependencies {
    implementation("com.fyatu:fyatu-kotlin:1.0.0")
}
```

### ViewModel Usage

```kotlin theme={null}
class PaymentViewModel : ViewModel() {

    private val fyatu = Fyatu(
        appId = BuildConfig.FYATU_APP_ID,
        secretKey = BuildConfig.FYATU_SECRET_KEY
    )

    private val _checkoutUrl = MutableStateFlow<String?>(null)
    val checkoutUrl: StateFlow<String?> = _checkoutUrl

    fun createPayment(amount: Double, reference: String) {
        viewModelScope.launch {
            try {
                val collection = fyatu.collections.create(
                    CreateCollectionParams(
                        amount = amount,
                        currency = "USD",
                        reference = reference
                    )
                )
                _checkoutUrl.value = collection.checkoutUrl
            } catch (e: FyatuException) {
                // Handle error
            }
        }
    }
}
```

## Features

* **Kotlin-First Design** - Idiomatic Kotlin with DSL builders
* **Coroutines Support** - Full suspend function support
* **Android Compatible** - Works with Android API 26+
* **Null Safety** - Leverages Kotlin's null safety
* **Automatic Token Management** - Handles JWT refresh automatically
* **Data Classes** - All models are Kotlin data classes

## Configuration Options

```kotlin theme={null}
val fyatu = Fyatu(
    appId = "your_app_id",
    secretKey = "your_secret_key"
) {
    // Optional configuration
    baseUrl = "https://api.fyatu.com/api/v3"
    timeout = 30.seconds
    maxRetries = 3
}
```

## Available Services

| Service             | Description                    |
| ------------------- | ------------------------------ |
| `fyatu.collections` | Accept payments via checkout   |
| `fyatu.refunds`     | Manage refunds                 |
| `fyatu.payouts`     | Send money to recipients       |
| `fyatu.cardholders` | Manage cardholders             |
| `fyatu.cards`       | Issue and manage virtual cards |
| `fyatu.account`     | Access account information     |

## Error Handling

```kotlin theme={null}
import com.fyatu.exceptions.*

try {
    val payout = fyatu.payouts.create(
        CreatePayoutParams(
            amount = 100.0,
            currency = "USD",
            recipientId = "invalid_id"
        )
    )
} catch (e: ValidationException) {
    println("Validation failed: ${e.details}")
} catch (e: AuthenticationException) {
    println("Authentication failed: ${e.message}")
} catch (e: InsufficientBalanceException) {
    println("Insufficient balance: ${e.message}")
} catch (e: FyatuException) {
    println("API error [${e.code}]: ${e.message}")
}
```

## Webhook Verification

```kotlin theme={null}
import com.fyatu.webhooks.Webhook

// Ktor example
post("/webhooks/fyatu") {
    val signature = call.request.headers["X-Fyatu-Signature"] ?: ""
    val payload = call.receiveText()

    val isValid = Webhook.verifySignature(
        payload = payload,
        signature = signature,
        secret = "your_webhook_secret"
    )

    if (!isValid) {
        call.respond(HttpStatusCode.Unauthorized, "Invalid signature")
        return@post
    }

    val event = Webhook.parseEvent(payload)
    println("Received event: ${event.type}")

    call.respond(HttpStatusCode.OK)
}
```

## DSL Builders

```kotlin theme={null}
// Using DSL for cleaner code
val collection = fyatu.collections.create {
    amount = 10.00
    currency = "USD"
    reference = "order_123"
    description = "Payment for Order #123"

    customer {
        email = "customer@example.com"
        name = "Alice Example"
    }

    redirectUrl = "https://yoursite.com/success"
    webhookUrl = "https://yoursite.com/webhooks"
}
```

## Flow Support

```kotlin theme={null}
// List collections as a Flow
fyatu.collections.listAsFlow(limit = 10)
    .collect { collection ->
        println("Collection: ${collection.id} - ${collection.status}")
    }
```

## Resources

* [API Reference](/v3/api-reference/introduction)
* [Webhooks Guide](/v3/concepts/webhooks)
* [GitHub Repository](https://github.com/fyatu/fyatu-kotlin) *(Coming soon)*