Skip to main content

​
Overview

The Cloud Card iOS SDK provides APIs for:
  • Card provisioning and registration
  • Retrieving locally stored cards
  • Generating EMV QR codes
  • Reading token inventory and usage summaries
  • Accessing locally cached transactions
The native entry point exposed by the SDK is CloudCardWrapper.

​
Installation

CloudCard is distributed as an XCFramework through Sudo Africa’s protected artifact repository.

​
Requirements

  • iOS 13.0+
  • Xcode 15+
  • CocoaPods
  • Physical iPhone recommended for payment testing

​
SDK Repository Authentication

You need repository credentials from Sudo Africa before installation. 
export SUDO_USER="your_sdk_username"
export SUDO_PASSWORD="your_sdk_password"
Or load them from .env: 
export $(grep -v '^#' .env | xargs)
Use a temporary .netrc file when installing: 
TMPHOME=$(mktemp -d)
trap 'rm -rf "$TMPHOME"' EXIT
export HOME="$TMPHOME"
cat > "$HOME/.netrc" <<EOF_NETRC
machine sdk.sudo.africa
login $SUDO_USER
password $SUDO_PASSWORD
EOF_NETRC
chmod 600 "$HOME/.netrc"
cd ios && pod install
Do not commit .env, .netrc, or SDK credentials to source control.

​
Environments

The SDK supports two environments:
  • true for sandbox
  • false for production
Your SDK environment must match the backend environment issuing the provisioning payload.

​
Initialization

Initialize the SDK once during app startup before calling any other Cloud Card API. 
import CloudCard

CloudCardWrapper.initializeSDK(true)
Use true for sandbox and false for production.

​
Register a Card

Provisioning data must come from your backend after the user is authenticated. The client app should not generate provisioning credentials locally. Typical payload values include:
  • walletId
  • accountId
  • paymentAppInstanceId
  • secret
  • jwtToken
Example: 
import CloudCard

let data = WalletRequestIOS()
data.accountId = accountId
data.tokenUniqueReference = accountId
data.paymentAppInstanceId = paymentAppInstanceId
data.secret = secret
data.keyNumber = 0
data.walletId = walletId
data.jwtToken = jwt

let result = await CloudCardWrapper.registerCard(data)
Successful registration stores the provisioned card locally on the device.

​
Retrieve Cards

if let fetched = CloudCardWrapper.getCards() as? [Any] {
    // Map results to your UI model
}
Filter active cards before displaying them to users.

​
Token Summary

Use token summary to monitor the current token balance and refresh state after provisioning or payment activity. 
if let summaryResult = CloudCardWrapper.getTokenSummary() as? [String: Any] {
    let totalTokens = summaryResult["totalTokens"] as? Int
    let tokensBalance = summaryResult["tokensBalance"] as? Int
}

​
Retrieve Saved Transactions

let raw = CloudCardWrapper.getSavedTransactions()
Saved transaction records typically include:
  • ATC
  • Amount
  • Timestamp

​
Generate EMV QR

if let result = CloudCardWrapper.getEmvQr(
    amount,
    foregroundColorHex: "#000000",
    backgroundColorHex: "#FFFFFF"
),
let status = result["status"] as? String,
status == "SUCCESS",
let qrImageResult = result["data"] as? UIImage {
    // Render QR image
}
The QR API supports dynamic amounts and custom foreground or background colors.

​
Common Issues

​
Authentication Failure During Installation

Check:
  • SUDO_USER is set
  • SUDO_PASSWORD is set
  • Credentials are valid
  • .netrc is configured correctly

​
Works on Device but Fails on Simulator

If the XCFramework only includes ios-arm64, simulator builds will fail. Use a physical iPhone or request a simulator-compatible XCFramework.

​
Registration Succeeds but No Cards Are Returned

Verify:
  • SDK environment matches backend environment
  • walletId and accountId are correct
  • registration returned success
  • stored cards are active

​
QR Generation Fails

Check:
  • there is an active card on the device
  • token inventory is not depleted
  • the amount format is valid
  • SDK environment matches the provisioning environment

​
Best Practices

  • Initialize the SDK once during app startup
  • Use a stable device identifier for paymentAppInstanceId
  • Fetch provisioning data from a secure backend endpoint
  • Avoid logging secrets or JWTs in production
  • Refresh cards and token summary after provisioning or payment events