Use this page with AI

Copy this into your coding assistant and add your request.

Read https://openiap.dev/docs/events/android/user-choice-billing-listener-android and https://openiap.dev/llms.txt. Follow the reading instructions, detailed reference, and linked guides relevant to my task before making changes.
Inspect my existing project and reuse its framework and conventions. Ask me for missing product decisions. Implement the requested behavior and run the applicable checks.
Show the working result, the commands and actual test results, and any remaining limitations. Keep your explanation brief.

My request: [describe what customers should be able to do]

Android userChoiceBillingListenerAndroid

Fired when a user selects alternative billing in the User Choice Billing dialog on Android.

With openiap-google 3.6.3+, selecting alternative billing completes the native purchase request without a Google Play purchase. After your external checkout finishes or is canceled, you can call requestPurchase again without reconnecting. This event does not confirm payment; verify the external payment on your backend before granting access.

originalExternalTransactionId and productDetailsAndroid are available in OpenIAP 2.3.0 / openiap-google 2.3.1 (requires Play Billing 9.1+). Legacy payloads may omit structured product details; use products as the product-ID fallback.

Listener Setup

swift

// Android only - not available on iOS

Kotlin example

fun addUserChoiceBillingListener(
    listener: OpenIapUserChoiceBillingListener
)

TypeScript example

userChoiceBillingListenerAndroid(
  listener: (details: UserChoiceBillingDetails) => void
): Subscription

Dart example

dart

Stream<UserChoiceBillingDetails> get userChoiceBillingAndroid;
// Android only

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

IObservable<UserChoiceBillingDetails> UserChoiceBillingAndroid { get; }

Kotlin (KMP) example

suspend fun userChoiceBillingAndroid(): UserChoiceBillingDetails

Registers a listener for User Choice Billing events. This listener is only triggered when the user selects alternative billing instead of Google Play billing.

import dev.hyo.openiap.listener.OpenIapUserChoiceBillingListener

val userChoiceListener = OpenIapUserChoiceBillingListener { details ->
    lifecycleScope.launch {
        println("User chose alternative billing")
        println("Products: ${details.products}")
        println("External transaction token received; send it to your backend without logging it.")

        // Process payment with your backend
        val paymentResult = processPaymentWithBackend(
            products = details.products,
            token = details.externalTransactionToken
        )

        if (paymentResult.success) {
            // Backend should report token to Google Play within 24 hours
            grantUserAccess(details.products)
        }
    }
}

openIapStore.addUserChoiceBillingListener(userChoiceListener)

// Cleanup when done
openIapStore.removeUserChoiceBillingListener(userChoiceListener)

TypeScript example

import {
  userChoiceBillingListenerAndroid,
  type UserChoiceBillingDetails,
} from 'expo-iap';

async function handleUserChoiceBilling(details: UserChoiceBillingDetails) {
  console.log('User chose alternative billing');
  console.log('Products:', details.products);
  console.log('External transaction token received; send it to your backend without logging it.');

  // Process payment with your backend
  const paymentResult = await processPaymentWithBackend({
    products: details.products,
    token: details.externalTransactionToken,
  });

  if (paymentResult.success) {
    // Backend should report token to Google Play within 24 hours
    grantUserAccess(details.products);
  }
}

const subscription = userChoiceBillingListenerAndroid((details) => {
  void handleUserChoiceBilling(details).catch((error) => {
    console.error('Alternative billing failed', error);
  });
});

// Cleanup when done
subscription.remove();

Dart example

dart

import 'dart:async';
import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';

// Android only - will not fire on iOS
Future<void> handleUserChoiceBilling(UserChoiceBillingDetails details) async {
  print('User chose alternative billing');
  print('Products: ${details.products}');
  print('External transaction token received; send it to your backend without logging it.');

  // Process payment with your backend
  final paymentResult = await processPaymentWithBackend(
    products: details.products,
    token: details.externalTransactionToken,
  );

  if (paymentResult.success) {
    // Backend should report token to Google Play within 24 hours
    grantUserAccess(details.products);
  }
}

