react-native-cloudcard (CloudCard React Native)

A React Native package for Sudo’s CloudCard digital wallet API, enabling seamless digital card operations and contactless payments.

Overview

CloudCard React Native provides an interface for managing digital cards, including provisioning, management, and transactions. It wraps Sudo Africa’s CloudCard API to offer a comprehensive solution for card lifecycle management, tokenization, and payment operations in your React Native applications.

Installation

npm install react-native-cloudcard

OR

yarn add react-native-cloudcard

Configure Android Access

Ensure your Android project has access to the SDK:

// For older Gradle (pre-7):
// android/build.gradle
allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://sdk.sudo.africa/repository/maven-releases/")
            credentials {
                username = project.findProperty("maven.repo.username") ?: ""
                password = project.findProperty("maven.repo.password") ?: ""
            }
        }
    }
}

// For Gradle 7+ (React Native 0.71+):
// android/settings.gradle
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://sdk.sudo.africa/repository/maven-releases/")
            credentials {
                username = project.findProperty("maven.repo.username") ?: ""
                password = project.findProperty("maven.repo.password") ?: ""
            }
        }
    }
}

Replace YOUR_USERNAME and YOUR_PASSWORD with the credentials provided by Sudo Africa.

Register service and receiver in your android manifest

 <service
            android:name="com.sudo.cloud_card.HCEService"
            android:enableOnBackInvokedCallback="true"
            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_flutter.HceEventReceiver"
            android:enabled="true"
            android:exported="true">
            <intent-filter>
                <action android:name="${packageName}.CLOUDCARD_EVENT" />
            </intent-filter>
        </receiver>
        ```


## Configure iOS Access
Create a .env file and add SUDO credentials

```sh
SUDO_USER=....
SUDO_PASS=....

Authenticate with ephemeral .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"

Install pods

cd ios && pod install

Usage

Initialize

import CloudCard from 'react-native-cloudcard';

async function initializeCloudCard() {
  // Use true for sandbox, false for production
  await CloudCard.init({
    isSandbox: true,
    onCardScanned: (event: CloudCardEvent) => {
      // Handle navigation to card page
    },
    onScanComplete: (event: CloudCardEvent) => {
      // Scan complete - Show UI update
    },
  });
}

Sandbox vs Production

Sandbox Mode: Use for development and testing (isSandbox: true) Production Mode: Use for live applications (isSandbox: false)

Register Card

const registrationData = {
  walletId: 'wallet-id-from-sudo',
  paymentAppInstanceId: 'device-id-eg-firebase-id',
  accountId: 'account-id-or-card-id',
  secret: 'secret-key',
  jwtToken: 'jwt-token-from-sudo',
};

const result = await CloudCard.registerCard(registrationData);
if (result.status === 'SUCCESS') {
  // Card successfully registered
}

Get Cards

const cards = await CloudCard.getCards();
cards.forEach(card => {
  console.log(`Card ID: ${card.id}, Last 4: ${card.last4}, Network: ${card.network}`);
});

Generate EMV QR Code

const result = await CloudCard.getEmvQr({
  cardId: 'card-id-here',
  amount: '000000000100', // Optional
  foregroundColorHex: '#000000',
  backgroundColorHex: '#FFFFFF',
});

if (result.success && result.data) {
  const qrCodeData = result.data.qrCode;
  // Display QR code to user
}

Get Saved Transactions

Retrieve up to 5 recently completed transactions:

const transactions = await CloudCard.getSavedTransactions();
transactions.forEach(txn => {
  console.log(`ATC: ${txn.atc}, Amount: ${txn.amount}, Time: ${new Date(txn.timestamp).toLocaleString()}`);
});

Additional Features

NFC Operations: Check NFC availability and set up payment defaults Card Management: Freeze/unfreeze cards, delete cards Security: Manage authentication requirements and key replenishment Token Management: Get token usage summaries and thresholds

Transaction Processing

For transaction processing functionality, please use the companion library react-native-tappa.

Requirements

React Native 0.68+ iOS 13.0+ / Android API level 21+ NFC-enabled device for NFC contactless payments (Not required for QR payments)

Support

For support, please contact [email protected] or visit sudo.africa.

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library