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:

BillingProgramAvailabilityResultAndroid#

Result of isBillingProgramAvailableAndroid():

BillingChoiceScreenTypeAndroid#

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

BillingProgramReportingDetailsAndroid#

Result of createBillingProgramReportingDetailsAndroid():

DeveloperBillingTypeAndroid#

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

BillingResultAndroid#

Billing operation result returned by Billing Choice dialogs:

BillingChoiceImageLayoutAndroid#

Image layout requested for developer-rendered Billing Choice:

GetBillingChoiceInfoParamsAndroid#

Parameters for getBillingChoiceInfoAndroid():

BillingChoiceInfoAndroid#

Display information for developer-rendered Billing Choice screens:

BillingProgramInformationDialogParamsAndroid#

Parameters for showBillingProgramInformationDialogAndroid():

LaunchExternalLinkParamsAndroid#

Parameters for launchExternalLinkAndroid():

ExternalLinkLaunchModeAndroid#

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

ExternalLinkTypeAndroid#

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

DeveloperBillingOptionParamsAndroid#

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

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:

DeveloperProvidedBillingDetailsAndroid#

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

DeveloperProvidedBillingProductAndroid#

InAppMessageCategoryAndroid#

In-app billing message categories:

InAppMessageParamsAndroid#

Parameters for showInAppMessagesAndroid():

InAppMessageResponseCodeAndroid#

Result code returned by Play billing in-app messages:

InAppMessageResultAndroid#

Result of showing Play billing in-app messages:

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)
}

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.