Use this page with AI

Copy this into your coding assistant and add your request.

Read https://openiap.dev/docs/types/billing-programs 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]

Billing Programs

Billing Programs (Android 8.2.0+)#

Google Play Billing Library 8.2.0+ introduces the Billing Programs API, which provides a more structured approach to external offers and content links. Version 8.3.0 adds External Payments for Japan, and 9.1.0 adds Billing Choice. OpenIAP exposes Billing Choice in Spec 2.1.0 and openiap-google 2.3.0.

Identifiers for Play Billing programs. Android only (Google docs).

Native references: Google · Play Billing 8.2.0 release notes · 8.3.0 release notes · 9.1.0 release notes

BillingProgramAndroid#

Enum for different billing program types. Use with enableBillingProgramAndroid in InitConnectionConfig:

Name	Summary	Version
`USER_CHOICE_BILLING`	User can select between Google Play or alternative billing	7.0+
`EXTERNAL_CONTENT_LINK`	For apps that link to external content (reader apps, music streaming)	8.2.0+
`EXTERNAL_OFFER`	For apps offering alternative payment options (replaces ALTERNATIVE_ONLY)	8.2.0+
`EXTERNAL_PAYMENTS`	Side-by-side choice between Google Play and developer billing (Japan only)	8.3.0+
`BILLING_CHOICE`	Present Google Play Billing alongside an alternative in-app billing system or external web link	9.1.0+

BillingProgramAvailabilityResultAndroid#

Result of isBillingProgramAvailableAndroid():

Name	Type	Summary
`isAvailable`	`boolean`	Whether the billing program is available for the user
`billingProgram`	`BillingProgramAndroid`	The billing program that was checked
`choiceScreenType`	`BillingChoiceScreenTypeAndroid` `\| null`	Billing Choice renderer. Present only for available `BILLING_CHOICE` checks.
`isExternalLinkAvailable`	`boolean \| null`	Whether external-link developer billing is available for Billing Choice.

BillingChoiceScreenTypeAndroid#

How the Billing Choice screen should be rendered (9.1.0+):

Name	Summary
`UNSPECIFIED`	Unspecified renderer.
`DEVELOPER_RENDERED`	The app renders the Billing Choice screen using `getBillingChoiceInfoAndroid()`.
`GOOGLE_RENDERED`	Google Play renders the Billing Choice screen and information dialog.

BillingProgramReportingDetailsAndroid#

Result of createBillingProgramReportingDetailsAndroid():

Name	Type	Summary
`billingProgram`	`BillingProgramAndroid`	The billing program associated with these details
`externalTransactionToken`	`string`	Token to report external transactions to Google (must report within 24 hours)

DeveloperBillingTypeAndroid#

Developer billing destination type used when creating Billing Choice reporting details (9.1.0+):

Name	Summary
`DEVELOPER_BILLING_TYPE_UNSPECIFIED`	Unspecified type. Do not use.
`IN_APP`	Developer-provided billing inside the app.
`EXTERNAL_LINK`	Developer-provided billing via an external link.

BillingResultAndroid#

Billing operation result returned by Billing Choice dialogs:

Name	Type	Summary
`responseCode`	`number`	Play Billing response code.
`debugMessage`	`string \| null`	Optional Play Billing debug message.
`subResponseCode`	`SubResponseCodeAndroid \| null`	Optional granular response code.

BillingChoiceImageLayoutAndroid#

Image layout requested for developer-rendered Billing Choice:

Name	Summary
`RECTANGULAR_FOUR_BY_ONE`	Rectangular image with a 4:1 aspect ratio.
`RECTANGULAR_THREE_BY_ONE`	Rectangular image with a 3:1 aspect ratio.
`RECTANGULAR_TWO_BY_TWO`	Rectangular image with a 2:2 aspect ratio.

GetBillingChoiceInfoParamsAndroid#

Parameters for getBillingChoiceInfoAndroid():

Name	Type	Summary
`billingProgram`	`BillingProgramAndroid`	Billing program. Defaults to `BILLING_CHOICE`.
`playBillingChoiceImageLayout`	`BillingChoiceImageLayoutAndroid`	Requested image layout. Defaults to `RECTANGULAR_FOUR_BY_ONE`.
`userLocale`	`string \| null`	Optional BCP 47 locale tag.

