CloudCard Flutter #

A Flutter plugin for Sudo's CloudCard digital wallet API, enabling seamless digital card operations and contactless payments.

Overview #

CloudCard Flutter 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 Flutter applications.

Installation #

1. Add the package to your pubspec.yaml #

dependencies:
  cloudcard_flutter: <latest_version>

2. Configure Android Access #

Ensure your Android project has the required access to access sdk:

For older Gradle (pre-7):
In 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+ (Flutter 3.7+):
In 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>

Getting Started #

Initialize the SDK #

Before using any features, initialize the SDK in your app's startup:

import 'package:cloudcard_flutter/cloudcard_flutter.dart';

Future<void> initializeCloudCard() async {
  // Use true for sandbox, false for production environment
  await cloudCardFlutter.init(isSandBox: true,
      onCardScanned: (CloudCardEvent event){
       //Handle navigation to card page
      },
    onScanComplete: (CloudCardEvent scannedResult){
      // Scan complete - Show UI update
    },
  );
}

Sandbox vs Production #

• Sandbox Mode: Use for development and testing (set isSandBox: true)
• Production Mode: Use for live applications (set isSandBox: false)

Core Features #

Register a Card #

Card registration data is retrieved after completing onboarding on the Sudo Africa platform.

final registrationData = RegistrationData(
  walletId: 'wallet-id-from-sudo (institution id)',
  paymentAppInstanceId: 'device Id eg Firebase ID',
  accountId: 'account-id or cardId',
  secret: 'secret-key',
  jwtToken: 'jwt-token-from-sudo',

  // Optional fields
  cardNumber: '4111111111111111',
  expiryDate: '12/25',
  cardHolderName: 'John Doe',
);


final result = await CloudCardFlutter().registerCard(registrationData);
if (result.status == Status.SUCCESS) {
  // Card successfully registered
}

Get Cards #

Retrieve all cards provisioned on the device (Limited to 1 card per device):

final cards = await CloudCardFlutter().getCards();
for (var card in cards) {
  print('Card ID: ${card.id}, Last 4: ${card.last4}, Network: ${card.network}');
}

Generate EMV QR Code #

Create a one-time use customer-presented QR code that can be used to make payments on terminals as a physical card would:

final result = await CloudCardFlutter().getEmvQr(
  cardId: 'card-id-here',
  amount: '000000000100', // Optional, omit for dynamic amount
  foregroundColorHex: '#000000', // Optional, defaults to #000000 (Black)
  backgroundColorHex: '#FFFFFF', // Optional, defaults to #FFFFFF (White)
);

if (result.success && result.data != null) {
  final qrCodeData = result.data!['qrCode'];
  // Display QR code to user for payment
}

Get Saved Transactions #

You can retrieve up to 5 recently completed transactions from the CloudCard local cache. This can be useful for showing a transaction history page in your app. Returns List

final transactions = await cloudCardFlutter().getSavedTransactions();
for (var transaction in transactions) {
}

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 flutter_tappa.

Building for iOS #

• Create a .env file and add SUDO credentials SUDO_USER=.... SUDO_PASS=....

• Run the following command in terminal to 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 pod install

Requirements #

• Flutter 2.5.0 or higher
• iOS 13.0+ / Android API level 21+
• NFC-enabled device for NFC contactless payments (Not required for QR payments)

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Support #

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