Test offline payments
Simulate network failures to test your offline payments integration without going physically offline.
The Terminal SDK includes a simulatedOfflineModeConfiguration property that lets you simulate network failures in a sandbox without physically disconnecting from the internet. Use this to verify your offline payments integration handles connectivity issues correctly.
Common mistake
You can’t use simulatedOfflineModeConfiguration in live mode. Setting a non-default configuration while connected to a live mode reader throws a TerminalException error.
Before you begin
Make sure you:
- Have a working offline payments integration .
- Are operating in a sandbox with a reader.
Note
Tap to Pay on iPhone offline mode requires a physical iPhone. The simulated Tap to Pay reader can simulate card taps for online testing, but it doesn’t support offline mode. simulatedOfflineModeConfiguration also doesn’t simulate offline mode for Tap to Pay on iPhone.
Configure simulated offline mode
The SimulatedOfflineModeConfiguration object has two properties that you can configure independently:
- sdkOfflineMode : Simulates network failures for calls made by the SDK itself.
- readerOfflineMode : Simulates network failures for calls made by smart readers with independent connectivity (such as WisePOS E or the related setting). This property is ignored for mobile readers because all network calls flow through the SDK for those reader types.
| Mode | Behavior |
|---|---|
the related setting | Default. No simulation. Uses real network conditions. |
the related setting | Requests fail instantly with a network error. |
the related setting | Requests hang for 15 seconds then fail. Useful for testing retry and timeout logic. |
the related setting | Approximately 50% of requests fail randomly. Useful for testing retry behavior and partial connectivity scenarios. |
Toggle simulated offline mode
Select a language
iOS
Android
Java
No results
// Enable simulated offline mode
Terminal.shared.simulatedOfflineModeConfiguration = SimulatedOfflineModeConfiguration.fullOffline
// Reset to normal network behavior after testing
Terminal.shared.simulatedOfflineModeConfiguration = SimulatedOfflineModeConfiguration.default
Check reader network status
The OfflineStatus object lets you query the current network status of the SDK and the connected reader. You can read it directly at any time:
Select a language
iOS
Android
Java
No results
let networkStatus = Terminal.shared.offlineStatus.sdk.networkStatus
Or use the OfflineDelegate (iOS) or OfflineListener (Android, Java) to receive updates whenever the network status changes:
Select a language
iOS
Android
Java
No results
class CustomOfflineDelegate: OfflineDelegate {
func terminal(_ terminal: Terminal, didChangeOfflineStatus offlineStatus: OfflineStatus) {
let networkStatus = offlineStatus.sdk.networkStatus
// Update your UI based on networkStatus
}
}
Terminal.shared.offlineDelegate = CustomOfflineDelegate()