BillingChoiceInfoAndroid#

Display information for developer-rendered Billing Choice screens:

Name	Type	Summary
`playBillingChoiceImageUrl`	`string`	Play Billing image URL for the requested layout.
`playBillingLoyaltyInfo`	`string \| null`	Optional Play loyalty information for the user.

BillingProgramInformationDialogParamsAndroid#

Parameters for showBillingProgramInformationDialogAndroid():

Name	Type	Summary
`billingProgram`	`BillingProgramAndroid`	Billing program. Defaults to `BILLING_CHOICE`.
`externalTransactionToken`	`string`	Billing Choice reporting token.

LaunchExternalLinkParamsAndroid#

Parameters for launchExternalLinkAndroid():

Name	Type	Summary
`billingProgram`	`BillingProgramAndroid`	The billing program (`EXTERNAL_CONTENT_LINK`, `EXTERNAL_OFFER`, or `BILLING_CHOICE`)
`externalTransactionToken`	`string \| null`	Pre-generated token for a developer-rendered Billing Choice external-link flow (9.1.0+)
`launchMode`	`ExternalLinkLaunchModeAndroid`	How the external link is launched
`linkType`	`ExternalLinkTypeAndroid`	The type of the external link
`linkUri`	`string`	The URI where the external content will be accessed

ExternalLinkLaunchModeAndroid#

How the external URL is launched (Play Billing Library 8.2.0+):

Name	Summary
`UNSPECIFIED`	Unspecified launch mode. Do not use.
`LAUNCH_IN_EXTERNAL_BROWSER_OR_APP`	Play launches the URL in an external browser or eligible app.
`CALLER_WILL_LAUNCH_LINK`	Play does not launch the URL — the app handles launching the URL after Play returns control.

ExternalLinkTypeAndroid#

Type of external link destination (Play Billing Library 8.2.0+):

Name	Summary
`UNSPECIFIED`	Unspecified link type. Do not use.
`LINK_TO_DIGITAL_CONTENT_OFFER`	The link directs users to a digital content offer.
`LINK_TO_APP_DOWNLOAD`	The link directs users to download an app.

DeveloperBillingOptionParamsAndroid#

Parameters for configuring developer billing option in purchase flow (8.3.0+; Billing Choice also uses this shape in 9.1.0+):

Name	Type	Summary
`billingProgram`	`BillingProgramAndroid`	The billing program (usually `EXTERNAL_PAYMENTS` or `BILLING_CHOICE`)
`linkUri`	`string \| null`	URL for an external-link flow. Omit it for an in-app Billing Choice flow.
`launchMode`	`DeveloperBillingLaunchModeAndroid` `\| null`	How to launch an external link. Omit it when no link is used.
`externalTransactionToken`	`string \| null`	Optional pre-generated token for a Billing Choice external-link flow.

For an in-app Billing Choice flow, pass only billingProgram: BILLING_CHOICE. Add linkUri, launchMode, and optionally externalTransactionToken only for an external-link flow.

DeveloperBillingLaunchModeAndroid#

How the external payment URL is launched:

Name	Summary
`LAUNCH_IN_EXTERNAL_BROWSER_OR_APP`	Google Play launches the link in a browser or eligible app
`CALLER_WILL_LAUNCH_LINK`	Your app handles launching the link after Play returns control

DeveloperProvidedBillingDetailsAndroid#

Details received when a user selects developer billing (8.3.0+; expanded in Billing 9.0 and 9.1):

Name	Type	Summary
`externalTransactionToken`	`string \| null`	Token used for external transaction reporting when one is returned for the selected flow.
`linkUri`	`string \| null`	Link for a Billing Choice external-link flow.
`originalExternalTransactionId`	`string \| null`	Original developer-billed subscription transaction being replaced.
`products`	`DeveloperProvidedBillingProductAndroid[]`	Products selected for the developer billing flow.

DeveloperProvidedBillingProductAndroid#

Name	Type	Summary
`id`	`string`	Google Play product identifier.
`type`	`ProductType`	Normalized product type: `IN_APP` or `SUBS`.
`offerToken`	`string \| null`	Subscription offer token, when applicable.

