Android Native SDK - Introduction

Package

Artifact: africa.sudo:cloudcard
Version: 0.2.0
Entry point: CloudCardAndroid

Overview

The Cloud Card Android SDK provides APIs for:

Card provisioning and registration
Card lifecycle management (freeze, unfreeze, delete, wipe)
Multi-card support with active and default card selection
QR-based transactions
Token usage summaries and key replenishment
NFC status checks, chip-position indicators, and payment-app settings
Locally cached transaction history

Installation

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

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

dependencies {
    implementation("africa.sudo:cloudcard:0.2.0")
}

Keep your repository credentials in gradle.properties or environment variables rather than committing them to source control.

Android Manifest

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

<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

CloudCardAndroid is a singleton. Call getInstance() once during app startup with a Context; later calls can omit it.

import com.sudo.cloud_card.*

val cloudCard = CloudCardAndroid.getInstance(
    context = applicationContext,
    isSandBox = true,
    supportMultipleCards = false,
    url = null
)

Parameter	Type	Default	Description
`context`	`Context?`	`null`	Required on the first call. Pass the application context.
`isSandBox`	`Boolean`	`true`	Selects the sandbox or production environment.
`supportMultipleCards`	`Boolean`	`false`	Allows more than one card in the wallet.
`url`	`String?`	`null`	Optional base URL override.

The first call to getInstance() must provide a Context. Calling it without one before the SDK is initialized throws IllegalStateException.

getInstance() calls init() internally, so you do not need to call init() yourself:

fun init(
    context: Context,
    isSandBox: Boolean,
    useNotifications: Boolean,
    supportMultipleCards: Boolean = false,
    url: String?
)

Device and NFC Checks

`isNfcEnabled()`

fun isNfcEnabled(): Boolean?

Checks NFC availability and state. This method is nullable and has three outcomes:

true: NFC is available and enabled
false: NFC is available but not enabled
null: NFC is not available on the device

`isDeviceSupported()`

fun isDeviceSupported(): Boolean

Returns true if the device meets the required security and compatibility checks.

`isDefaultPaymentApp()`

fun isDefaultPaymentApp(): Boolean

Returns true if your application is currently set as the default contactless payment app.

`launchDefaultPaymentAppSettings(activity: Activity)`

fun launchDefaultPaymentAppSettings(activity: Activity): Boolean

Opens the device settings page where the user can set your app as the default payment app. Returns true if the settings page was launched.

if (cloudCard.isNfcEnabled() == true && !cloudCard.isDefaultPaymentApp()) {
    cloudCard.launchDefaultPaymentAppSettings(this)
}

NFC Chip Position

These helpers show users where to tap on the device for contactless payments.

`showNfcChipPosition(activity, duration, colorHex)`

fun showNfcChipPosition(
    activity: Activity,
    duration: Long? = 3000L,
    colorHex: String? = null
): Boolean

Displays an overlay indicator over the NFC chip location.

activity: activity used to display the overlay
duration: display time in milliseconds. Pass null to show it indefinitely
colorHex: optional indicator color, for example "#FF5722"

Returns true if the indicator was displayed.

`hideNfcChipPosition()`

fun hideNfcChipPosition(): Boolean

Dismisses the indicator. Returns false if no indicator was showing.

`getNfcChipPosition()`

fun getNfcChipPosition(): NfcChipPosition?

Returns the chip coordinates and confidence level, or null if the position cannot be determined.

cloudCard.showNfcChipPosition(activity = this, duration = 5000L, colorHex = "#AF5298")

val position = cloudCard.getNfcChipPosition()
Log.d("CloudCard", "${position?.x} ${position?.y} ${position?.confidence}")

cloudCard.hideNfcChipPosition()

Card Registration

`registerCard(data: RegistrationData)`

suspend fun registerCard(data: RegistrationData): CCResult

Registers and provisions a card using institution and device information. This is a suspend function, so call it from a coroutine.

lifecycleScope.launch {
    val result = cloudCard.registerCard(
        RegistrationData(
            walletId = walletId,
            paymentAppInstanceId = paymentAppInstanceId,
            accountId = accountId,
            jwtToken = jwtToken
        )
    )

    if (result.status == Status.SUCCESS) {
        // card provisioned
    }
}

Card Management

`getCards()`

fun getCards(): List<CardData>

Returns all cards available in the wallet.

`setActiveCard(id: String)`

fun setActiveCard(id: String): Boolean

Sets the card matching the given tokenUniqueRef as the active card used for the next payment.

`setDefaultCard(id: String)`

fun setDefaultCard(id: String): Boolean

Sets the card matching the given tokenUniqueRef as the default card used for payments.

setActiveCard and setDefaultCard are relevant when the SDK is initialized with supportMultipleCards = true.

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

fun freezeUnfreezeCard(period: Duration?, cardId: String): CCResult

Toggles the card between active and frozen states.

