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

# Android

> Install and use Novac Android SDK with minimal setup config.

## Overview

Novac Android SDKs enable Android developers to extend Novac's capabilities when building mobile platforms with minimal setup.

The Novac Android SDK provides a seamless checkout experience with a customizable UI, native Jetpack Compose and Views support, and robust error handling—all with a simple setup.

***

### Prerequisites

<Accordion title="See details" defaultOpen={true}>
  Before you begin, ensure that you’ve completed the following steps:

  * [Obtain your API keys](/docs/getting-started/obtain-api-keys): required for making authenticated API calls.
  * Android project with Gradle build system
  * Minimum SDK version compatible with Jetpack Compose or AppCompat
</Accordion>

### Installation

<Steps>
  <Step title="Step 1 - Add the JitPack Repository">
    In your **project-level** `build.gradle`, add the JitPack repository:

    ```groovy theme={null}
    allprojects {
        repositories {
            maven { url 'https://jitpack.io' }
        }
    }
    ```
  </Step>

  <Step title="Step 2 - Add the SDK Dependency">
    In your app-level `build.gradle`, add the following dependency.

    ```groovy theme={null}
      dependencies {
          implementation 'com.github.novacpayment:novac-payment-android-sdk:v0.2.6'
      }
    ```
  </Step>
</Steps>

***

## Initialize the SDK

Initialize the SDK in your `Application` class or main `Activity`. You will need your `merchantId` and `apiKey` from your Novac dashboard, and you must specify the activities that will handle payment success and failure outcomes.

```kotlin theme={null}
import com.novacpaymen.paywithnovac_android_skd.NovacCheckout
import com.novacpaymen.paywithnovac_android_skd.CheckoutConfig

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

        NovacCheckout.initialize(
            CheckoutConfig(
                merchantId = "your-merchant-id",
                baseUrl = "https://api.novacpayment.com",
                apiKey = "your-api-key",
                enableLogging = false,
                successActivityClass = SuccessActivity::class.java,
                failureActivityClass = FailureActivity::class.java
            )
        )
    }
}
```

### Checkout Config Parameters

| Parameter              | Type      | Required | Description                              |
| ---------------------- | --------- | -------- | ---------------------------------------- |
| `merchantId`           | `String`  | `true`   | Your merchant ID from Novac              |
| `baseUrl`              | `String`  | `true`   | API base URL                             |
| `apiKey`               | `String`  | `true`   | Your API key from Novac                  |
| `enableLogging`        | `Boolean` | `false`  | Enable debug logging                     |
| `successActivityClass` | `Class`   | `true`   | Activity to launch on successful payment |
| `failureActivityClass` | `Class`   | `true`   | Activity to launch on failed payment     |

***

### Create Result Activities

You need two activities to handle the payment outcomes: one for success and one for failure. The SDK passes transaction details to each via the intent.

### `SuccessActivity.kt`

```kotlin theme={null}
class SuccessActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_success)

        val transactionReference = intent.getStringExtra("transaction_reference")
        val amount = intent.getDoubleExtra("amount", 0.0)
        val currency = intent.getStringExtra("currency")
        val paymentStatus = intent.getStringExtra("payment_status")

        // Update your UI, confirm the order, etc.
    }
}
```

### `FailureActivity.kt`

```kotlin theme={null}
class FailureActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_failure)

        val transactionReference = intent.getStringExtra("transaction_reference")
        val amount = intent.getDoubleExtra("amount", 0.0)
        val currency = intent.getStringExtra("currency")
        val errorMessage = intent.getStringExtra("error_message")
        val errorCode = intent.getStringExtra("error_code")

        // Show error message, offer retry option, etc.
    }
}
```

***

### Launch the Checkout Flow

Once the SDK is initialized, launching a payment is a single method call:

```kotlin theme={null}
val sdk = NovacCheckout.getInstance()

sdk.launchCheckoutFlow(
    context = this,
    transactionReference = UUID.randomUUID().toString(),
    amount = 120.0,
    currency = "NGN",
    customerEmail = "customer@example.com",
    customerFirstName = "John",
    customerLastName = "Doe",
    customerPhone = "1234567890"
)
```

***

## Advanced Usage

### Customizing the Checkout UI

You can personalize the checkout modal with your brand logo, a payment description, and a custom title:

```kotlin theme={null}
val customizationData = CheckoutCustomizationData(
    logoUrl = "https://your-logo-url.com/logo.png",
    paymentDescription = "Payment for Order #123",
    checkoutModalTitle = "Complete Your Payment"
)

sdk.launchCheckoutFlow(
    context = this,
    transactionReference = UUID.randomUUID().toString(),
    amount = 120.0,
    currency = "NGN",
    customerEmail = "customer@example.com",
    customerFirstName = "John",
    customerLastName = "Doe",
    customerPhone = "1234567890",
    customizationData = customizationData
)
```

### Manual Checkout Initiation

For greater control over the checkout flow — for example, to retrieve the payment URL and handle redirection yourself — use `initiateCheckout` directly within a coroutine:

```kotlin theme={null}
val sdk = NovacCheckout.getInstance()

val customerData = CheckoutCustomerData(
    email = "customer@example.com",
    firstName = "John",
    lastName = "Doe",
    phoneNumber = "1234567890"
)

val customizationData = CheckoutCustomizationData(
    logoUrl = "https://your-logo-url.com/logo.png",
    paymentDescription = "Payment for Order #123",
    checkoutModalTitle = "Complete Your Payment"
)

coroutineScope.launch {
    when (val result = sdk.initiateCheckout(
        transactionReference = UUID.randomUUID().toString(),
        amount = 120.0,
        currency = "NGN",
        checkoutCustomerData = customerData,
        checkoutCustomizationData = customizationData
    )) {
        is Result.Success -> {
            val paymentUrl = result.value.data?.paymentRedirectUrl
            // Redirect the user to the payment URL
        }
        is Result.Failure -> {
            Log.e("Checkout", "Payment initiation failed", result.exception)
        }
    }
}
```

Keep the following in mind when testing:

* Always use a unique `reference` value for each transaction, duplicate references will be rejected.
* Start with small test amounts (₦100) to validate your integration before going live.
* Check your sandbox dashboard to confirm transaction results and inspect any errors.