InAppMessageCategoryAndroid#

In-app billing message categories:

Name	Summary
`UNKNOWN_IN_APP_MESSAGE_CATEGORY_ID`	Unknown category. Do not use.
`TRANSACTIONAL`	Transactional billing messages, such as subscription status changes.

InAppMessageParamsAndroid#

Parameters for showInAppMessagesAndroid():

Name	Type	Summary
`categories`	`InAppMessageCategoryAndroid[]` `\| null`	Categories to show. Defaults to `TRANSACTIONAL`.

InAppMessageResponseCodeAndroid#

Result code returned by Play billing in-app messages:

Name	Summary
`NO_ACTION_NEEDED`	Flow finished and no developer action is needed.
`SUBSCRIPTION_STATUS_UPDATED`	Subscription status changed; refresh the purchase referenced by the returned token.

InAppMessageResultAndroid#

Result of showing Play billing in-app messages:

Name	Type	Summary
`responseCode`	`InAppMessageResponseCodeAndroid`	Flow result.
`purchaseToken`	`string \| null`	Purchase token returned when a subscription status changed.

Usage Example#

import dev.hyo.openiap.store.OpenIapStore
import dev.hyo.openiap.*

val iapStore = OpenIapStore(context)

// Enable External Payments via InitConnectionConfig
check(iapStore.initConnection(
    InitConnectionConfig(
        enableBillingProgramAndroid = BillingProgramAndroid.ExternalPayments
    )
)) { "Store connection failed" }

// Listen for developer billing selection
iapStore.addDeveloperProvidedBillingListener { details ->
    Log.d("IAP", "External transaction token received; send it to your backend without logging it.")
    // Report token to Google via your backend within 24 hours
}

// Check availability (Japan only)
val result = iapStore.isBillingProgramAvailable(
    BillingProgramAndroid.ExternalPayments
)
if (result.isAvailable) {
    // Purchase with developer billing option
    val props = RequestPurchaseProps(
        request = RequestPurchaseProps.Request.Purchase(
            RequestPurchasePropsByPlatforms(
                google = RequestPurchaseAndroidProps(
                    skus = listOf("product_id"),
                    developerBillingOption = DeveloperBillingOptionParamsAndroid(
                        billingProgram = BillingProgramAndroid.ExternalPayments,
                        linkUri = "https://your-site.com/checkout",
                        launchMode = DeveloperBillingLaunchModeAndroid.LaunchInExternalBrowserOrApp
                    )
                )
            )
        ),
        type = ProductQueryType.InApp
    )
    iapStore.requestPurchase(props)
}

TypeScript example

import {
  initConnection,
  isBillingProgramAvailableAndroid,
  requestPurchase,
  developerProvidedBillingListenerAndroid,
} from 'expo-iap';

// Enable External Payments via InitConnectionConfig
const connected = await initConnection({
  enableBillingProgramAndroid: 'external-payments',
});
if (!connected) throw new Error('Store connection failed');

// Listen for developer billing selection
developerProvidedBillingListenerAndroid((details) => {
  console.log('External transaction token received; send it to your backend without logging it.');
  // Report token to Google via your backend within 24 hours
});

// Check availability (Japan only)
const result = await isBillingProgramAvailableAndroid('external-payments');
if (result.isAvailable) {
  // Purchase with developer billing option
  await requestPurchase({
    request: {
      google: {
        skus: ['product_id'],
        developerBillingOption: {
          billingProgram: 'external-payments',
          linkUri: 'https://your-site.com/checkout',
          launchMode: 'launch-in-external-browser-or-app',
        },
      },
    },
    type: 'in-app',
  });
}

Dart example

dart

import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';

// Enable External Payments via InitConnectionConfig
final connected = await FlutterInappPurchase.instance.initConnection(
  enableBillingProgramAndroid: BillingProgramAndroid.ExternalPayments,
);
if (!connected) throw StateError('Store connection failed');

// Listen for developer billing selection
final developerBillingSubscription = FlutterInappPurchase.instance
    .developerProvidedBillingAndroid
    .listen((details) {
  print('External transaction token received; send it to your backend without logging it.');
  // Report token to Google via your backend within 24 hours
});