final subscription = FlutterInappPurchase.instance.userChoiceBillingAndroid.listen((details) {
  unawaited(handleUserChoiceBilling(details).catchError(
    (Object error) => print('Alternative billing failed: $error'),
  ));
});

// Cleanup when done
subscription.cancel();

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;
using System;

async Task ProcessUserChoiceBillingSafelyAsync(UserChoiceBillingDetails details)
{
    try
    {
        await ProcessUserChoiceBillingAsync(details);
    }
    catch (Exception error)
    {
        Console.WriteLine(quot;Alternative billing failed: {error.Message}");
    }
}

using var subscription = OpenIapClient.Instance.UserChoiceBillingAndroid.Subscribe(details =>
{
    Console.WriteLine("User chose alternative billing");
    Console.WriteLine(quot;Products: {string.Join(", ", details.Products)}");
    Console.WriteLine("External transaction token received; send it to your backend without logging it.");

    // Process payment with your backend.
    _ = ProcessUserChoiceBillingSafelyAsync(details);
});

Kotlin (KMP) example

import io.github.hyochan.kmpiap.KmpIAP

val kmpIAP = KmpIAP()

// Start this before requestPurchase; it suspends until the next selection.
lifecycleScope.launch {
    val details = kmpIAP.userChoiceBillingAndroid()
    println("User chose alternative billing")
    println("Products: ${details.products}")
    println("External transaction token received; send it to your backend without logging it.")

    val paymentResult = processPaymentWithBackend(
        products = details.products,
        token = details.externalTransactionToken
    )

    if (paymentResult.success) {
        // Backend should report token to Google Play within 24 hours
        grantUserAccess(details.products)
    }
}

Event Payload

swift

// Android only - not available on iOS

Kotlin example

data class UserChoiceBillingDetails(
    val externalTransactionToken: String,
    val products: List<String>
) {
    var originalExternalTransactionId: String? = null
        private set
    var productDetailsAndroid: List<DeveloperProvidedBillingProductAndroid>? = null
        private set
}

TypeScript example

interface UserChoiceBillingDetails {
  externalTransactionToken: string;
  originalExternalTransactionId?: string | null;
  productDetailsAndroid?: DeveloperProvidedBillingProductAndroid[] | null;
  products: string[];
}

Dart example

dart

class UserChoiceBillingDetails {
  final String externalTransactionToken;
  final String? originalExternalTransactionId;
  final List<DeveloperProvidedBillingProductAndroid>? productDetailsAndroid;
  final List<String> products;
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;
using System.Collections.Generic;

public sealed record UserChoiceBillingDetails
{
    public required string ExternalTransactionToken { get; init; }
    public string? OriginalExternalTransactionId { get; init; }
    public IReadOnlyList<DeveloperProvidedBillingProductAndroid>? ProductDetailsAndroid { get; init; }
    public required IReadOnlyList<string> Products { get; init; }
}

Kotlin (KMP) example

data class UserChoiceBillingDetails(
    val externalTransactionToken: String,
    val products: List<String>
) {
    var originalExternalTransactionId: String? = null
        private set
    var productDetailsAndroid: List<DeveloperProvidedBillingProductAndroid>? = null
        private set
}

externalTransactionToken - Token that must be reported to Google Play within 24 hours
originalExternalTransactionId - Originating external subscription transaction ID for developer-billed replacements (Play Billing 9.1+)
productDetailsAndroid - Selected product IDs, product types, and offer tokens as optional structured Play Billing 9.1+ data; use products when it is absent
products - List of product IDs selected by the user

Handling User Choice Billing

Receive UserChoiceBillingDetails via listener
Process payment with your backend payment system
Send the external transaction token to your backend
Backend reports token to Google Play within 24 hours (required for compliance)
Grant user access to purchased content

⚠️ Important: The external transaction token MUST be reported to Google Play within 24 hours. Failure to report tokens may result in account suspension. It is strongly recommended to handle token reporting on your backend server for reliability and security.

Flow Comparison

When using User Choice Billing mode, there are two possible flows depending on user selection:

Google Play selected - Standard PurchaseUpdated event fires (handle normally)
Alternative billing selected - UserChoiceBillingAndroid event fires (handle with your payment system)

See External Purchase documentation for complete implementation examples.