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

# Android Native SDK

> Integrate the Sudo Cloud Card Android Native SDK for provisioning, management, and payment operations.

## Overview

The Cloud Card Android SDK provides APIs for:

* Card provisioning and registration
* Card management
* QR-based transactions
* Token usage summaries
* NFC and payment-app status checks

## Installation

Add the SDK repository and dependency to your Android app module setup.

```groovy theme={null}
repositories {
    google()
    mavenCentral()
    maven {
        url = uri("https://sdk.sudo.africa/repository/maven-releases/")
        credentials {
            username = "USERNAME"
            password = "PASSWORD"
        }
    }
}

dependencies {
    implementation("africa.sudo:cloudcard:$latest_version")
}
```

## Android Manifest

Add the following service inside the `<application>` tag of your `AndroidManifest.xml`.

```xml theme={null}
<service
    android:name="com.sudo.cloud_card.HCEService"
    android:enabled="true"
    android:exported="true"
    android:enableOnBackInvokedCallback="true"
    android:permission="android.permission.BIND_NFC_SERVICE">
    <intent-filter>
        <action android:name="android.nfc.cardemulation.action.HOST_APDU_SERVICE" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</service>
```

## Initialization

Import the SDK and initialize it before using any Cloud Card API.

```kotlin theme={null}
import com.sudo.cloud_card.*

val cloudCard = CloudCardAndroid.getInstance(context)
```

## API Reference

### `isNfcEnabled()`

Returns `Boolean`.

Use this to determine whether NFC is available and enabled on the device.

### `isDeviceSupported()`

Returns `Boolean`.

Use this to verify whether the current device meets the required security and compatibility checks.

### `isDefaultPaymentApp()`

Returns `Boolean`.

Use this to determine whether your application is currently set as the default payment app.

### `registerCard(data: RegistrationData)`

```kotlin theme={null}
suspend fun registerCard(data: RegistrationData): CCResult
```

Registers and provisions a card using institution and device information.

### `manualKeyReplenishment()`

```kotlin theme={null}
suspend fun manualKeyReplenishment(): CCResult
```

Refreshes secure keys for offline transactions on the current card.

### `freezeUnfreezeCard(period: Duration?, cardId: String)`

```kotlin theme={null}
fun freezeUnfreezeCard(period: Duration?, cardId: String): CCResult
```

Updates the current card state to make it temporarily active or inactive.

* `period`: optional time-based state input
* `cardId`: required card identifier

Returns a `CCResult` whose `data` field is a `Boolean` representing the latest card state.

### `getCards()`

```kotlin theme={null}
fun getCards(): List<CardData>
```

Returns all cards available in the wallet.

### `getEmvQr(cardId: String, amount: String? = "000000000000")`

```kotlin theme={null}
fun getEmvQr(cardId: String, amount: String? = "000000000000"): CCResult
```

Generates an EMV QR code for QR-based contactless payment.

* `amount`: optional 12-character amount in the lowest denomination. For example, NGN 1 should be passed as `"000000000100"`.
* `cardId`: required card identifier

Returns a `CCResult` whose `data` field contains a `Bitmap`.

### `tokenSummary()`

```kotlin theme={null}
fun tokenSummary(): TokensUsageSummary
```

Returns card usage summary data across the card lifecycle.

### `setRequireAuth(auth: Boolean)`

```kotlin theme={null}
fun setRequireAuth(auth: Boolean)
```

Enables or disables biometric authentication for transactions.

## Objects

### `RegistrationData`

Required fields:

* `walletId`: institution ID
* `paymentAppInstanceId`: unique device ID
* `accountId`: card unique identifier
* `jwtToken`: auth token from your server

Optional fields:

* `secret`: secret passed to the user
* `cardNumber`: card number for an already-issued card
* `expiryDate`: expiry for an already-issued card
* `cardHolderName`: cardholder name for an already-issued card

### `CCResult`

Fields:

* `status`: request status. Possible values are `SUCCESS`, `FAILED`, `PENDING`
* `message`: accompanying message
* `data`: present on successful responses

### `CardData`

Fields:

* `isActive`: current card state. `false` means the card is frozen
* `id`: unique card ID
* `maskedPan`: masked PAN
* `cardHolder`: cardholder name
* `exp`: card expiry data

## Customization

### APDU Service Banner

To override the default Host APDU Service banner used by the library, add a drawable resource with the same name in your application:

* Create `cloud_card_banner` in your app's `res/drawable` directory.