Use this page with AI

Copy this into your coding assistant and add your request.

Read https://openiap.dev/docs/events/android/developer-provided-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 developerProvidedBillingListenerAndroid

Fired when a user selects developer-provided billing in an External Payments or Billing Choice purchase flow. Billing Choice payload fields are available in OpenIAP 2.1.0 and openiap-google 2.3.0, and require Play Billing 9.1.0+. Unlike User Choice Billing, this event is tied to the developer billing option configured for the purchase itself.

Eligibility: Availability depends on the enabled Google Play billing program and market. External Payments launched in Japan; Billing Choice has its own program eligibility.

Listener Setup

swift

// Android only - not available on iOS

Kotlin example

// Callback approach
fun addDeveloperProvidedBillingListener(
    listener: OpenIapDeveloperProvidedBillingListener
)

TypeScript example

developerProvidedBillingListenerAndroid(
  listener: (details: DeveloperProvidedBillingDetailsAndroid) => void
): Subscription

Dart example

dart

Stream<DeveloperProvidedBillingDetailsAndroid> get developerProvidedBillingAndroid;
// Android only (8.3.0+)

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

// Observable callback approach.
IDisposable subscription = OpenIapClient.Instance.DeveloperProvidedBillingAndroid.Subscribe(details =>
{
    Console.WriteLine(quot;Developer billing selected for {details.Products.Count} product(s).");
});

Kotlin (KMP) example

suspend fun developerProvidedBillingAndroid(): DeveloperProvidedBillingDetailsAndroid

Registers a listener for Developer Provided Billing events. This listener is triggered when the user selects the developer's payment option instead of Google Play in an enabled developer billing program.

React Native and Expo hook users can pass the same callback through onDeveloperProvidedBillingAndroid. The hook also accepts billingChoiceScreenTypeAndroid and returns the Billing Choice Android APIs.

const {
  getBillingChoiceInfoAndroid,
  showInAppMessagesAndroid,
} = useIAP({
  enableBillingProgramAndroid: 'billing-choice',
  billingChoiceScreenTypeAndroid: 'google-rendered',
  onDeveloperProvidedBillingAndroid: (details) => {
    void processDeveloperBilling(details).catch((error) => {
      console.error('Developer billing failed', error);
    });
  },
});

import dev.hyo.openiap.DeveloperProvidedBillingDetailsAndroid

// Using callback
openIapStore.addDeveloperProvidedBillingListener { details ->
    lifecycleScope.launch {
        val paymentResult = processPaymentWithYourGateway(
            products = details.products,
            linkUri = details.linkUri
        )

        if (paymentResult.success) {
            details.externalTransactionToken?.let { token ->
                reportExternalTransactionToGoogle(token)
            }
            grantUserAccess()
        }
    }
}

TypeScript example

import {
  developerProvidedBillingListenerAndroid,
  type DeveloperProvidedBillingDetailsAndroid,
} from 'expo-iap';

async function handleDeveloperBilling(details: DeveloperProvidedBillingDetailsAndroid) {
  // Use products and linkUri to choose your in-app or external-link checkout.
  const paymentResult = await processPaymentWithYourGateway({
    products: details.products,
    linkUri: details.linkUri,
  });

  if (paymentResult.success) {
    if (details.externalTransactionToken) {
      await reportExternalTransactionToGoogle(
        details.externalTransactionToken,
      );
    }
    grantUserAccess();
  }
}

const subscription = developerProvidedBillingListenerAndroid((details) => {
  void handleDeveloperBilling(details).catch((error) => {
    console.error('Developer 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 (8.3.0+) - will not fire on iOS or older Android
Future<void> handleDeveloperBilling(DeveloperProvidedBillingDetailsAndroid details) async {
  final paymentResult = await processPaymentWithYourGateway(
    products: details.products,
    linkUri: details.linkUri,
  );

  if (paymentResult.success) {
    final token = details.externalTransactionToken;
    if (token != null) {
      await reportExternalTransactionToGoogle(token);
    }
    grantUserAccess();
  }
}

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

// Cleanup when done
subscription.cancel();

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

async Task HandleDeveloperBillingSafelyAsync(DeveloperProvidedBillingDetailsAndroid details)
{
    try
    {
        var paymentResult = await ProcessPaymentWithYourGatewayAsync(
            details.Products,
            details.LinkUri);

        if (paymentResult.Success)
        {
            if (details.ExternalTransactionToken is { Length: > 0 } token)
            {
                await ReportExternalTransactionToGoogleAsync(token);
            }
            await GrantUserAccessAsync();
        }
    }
    catch (Exception error)
    {
        Console.WriteLine(quot;Developer billing failed: {error.Message}");
    }
}

var subscription = OpenIapClient.Instance.DeveloperProvidedBillingAndroid.Subscribe(
    details => _ = HandleDeveloperBillingSafelyAsync(details));

// Cleanup when done.
subscription.Dispose();

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.developerProvidedBillingAndroid()
    val paymentResult = processPaymentWithYourGateway(
        products = details.products,
        linkUri = details.linkUri
    )

    if (paymentResult.success) {
        details.externalTransactionToken?.let { token ->
            reportExternalTransactionToGoogle(token)
        }
        grantUserAccess()
    }
}

Event Payload

swift

// Android only - not available on iOS

Kotlin example

data class DeveloperProvidedBillingDetailsAndroid(
    val externalTransactionToken: String?,
    val linkUri: String?,
    val originalExternalTransactionId: String?,
    val products: List<DeveloperProvidedBillingProductAndroid>
)

TypeScript example

interface DeveloperProvidedBillingDetailsAndroid {
  externalTransactionToken?: string | null;
  linkUri?: string | null;
  originalExternalTransactionId?: string | null;
  products: DeveloperProvidedBillingProductAndroid[];
}

interface DeveloperProvidedBillingProductAndroid {
  id: string;
  type: 'in-app' | 'subs';
  offerToken?: string | null;
}

Dart example

dart

class DeveloperProvidedBillingDetailsAndroid {
  final String? externalTransactionToken;
  final String? linkUri;
  final String? originalExternalTransactionId;
  final List<DeveloperProvidedBillingProductAndroid> products;
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

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

Kotlin (KMP) example

data class DeveloperProvidedBillingDetailsAndroid(
    val externalTransactionToken: String?,
    val linkUri: String?,
    val originalExternalTransactionId: String?,
    val products: List<DeveloperProvidedBillingProductAndroid>
)

externalTransactionToken, linkUri, and originalExternalTransactionId are nullable. The callback always includes products; each item has an id, type, and optional subscription offerToken.

Comparison: User Choice vs Developer Provided Billing

Feature	User Choice Billing	Developer Provided Billing
Billing Library	7.0+	8.3.0+
Availability	Eligible regions	Program and market eligibility; External Payments launched in Japan, while Billing Choice uses separate eligibility.
When presented	During `requestPurchase()`	During requestPurchase()
UI	Google Play user-choice dialog in the billing flow	Program-specific in-app or external-link choice flow
Event	`UserChoiceBillingAndroid`	`DeveloperProvidedBillingAndroid`
Setup	`enableBillingProgramAndroid: BillingProgramAndroid.UserChoiceBilling`	Set `enableBillingProgramAndroid` to `ExternalPayments` or `BillingChoice`, then pass `developerBillingOption` to `requestPurchase`.

Important: When Google Play returns an external transaction token, send it to your backend and report the completed external transaction within the applicable program deadline. Do not log or expose the token.

See Billing Programs types and the external purchase guide for setup and purchase examples.