period: optional duration for which the card should stay frozen
cardId: required card identifier

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

`deleteCard(cardId: String)`

fun deleteCard(cardId: String): CCResult

Permanently deletes a single card from the wallet.

`emptyWallet()`

fun emptyWallet(): CCResult

Deletes all card and transaction data in the wallet.

`wipeWallet()`

fun wipeWallet(): CCResult

Wipes all wallet data and preferences stored by the SDK, including card information, tokens, and wallet configuration.

emptyWallet() and wipeWallet() are destructive and cannot be undone. Cards must be provisioned again afterwards.

Tokens and Security

`manualKeyReplenishment()`

suspend fun manualKeyReplenishment(): CCResult

Refreshes the secure keys used for offline transactions on the current card.

`tokenSummary()`

fun tokenSummary(): TokensUsageSummary

Returns token usage statistics across the card lifecycle.

`getTokenThreshold()`

fun getTokenThreshold(): Int

Returns the token count at which replenishment should be triggered. Compare it against the values in tokenSummary() to decide when to call manualKeyReplenishment().

`setRequireAuth(auth: Boolean)`

fun setRequireAuth(auth: Boolean)

Set to true to enforce foreground card access and a biometric check before transactions.

QR and Transactions

`getEmvQr(...)`

suspend fun getEmvQr(
    cardId: String,
    amount: String? = null,
    foregroundColorHex: String? = null,
    backgroundColorHex: String? = null,
    margin: Int? = 4
): CCResult

Generates an EMV QR code for a customer-presented QR payment.

cardId: required card identifier
amount: transaction amount in the lowest denomination, as a 12-character zero-padded string. For example, NGN 1 is "000000000100". Leave it empty or null to generate a dynamic-amount QR
foregroundColorHex: QR code color. Defaults to black
backgroundColorHex: QR background color. Defaults to transparent
margin: margin between the QR code and its background. Defaults to 4

Returns a CCResult whose data field contains a Bitmap.

lifecycleScope.launch {
    val result = cloudCard.getEmvQr(
        cardId = cardId,
        amount = "000000000200",
        foregroundColorHex = "#000000",
        backgroundColorHex = "#FFFFFF"
    )

    if (result.status == Status.SUCCESS) {
        qrImageView.setImageBitmap(result.data as Bitmap)
    }
}

`getSavedTransactions()`

fun getSavedTransactions(): List<SavedTransaction>

Returns recent completed transactions cached on the device.

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

`NfcChipPosition`

Fields:

x: horizontal coordinate of the NFC chip
y: vertical coordinate of the NFC chip
confidence: confidence level of the detected position

`SavedTransaction`

Fields:

amount: transaction amount
currency: transaction currency
timestamp: time the transaction completed
type: transaction type

Customization

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.

​Package

​Overview

​Installation

​Android Manifest

​Initialization

​Device and NFC Checks

​isNfcEnabled()

​isDeviceSupported()

​isDefaultPaymentApp()

​launchDefaultPaymentAppSettings(activity: Activity)

​NFC Chip Position

​showNfcChipPosition(activity, duration, colorHex)

​hideNfcChipPosition()

​getNfcChipPosition()

​Card Registration

​registerCard(data: RegistrationData)

​Card Management

​getCards()

​setActiveCard(id: String)

​setDefaultCard(id: String)

​freezeUnfreezeCard(period: Duration?, cardId: String)

​deleteCard(cardId: String)

​emptyWallet()

​wipeWallet()

​Tokens and Security

​manualKeyReplenishment()

​tokenSummary()

​getTokenThreshold()

​setRequireAuth(auth: Boolean)

​QR and Transactions

​getEmvQr(...)

​getSavedTransactions()

​Objects

​RegistrationData

​CCResult

​CardData

​NfcChipPosition

​SavedTransaction

​Customization

​APDU Service Banner

Package

Overview

Installation

Android Manifest

Initialization

Device and NFC Checks

`isNfcEnabled()`

`isDeviceSupported()`

`isDefaultPaymentApp()`

`launchDefaultPaymentAppSettings(activity: Activity)`

NFC Chip Position

`showNfcChipPosition(activity, duration, colorHex)`

`hideNfcChipPosition()`

`getNfcChipPosition()`

Card Registration

`registerCard(data: RegistrationData)`

Card Management

`getCards()`

`setActiveCard(id: String)`

`setDefaultCard(id: String)`

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

`deleteCard(cardId: String)`

`emptyWallet()`

`wipeWallet()`

Tokens and Security

`manualKeyReplenishment()`

`tokenSummary()`

`getTokenThreshold()`

`setRequireAuth(auth: Boolean)`

QR and Transactions

`getEmvQr(...)`

`getSavedTransactions()`

Objects

`RegistrationData`

`CCResult`

`CardData`

`NfcChipPosition`

`SavedTransaction`

Customization

APDU Service Banner