Map user-cancelled PlatformException to PurchaseError on purchase flow cancellation

[FeanorD]

Description

When a user cancels the subscription purchase flow, _iap.requestPurchase(builder.build()) throws

PurchaseError(
    code: gentype.ErrorCode.ServiceError,
    message: 'Failed to request purchase: ${error.toString()}',
)

when it catches PlatformException(user-cancelled, User cancelled the purchase flow, wo_pledge_v1_monthly, null). I think, in this case, it would be great to map PlatformException to PurchaseError with the right error code, as it provides a code: 'user-cancelled' that could be mapped to ErrorCode.UserCancelled, and a String message.

Expected Behavior

When a user cancels the subscription purchase flow _iap.requestPurchase(...) should return PurchaseError(code: ErrorCode.UserCancelled) instead of a PurchaseError(code: ErrorCode.ServiceError, ...).

Screenshots

Environment

• flutter_inapp_purchase: 8.2.7
• Flutter: 3.38.8
• Dart: 3.10.7
• Platforms: iOS 15.8 real device
• iOS deployment target: 15.0
• Xcode version: 26.2 (17C52)

Latest Version Check

• Confirmed the issue reproduces on the latest flutter_inapp_purchase

To Reproduce

Steps to reproduce the behavior:

1. Wrap _iap.requestPurchase(...) call in a try-catch
2. Call _iap.requestPurchase(...)
3. Cancel the subscription flow / close the native bottom sheet without purchasing the item
4. Catch the PurchaseError(code: ErrorCode.ServiceError, ...)

[gitdogdev]

@FeanorD ## Issue Summary

When a user cancels the subscription purchase flow on iOS, requestPurchase() throws a raw PlatformException with code 'user-cancelled' instead of mapping it to a PurchaseError with code: ErrorCode.UserCancelled.

Current Behavior

The requestPurchase() method in the iOS implementation catches platform exceptions but doesn't properly map the 'user-cancelled' code to the expected ErrorCode.UserCancelled enum value. This causes inconsistent error handling across platforms and breaks the contract of the public API.

Root Cause

In the iOS native code, when a user cancels a purchase, StoreKit returns an error with code 'user-cancelled'. The current implementation either:

1. Doesn't catch this specific error code, or
2. Re-throws it as a raw PlatformException instead of wrapping it in a PurchaseError

This differs from the Android implementation, which properly maps cancellation errors to ErrorCode.UserCancelled.

Expected Behavior

The requestPurchase() method should catch the 'user-cancelled' platform exception and throw a PurchaseError with:

• code: ErrorCode.UserCancelled
• message: 'User cancelled the purchase' (or similar)

This ensures consistent error handling across both iOS and Android platforms.

Proposed Solution

Update the iOS error handling in the requestPurchase() method to include:

catch (e) {
  if (e is PlatformException && e.code == 'user-cancelled') {
    throw PurchaseError(
      code: ErrorCode.UserCancelled,
      message: 'User cancelled the purchase',
    );
  }
  rethrow;
}

This mapping should be applied at the Dart layer to normalize the platform-specific error codes into the app's unified error model.

---

🤖 Generated by gitdog.dev · Have more questions? Tag @gitdog and let me know!

[FeanorD]

@gitdogdev, UPD: changed the description to make it clearer

[gitdogdev]

@FeanorD ## Follow-up Summary

Your clarified description accurately captures the issue:

Current Behavior:
When a user cancels the subscription purchase flow on iOS, requestPurchase() throws:

An `SKErrorDomain` error with code 2 (userCancelled)

Expected Behavior:
The cancellation should be handled gracefully without throwing an exception, or the exception should be catchable and identifiable as a user cancellation rather than a genuine error.

Root Cause:
The requestPurchase() function doesn't distinguish between user-initiated cancellations and actual errors. On iOS, when a user cancels the purchase dialog, the StoreKit framework returns an error that gets propagated directly to the caller without any special handling.

Recommended Solutions

1. Wrap the Purchase Call in Try-Catch (Immediate Workaround)

try {
    billingClient.requestPurchase(productDetails, activity)
} catch (e: Exception) {
    if (e.message?.contains("userCancelled") == true || 
        e.message?.contains("SKError") == true) {
        // Handle user cancellation gracefully
        Log.d("Purchase", "User cancelled the purchase")
    } else {
        // Handle actual errors
        Log.e("Purchase", "Purchase failed: ${e.message}")
    }
}

2. Check Error Code Before Throwing (Better Approach)

Implement a custom error handler that examines the error code:

private fun isPurchaseCancellation(error: BillingResult): Boolean {
    return error.responseCode == BillingClient.BillingResponseCode.USER_CANCELED
}

3. Use Flow/StateFlow for Purchase State

Emit different states rather than throwing exceptions:

sealed class PurchaseState {
    object Idle : PurchaseState()
    object Loading : PurchaseState()
    object Success : PurchaseState()
    object UserCancelled : PurchaseState()
    data class Error(val message: String) : PurchaseState()
}

This approach gives you better control over how cancellations are handled throughout your app.

---

🤖 Generated by gitdog.dev · Have more questions? Tag @gitdog and let me know!

[hyochan]

This has been fixed in v8.2.8.

All PlatformException catch blocks across the plugin now properly map the platform error code to the corresponding ErrorCode using ErrorCodeUtils.fromPlatformCode(), instead of falling back to ErrorCode.ServiceError.

For example, a user cancellation (user-cancelled) will now correctly result in:

PurchaseError(
  code: ErrorCode.UserCancelled,
  message: '...',
)

Please upgrade to 8.2.8:

dependencies:
  flutter_inapp_purchase: ^8.2.8

See PR #621 for the full changeset.