// Check availability (Japan only)
final result = await FlutterInappPurchase.instance
    .isBillingProgramAvailableAndroid(BillingProgramAndroid.ExternalPayments);
if (result.isAvailable) {
  // Purchase with developer billing option
  await FlutterInappPurchase.instance.requestPurchase(
    RequestPurchaseProps.inApp((
      apple: null,
      google: RequestPurchaseAndroidProps(
        skus: ['product_id'],
        developerBillingOption: DeveloperBillingOptionParamsAndroid(
          billingProgram: BillingProgramAndroid.ExternalPayments,
          linkUri: 'https://your-site.com/checkout',
          launchMode: DeveloperBillingLaunchModeAndroid.LaunchInExternalBrowserOrApp,
        ),
      ),
    )),
  );
}

await developerBillingSubscription.cancel();

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;
using System;

// Enable External Payments via InitConnectionConfig.
var connected = await OpenIapClient.Mutation.InitConnectionAsync(new InitConnectionConfig
{
    EnableBillingProgramAndroid = BillingProgramAndroid.ExternalPayments,
});
if (!connected) throw new InvalidOperationException("Store connection failed");

// Listen for developer billing selection.
using var subscription = OpenIapClient.Instance.DeveloperProvidedBillingAndroid.Subscribe(details =>
{
    Console.WriteLine("External transaction token received; send it to your backend without logging it.");
    // Report token to Google via your backend within 24 hours.
});

// Check availability (Japan only).
var result = await OpenIapClient.Mutation
    .IsBillingProgramAvailableAndroidAsync(BillingProgramAndroid.ExternalPayments);
if (result.IsAvailable)
{
    // Purchase with developer billing option
    var props = new RequestPurchaseProps
    {
        RequestPurchase = new RequestPurchasePropsByPlatforms
        {
            Google = new RequestPurchaseAndroidProps
            {
                Skus = new[] { "product_id" },
                DeveloperBillingOption = new DeveloperBillingOptionParamsAndroid
                {
                    BillingProgram = BillingProgramAndroid.ExternalPayments,
                    LinkUri = "https://your-site.com/checkout",
                    LaunchMode = DeveloperBillingLaunchModeAndroid.LaunchInExternalBrowserOrApp,
                },
            },
        },
        Type = ProductQueryType.InApp,
    };
    await OpenIapClient.Mutation.RequestPurchaseAsync(props);
}

GDScript example

# Enable External Payments via InitConnectionConfig
var config = InitConnectionConfig.new()
config.enable_billing_program_android = BillingProgramAndroid.EXTERNAL_PAYMENTS
var connected = await iap.init_connection(config)
if not connected:
    push_error("Store connection failed")
    return

# Listen for developer billing selection
func _on_developer_provided_billing(details: DeveloperProvidedBillingDetailsAndroid):
    print("External transaction token received; send it to your backend without logging it.")
    # Report token to Google via your backend within 24 hours

iap.developer_provided_billing_android.connect(_on_developer_provided_billing)

# Check availability (Japan only)
var result = await iap.is_billing_program_available_android(
    BillingProgramAndroid.EXTERNAL_PAYMENTS
)
if result.is_available:
    # Purchase with developer billing option
    var props = RequestPurchaseProps.new()
    props.request = RequestPurchasePropsByPlatforms.new()
    props.request.google = RequestPurchaseAndroidProps.new()
    props.request.google.skus.assign(["product_id"])
    props.request.google.developer_billing_option = DeveloperBillingOptionParamsAndroid.new()
    props.request.google.developer_billing_option.billing_program = BillingProgramAndroid.EXTERNAL_PAYMENTS
    props.request.google.developer_billing_option.link_uri = "https://your-site.com/checkout"
    props.request.google.developer_billing_option.launch_mode = DeveloperBillingLaunchModeAndroid.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
    props.type = ProductQueryType.IN_APP
    await iap.request_purchase(props)

Token Reporting: When a user completes a purchase through developer billing, you must report the externalTransactionToken to Google Play within 24 hours. See External Payments documentation for complete implementation details.