Offline payments

United States

The Clover Go SDK requires an active network connection to process transactions and does not support offline payments (Store-and-Forward).

Although offline payments are not supported, you must handle scenarios where the device loses connectivity. To provide a smooth user experience, you must monitor the device's network status to detect connection issues immediately and prevent transaction attempts that are destined to fail. This topic covers offline handling strategies for both iOS and Android platforms.

iOS

The iOS SDK includes a ReachabilityService that monitors the host device's network status. This allows your app to detect connection issues immediately.

Monitor network reachability

Monitor the SDK’s reachability status and notify the merchant if payments cannot be processed. Use ReachabilityService to check the current state or subscribe to status updates.

Check current status

Use currentReachability to get a snapshot of the SDK's connection to Clover servers.

/// Returns the current reachability for the SDK
/// - Returns: ReachabilityState reflecting the reachability of the SDK to Clover servers.
public var currentReachability: ReachabilityService.State {
    return ReachabilityService.currentReachability
}

Subscribe to status updates

The following example demonstrates how to subscribe to the reachability publisher and update a UI label based on the network status.

func setReachability() {
    self.networkLabel.text = "Network Status: \(CloverPaymentSDK.shared.currentReachability.rawValue.capitalized)"

    switch CloverPaymentSDK.shared.currentReachability {
    case .offline:
        TestLogger.shared.log("🔴 Network Status: Offline")
        // Add logic here to alert the merchant (Example: Prevent the transaction)
    case .online:
        TestLogger.shared.log("🟢 Network Status: Online")
    @unknown default:
        TestLogger.shared.log("🟣 Network Status: Unknown")
    }
}

// Subscribe to the publisher on the main run loop
reachability = ReachabilityService.publisher
    .subscribe(on: RunLoop.main)
    .receive(on: RunLoop.main)
    .sink(receiveValue: { value in
        setReachability()
    })
setReachability()

Understand offline behavior

If you initiate a transaction without a viable network connection, the SDK returns a CloverGenericError.offline error.

This error occurs when:

Host device is offline: The iOS mobile device (phone or tablet) has lost its Wi-Fi or cellular connection.
Clover servers are not available: The ping response indicates that the configured payment servers (such as c.clover.com) are not available.

By failing immediately, the SDK prevents the merchant and customer from waiting for network timeouts, which can take several minutes.

Android

Unlike the iOS SDK, the Android SDK does not perform internal connectivity pre-checks. You must implement your own network monitoring using the standard Android ConnectivityManager.

Monitor network reachability

To ensure a smooth user experience, we recommend using a NetworkCallback listener to actively monitor the state of the connection.

Subscribe to status updates (Recommended)

Use ConnectivityManager to register a callback that listens for network capability changes.

context.getSystemService(ConnectivityManager::class.java)?.registerDefaultNetworkCallback(object : ConnectivityManager.NetworkCallback() {
    override fun onCapabilitiesChanged(network: Network, networkCapabilities: NetworkCapabilities) {
        super.onCapabilitiesChanged(network, networkCapabilities)
        if (networkCapabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET) &&
            networkCapabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED)) {
            // Valid network: allow transactions and remove offline banner
        } else {
            // Invalid network: prevent transactions and show offline banner
        }
    }
})

Check current status

If you only need a quick time-of-use check before initiating a transaction, you can check the active network capabilities.

// Conditional check to bail out before calling the SDK's charge endpoint
if (!(context.getSystemService(ConnectivityManager::class.java)?.let { cm ->
        cm.activeNetwork?.let { network ->
            cm.getNetworkCapabilities(network)?.let {
                it.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET) &&
                    it.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED)
            }
        }
    } ?: false)) {
   // Do not proceed with transaction, and alert user
}

Understand offline behavior

If you initiate a transaction without a viable network connection, the SDK returns a CloverReaderError with the code READER_NOT_CONNECTED.

Note: While the error code READER_NOT_CONNECTED usually implies a Bluetooth connection issue with the card reader, in this context, it indicates that the transaction failed because the device could not reach Clover servers.

Inspect the OnPaymentError state to catch this specific error and display a helpful message to the merchant.

goSdk.chargeCardReader(
    request
).collectLatest { cardReaderState ->
    when (cardReaderState) {
        is ChargeCardReaderState.OnPaymentComplete -> {}
        is ChargeCardReaderState.OnPaymentError -> {
            val error = cardReaderState.error
            when (error) {
               // Check for specific reader errors
               is CloverReaderError -> {
                   when (error.code) {
                        // Handle the offline scenario
                        ReaderErrorCode.READER_NOT_CONNECTED -> {
                            // Display message: "Network not available. Please check your connection."
                        }
                       else -> {}
                   }
               }
           }
        }
        is ChargeCardReaderState.OnReaderPaymentProgress -> {}
    }
}

Updated 7 days ago