react-native-cloudcard

A React Native SDK for Sudo Africa CloudCard, enabling digital card provisioning, lifecycle management, NFC contactless payments (HCE), EMV QR generation, token management, and saved transaction retrieval.

This library wraps the native CloudCard Android & iOS SDKs and exposes a unified JavaScript API.

Features

• Digital card provisioning
• Card lifecycle management (freeze, delete)
• NFC contactless (HCE) support
• EMV QR generation
• Token usage & replenishment
• Saved transaction history
• Default payment app utilities
• NFC chip position UX helpers
• Flutter-API parity helpers

Installation

npm install react-native-cloudcard
# OR
yarn add react-native-cloudcard

Android Setup

1. Configure Maven repository

RN 0.71+ / Gradle 7+

Edit android/settings.gradle

dependencyResolutionManagement {
  repositories {
    google()
    mavenCentral()

    maven {
      url = uri("https://sdk.sudo.africa/repository/maven-releases/")
      credentials {
        username = providers.gradleProperty("maven.repo.username").orNull ?: System.getenv("NEXUS_USER")
        password = providers.gradleProperty("maven.repo.password").orNull ?: System.getenv("NEXUS_PASS")
      }
    }
  }
}

2. Provide credentials

Option A — android/gradle.properties

maven.repo.username=YOUR_USERNAME
maven.repo.password=YOUR_PASSWORD

Option B — environment variables

export NEXUS_USER=YOUR_USERNAME
export NEXUS_PASS=YOUR_PASSWORD

3. Register HCE service & receiver

Add inside <application> in AndroidManifest.xml

<service
  android:name="com.sudo.cloud_card.HCEService"
  android:enabled="true"
  android:exported="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>

<receiver
  android:name="africa.sudo.cloudcard.reactnative.HceEventReceiver"
  android:enabled="true"
  android:exported="true">
  <intent-filter>
    <action android:name="${applicationId}.CLOUDCARD_EVENT" />
  </intent-filter>
</receiver>

iOS Setup

1. Create .env

SUDO_USER=...
SUDO_PASS=...

2. Temporary .netrc

export $(grep -v '^#' .env | xargs)

TMPHOME=$(mktemp -d)
trap 'rm -rf "$TMPHOME"' EXIT
export HOME="$TMPHOME"

cat > "$HOME/.netrc" <<EOF
machine sdk.sudo.africa
login $SUDO_USER
password $SUDO_PASS
EOF
chmod 600 "$HOME/.netrc"

3. Install pods

cd ios && pod install

Usage

import CloudCard from 'react-native-cloudcard';

Initialization

await CloudCard.init({
  isSandBox: true,
  url: 'optional-endpoint',
  onCardScanned: (event) => {},
  onScanComplete: (event) => {},
});

CCResult shape

type CCResult<T = any> = {
  status: 'SUCCESS' | 'ERROR' | 'PENDING';
  message: string;
  data?: T;
};

Card Management

Register Card

await CloudCard.registerCard({
  walletId: 'wallet-id',
  paymentAppInstanceId: 'device-id',
  accountId: 'account-id',
  secret: 'secret',
  jwtToken: 'jwt-token',
});

Get Cards

const res = await CloudCard.getCards();
const cards = res.data;

Get First Card (Flutter parity)

await CloudCard.getCard();

Delete Card

await CloudCard.deleteCard('card-id');

Freeze / Unfreeze

await CloudCard.freezeUnfreezeCard({
  cardId: 'card-id',
  isFreeze: true,
  periodInDays: 7,
});

NFC & Device Utilities

await CloudCard.isDeviceSupported();
await CloudCard.isNfcEnabled();
await CloudCard.isDefaultPaymentApp();
await CloudCard.launchDefaultPaymentAppSettings();

Flutter parity:

CloudCard.checkDeviceSupport();
CloudCard.openAppSettings();
CloudCard.checkDefaultApp();

Token & Security

await CloudCard.manualKeyReplenishment();
await CloudCard.replenishKeys(); // alias
await CloudCard.tokenSummary();
await CloudCard.setRequireAuth(true);
await CloudCard.getTokenThreshold();

EMV QR

await CloudCard.getEmvQr({
  cardId: 'card-id',
  amount: '000000000100',
  foregroundColorHex: '#000000',
  backgroundColorHex: '#FFFFFF',
});

Saved Transactions

const res = await CloudCard.getSavedTransactions();
const txns = res.data;

Wallet Reset

await CloudCard.wipeWallet();

NFC Chip Position Helpers

await CloudCard.showNfcChipPosition({
  duration: 3000,
  colorHex: '#FF5722',
});

await CloudCard.hideNfcChipPosition();

const pos = await CloudCard.getNfcChipPosition();

Events

CloudCard.addListener('CloudCard:log', console.log);
CloudCard.removeAllListeners('CloudCard:log');
CloudCard.removeHceListeners();

Requirements

• React Native 0.68+
• Android API 24+
• iOS 13+
• NFC-enabled device for tap-to-pay

Support

[email protected] https://sudo.africa