Skip to main content

​
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. 
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. 
<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>
    <meta-data
        android:name="android.nfc.cardemulation.host_apdu_service"
        android:resource="@xml/apduservice" />
</service>

​
Initialization

Import the SDK and initialize it before using any Cloud Card API. 
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)

suspend fun registerCard(data: RegistrationData): CCResult
Registers and provisions a card using institution and device information.

​
manualKeyReplenishment()

suspend fun manualKeyReplenishment(): CCResult
Refreshes secure keys for offline transactions on the current card.

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

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()

fun getCards(): List<CardData>
Returns all cards available in the wallet.

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

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()

fun tokenSummary(): TokensUsageSummary
Returns card usage summary data across the card lifecycle.

​
setRequireAuth(auth: Boolean)

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.