8.1.2 - External Payments Program

v8.1.2 adds support for Google Play Billing Library 8.3.0's External Payments program and enableBillingProgramAndroid in InitConnectionConfig.

What's New

External Payments Program (Android 8.3.0+, Japan Only)

Google Play Billing Library 8.3.0 introduces the External Payments program, which presents users with a side-by-side choice between Google Play Billing and the developer's external payment option directly in the purchase flow.

Key differences from User Choice Billing:

Feature	User Choice Billing	External Payments
Billing Library	7.0+	8.3.0+
Availability	Eligible regions	Japan only
UI	Separate dialog	Side-by-side in purchase dialog

New APIs

BillingProgramAndroid.ExternalPayments

New billing program type for external payments:

final isAvailable = await iap.isBillingProgramAvailableAndroid(
  BillingProgramAndroid.ExternalPayments,
);

DeveloperBillingOptionParamsAndroid

Configure the external payment option in the purchase flow:

await iap.requestPurchaseWithBuilder(
  build: (builder) {
    builder.android.skus = ['product_id'];
    builder.android.developerBillingOption = DeveloperBillingOptionParamsAndroid(
      billingProgram: BillingProgramAndroid.ExternalPayments,
      launchMode: DeveloperBillingLaunchModeAndroid.LaunchInExternalBrowserOrApp,
      linkUri: 'https://example.com/checkout',
    );
    builder.type = ProductQueryType.InApp;
  },
);

DeveloperBillingLaunchModeAndroid

Controls how the external payment link is launched:

• LaunchInExternalBrowserOrApp: Google Play launches the URL in external browser
• CallerWillLaunchLink: Your app handles launching the URL

developerProvidedBillingAndroid Stream

Listen for when a user selects the developer billing option:

iap.developerProvidedBillingAndroid.listen((details) {
  // User selected developer billing
  final token = details.externalTransactionToken;

  // IMPORTANT: Report transaction to Google within 24 hours
  await reportExternalTransaction(token);
});

New Event

IapEvent.DeveloperProvidedBillingAndroid - Fired when user selects developer billing in the External Payments flow.

Implementation Example

import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';

class ExternalPaymentsExample {
  final iap = FlutterInappPurchase.instance;
  StreamSubscription? _developerBillingSubscription;

  Future<void> setup() async {
    await iap.initConnection();

    // Listen for developer billing selection
    _developerBillingSubscription =
        iap.developerProvidedBillingAndroid.listen((details) async {
      // User chose developer billing
      // The externalTransactionToken MUST be reported to Google within 24 hours
      await reportToBackend(details.externalTransactionToken);
    });
  }

  Future<void> purchaseWithExternalOption(String productId) async {
    // Check if External Payments is available
    final availability = await iap.isBillingProgramAvailableAndroid(
      BillingProgramAndroid.ExternalPayments,
    );

    if (!availability.isAvailable) {
      // Fall back to standard purchase
      await standardPurchase(productId);
      return;
    }

    // Request purchase with external payment option
    await iap.requestPurchaseWithBuilder(
      build: (builder) {
        builder.android.skus = [productId];
        builder.android.developerBillingOption = DeveloperBillingOptionParamsAndroid(
          billingProgram: BillingProgramAndroid.ExternalPayments,
          launchMode: DeveloperBillingLaunchModeAndroid.LaunchInExternalBrowserOrApp,
          linkUri: 'https://yoursite.com/checkout?product=$productId',
        );
        builder.type = ProductQueryType.InApp;
      },
    );
  }

  void dispose() {
    _developerBillingSubscription?.cancel();
  }
}

enableBillingProgramAndroid in InitConnectionConfig (Android)

New enableBillingProgramAndroid field in InitConnectionConfig for easier billing program setup during connection initialization:

// Enable External Payments during connection
await iap.initConnection(
  enableBillingProgramAndroid: BillingProgramAndroid.ExternalPayments,
);

This provides a cleaner alternative to calling enableBillingProgram() separately before initConnection().

Important Notes

1. Japan Only: External Payments is currently only available in Japan
2. Token Reporting: You MUST report the externalTransactionToken to Google Play within 24 hours
3. 8.3.0+ Required: This feature requires Google Play Billing Library 8.3.0 or higher

Dependencies

Updated OpenIAP versions:

• openiap-gql: 1.3.8 -> 1.3.10
• openiap-google: 1.3.16 -> 1.3.19
• openiap-apple: 1.3.7 -> 1.3.8