Error Handling & Troubleshooting

The payabl. SDKs surface errors at every stage — initialization, network, and payment processing. This guide shows where errors appear in your code, how to diagnose common scenarios, and what to include when you report an issue.

How errors surface in the SDK

Errors reach your app through two channels:

1. The payment result. Every payment flow returns a result with three outcomes — completed, cancelled, or failed. Always handle all three:

Android:

when (result) {
    is PBLPaymentResult.Completed -> { /* update order status */ }
    is PBLPaymentResult.Canceled -> { /* user backed out */ }
    is PBLPaymentResult.Failed -> { /* surface the failure, allow retry */ }
}

iOS:

switch result {
case .completed: break // update order status
case .canceled: break  // user backed out
case .failed: break    // surface the failure, allow retry
}

2. SDK errors outside the payment result (iOS). Configuration and session problems raised before or outside a payment flow are delivered through PBLErrorDelegate:

extension CartViewModel: PBLErrorDelegate {
    func errorOccured(error: any Error) {
        // e.g., configuration or session issues
    }
}

On Android, wrap PayablSDK.init and flow launches in a try/catch to capture initialization errors.

Common error scenarios

Troubleshooting steps

1. Reproduce and isolate — replicate the error in the sandbox and note the exact steps.
2. Verify configuration — session credentials fresh, environment matching, method-specific setup complete.
3. Review logs — monitor Logcat (Android) or the Xcode console (iOS) for error messages and stack traces during SDK operations.
4. Test connectivity — confirm the device/simulator has internet access and nothing is blocking requests.
5. Compare against the demo app — the demo apps implement every flow correctly against the sandbox; if the demo works on your device and your integration doesn't, diff your setup against the demo source.

Gateway and card error references

The authoritative transaction status and decline reasons are available on the gateway side (for example, via the notification_url webhook and your transaction records). To understand why payments decline and how to reduce declines, see Declines and Failed Payments. For detailed code catalogs:

1. payabl. Response codes — status codes generated and returned by payabl.
2. Card issuer error codes
3. Mastercard Merchant Advice Codes

When to contact support

If the issue persists, contact [email protected]. To help us resolve your issue quickly, include:

• The transaction_id or session_id of the affected payment (returned by your /mobile/init call) — this lets us locate the exact transaction immediately.
• Step-by-step reproduction — what you did, what you expected, what happened instead.
• Your merchant ID, the platform (Android/iOS) and SDK version, and the environment (sandbox/production).
• Logs from Logcat or the Xcode console covering the failure.