Use this page with AI

Copy this into your coding assistant and add your request.

Read https://openiap.dev/docs/features/external-purchase 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]

External Purchase

Overview

External purchase allows you to redirect users to external payment systems instead of using platform-native billing (StoreKit on iOS, Google Play Billing on Android). This enables alternative payment methods and can reduce platform fees.

Platform Support

Platform	Feature Name	Minimum OS Version	Native Framework
iOS	External Purchase URL	iOS 17.4+ (Notice Sheet) iOS 18.1+ (Custom Links)	StoreKit 2
Android	Alternative Billing / Billing Programs	Android 6.0+ (API 23)	Google Play Billing 6.2+ (legacy), 8.2.0+ (External Content Links), 8.2.1+ (External Offers), 8.3.0+ (External Payments)

Common Requirements#

Both platforms require the following infrastructure to support external purchases:

Backend Verification System

Payment gateway integration
Purchase verification endpoint
Entitlement management system
Transaction logging and auditing

Platform-Specific Implementation#

iOS - External Purchase

iOS supports external purchase through StoreKit's External Purchase API. The notice sheet presents within the app and returns results immediately - no browser redirect required.

Basic Usage

Check that the notice sheet can be shown, present it, then open your purchase link when the user continues:

swift

import OpenIAP

@available(iOS 17.4, *)
func handleExternalPurchaseFlow() async {
    let externalUrl = "https://your-payment-site.com/checkout"

    do {
        // Step 1: Check if notice sheet can be presented
        let canPresent = try await OpenIapModule.shared
            .canPresentExternalPurchaseNoticeIOS()

        guard canPresent else {
            print("External purchase notice sheet not available")
            return
        }

        // Step 2: Present notice sheet (Apple's info sheet)
        let noticeResult = try await OpenIapModule.shared
            .presentExternalPurchaseNoticeSheetIOS()

        if noticeResult.result == .continue {
            // Step 3: Present external purchase link
            let linkResult = try await OpenIapModule.shared
                .presentExternalPurchaseLinkIOS(externalUrl)

            if linkResult.success {
                print("User acknowledged external purchase")
                // User approved external purchase
                // Call your backend API to initiate purchase
                // await yourBackend.createPurchase(productId, userId)
            } else {
                print("External purchase link failed: \(linkResult.error ?? "")")
            }
        } else {
            print("User dismissed notice sheet")
        }
    } catch {
        print("External purchase error: \(error)")
    }
}

Kotlin example

import dev.openiap.OpenIap
import dev.openiap.ExternalPurchaseNoticeAction

// iOS 17.4+ External Purchase Flow (from Kotlin Multiplatform)
suspend fun handleExternalPurchaseFlow() {
    val externalUrl = "https://your-payment-site.com/checkout"

    try {
        // Step 1: Check if notice sheet can be presented
        val canPresent = OpenIap.canPresentExternalPurchaseNoticeIOS()

        if (!canPresent) {
            println("External purchase notice sheet not available")
            return
        }

        // Step 2: Present notice sheet (Apple's info sheet)
        val noticeResult = OpenIap.presentExternalPurchaseNoticeSheetIOS()

        if (noticeResult.result == ExternalPurchaseNoticeAction.Continue) {
            // Step 3: Present external purchase link
            val linkResult = OpenIap.presentExternalPurchaseLinkIOS(externalUrl)

            if (linkResult.success) {
                println("User acknowledged external purchase")
                // User approved external purchase
                // Call your backend API to initiate purchase
                // yourBackend.createPurchase(productId, userId)
            } else {
                println("External purchase link failed: ${linkResult.error ?: ""}")
            }
        } else {
            println("User dismissed notice sheet")
        }
    } catch (e: Exception) {
        println("External purchase error: ${e.message}")
    }
}

TypeScript example

import {
  canPresentExternalPurchaseNoticeIOS,
  presentExternalPurchaseNoticeSheetIOS,
  presentExternalPurchaseLinkIOS
} from 'expo-iap';

async function handleExternalPurchaseFlow() {
  const externalUrl = 'https://your-payment-site.com/checkout';

  try {
    // Step 1: Check if notice sheet can be presented
    const canPresent = await canPresentExternalPurchaseNoticeIOS();

    if (!canPresent) {
      console.log('External purchase notice sheet not available');
      return;
    }

    // Step 2: Present notice sheet (Apple's info sheet)
    const noticeResult = await presentExternalPurchaseNoticeSheetIOS();

    if (noticeResult.result === 'continue') {
      // Step 3: Present external purchase link
      const linkResult = await presentExternalPurchaseLinkIOS(externalUrl);

      if (linkResult.success) {
        console.log('User acknowledged external purchase');
        // User approved external purchase
        // Call your backend API to initiate purchase
        // await yourBackend.createPurchase(productId, userId);
      } else {
        console.log(`External purchase link failed: ${linkResult.error ?? ''}`);
      }
    } else {
      console.log('User dismissed notice sheet');
    }
  } catch (error) {
    console.error('External purchase error:', error);
  }
}

Dart example

dart

import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';

// iOS 17.4+ External Purchase Flow
Future<void> handleExternalPurchaseFlow() async {
  const externalUrl = 'https://your-payment-site.com/checkout';

  try {
    // Step 1: Check if notice sheet can be presented
    final canPresent = await FlutterInappPurchase.instance
        .canPresentExternalPurchaseNoticeIOS();

    if (!canPresent) {
      print('External purchase notice sheet not available');
      return;
    }

    // Step 2: Present notice sheet (Apple's info sheet)
    final noticeResult = await FlutterInappPurchase.instance
        .presentExternalPurchaseNoticeSheetIOS();

    if (noticeResult.result == ExternalPurchaseNoticeAction.Continue) {
      // Step 3: Present external purchase link
      final linkResult = await FlutterInappPurchase.instance
          .presentExternalPurchaseLinkIOS(externalUrl);

      if (linkResult.success) {
        print('User acknowledged external purchase');
        // User approved external purchase
        // Call your backend API to initiate purchase
        // await yourBackend.createPurchase(productId, userId);
      } else {
        print('External purchase link failed: ${linkResult.error ?? ""}');
      }
    } else {
      print('User dismissed notice sheet');
    }
  } catch (e) {
    print('External purchase error: $e');
  }
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

async Task HandleExternalPurchaseFlowAsync()
{
    var mutate = (MutationResolver)OpenIapClient.Instance;
    if (!await mutate.CanPresentExternalPurchaseNoticeIOSAsync()) return;

    var notice = await mutate.PresentExternalPurchaseNoticeSheetIOSAsync();
    if (notice.Result != ExternalPurchaseNoticeAction.Continue) return;

    var link = await mutate.PresentExternalPurchaseLinkIOSAsync(
        "https://your-payment-site.com/checkout");
    if (!link.Success)
    {
        Console.WriteLine(quot;External purchase link failed: {link.Error}");
    }
}

Kotlin (KMP) example

import io.github.hyochan.kmpiap.KmpIAP
import io.github.hyochan.kmpiap.ExternalPurchaseNoticeAction

// iOS 17.4+ External Purchase Flow (from Kotlin Multiplatform)
suspend fun handleExternalPurchaseFlow() {
    val kmpIAP = KmpIAP()
    val externalUrl = "https://your-payment-site.com/checkout"

    try {
        // Step 1: Check if notice sheet can be presented
        val canPresent = kmpIAP.canPresentExternalPurchaseNoticeIOS()

        if (!canPresent) {
            println("External purchase notice sheet not available")
            return
        }

        // Step 2: Present notice sheet (Apple's info sheet)
        val noticeResult = kmpIAP.presentExternalPurchaseNoticeSheetIOS()

        if (noticeResult.result == ExternalPurchaseNoticeAction.Continue) {
            // Step 3: Present external purchase link
            val linkResult = kmpIAP.presentExternalPurchaseLinkIOS(externalUrl)

            if (linkResult.success) {
                println("User acknowledged external purchase")
                // User approved external purchase
                // Call your backend API to initiate purchase
                // yourBackend.createPurchase(productId, userId)
            } else {
                println("External purchase link failed: ${linkResult.error ?: ""}")
            }
        } else {
            println("User dismissed notice sheet")
        }
    } catch (e: Exception) {
        println("External purchase error: ${e.message}")
    }
}

GDScript example

# iOS 17.4+ External Purchase Flow
func handle_external_purchase_flow() -> void:
    var external_url = "https://your-payment-site.com/checkout"

    # Step 1: Check if notice sheet can be presented
    var can_present = await iap.can_present_external_purchase_notice_ios()

    if not can_present:
        print("External purchase notice sheet not available")
        return

    # Step 2: Present notice sheet (Apple's info sheet)
    var notice_result = await iap.present_external_purchase_notice_sheet_ios()

    if notice_result.result == ExternalPurchaseNoticeAction.CONTINUE:
        # Step 3: Present external purchase link
        var link_result = await iap.present_external_purchase_link_ios(external_url)

        if link_result.success:
            print("User acknowledged external purchase")
            # User approved external purchase
            # Call your backend API to initiate purchase
            # await your_backend.create_purchase(product_id, user_id)
        else:
            print("External purchase link failed: %s" % (link_result.error if link_result.error else ""))
    else:
        print("User dismissed notice sheet")

Requirements

iOS 17.4+ - Required for canPresentExternalPurchaseNoticeIOS and presentExternalPurchaseNoticeSheetIOS
iOS 18.1+ - Required for the ExternalPurchaseCustomLink APIs
StoreKit 2 - Uses StoreKit 2 framework
Entitlement required - com.apple.developer.storekit.external-purchase entitlement must be configured in App Store Connect
Country code configuration - Must specify supported country codes in SKExternalPurchase array in Info.plist. Only available in EU countries and South Korea. See Apple Documentation
No deep linking required - Notice sheet presents within the app and returns results immediately

Configuration (iOS)

Add entitlement and country codes in Info.plist. Use lowercase ISO 3166-1 alpha-2 country codes:

1. SKExternalPurchase (Required)

Specify countries where your app supports external purchases:

xml

<key>SKExternalPurchase</key>
<array>
  <!-- South Korea -->
  <string>kr</string>

  <!-- Netherlands -->
  <string>nl</string>

  <!-- EU Countries (examples) -->
  <string>de</string>  <!-- Germany -->
  <string>fr</string>  <!-- France -->
  <string>it</string>  <!-- Italy -->
  <string>es</string>  <!-- Spain -->
  <!-- Add other EU country codes as needed -->
</array>

<!-- Entitlement required -->
<!-- com.apple.developer.storekit.external-purchase: true -->

2. SKExternalPurchaseLink (Optional - iOS 15.4+)

Provide destination URLs for each country. Required if using com.apple.developer.storekit.external-purchase-link entitlement:

xml

<key>SKExternalPurchaseLink</key>
<dict>
  <key>nl</key>
  <string>https://your-site.com/checkout</string>

  <key>de</key>
  <string>https://your-site.com/de/checkout</string>

  <key>kr</key>
  <string>https://your-site.com/kr/checkout</string>
</dict>

3. SKExternalPurchaseMultiLink (iOS 17.5+)

Provide multiple URLs (up to 5) for each country. Use this instead of SKExternalPurchaseLink for iOS 17.5+:

xml

<key>SKExternalPurchaseMultiLink</key>
<dict>
  <key>es</key>
  <array>
    <string>https://your-site.com/es1</string>
    <string>https://your-site.com/new-user-es</string>
    <string>https://your-site.com/seasonal-sale-es</string>
  </array>

  <key>fr</key>
  <array>
    <string>https://your-site.com/fr</string>
    <string>https://your-site.com/global-sale</string>
  </array>

  <key>it</key>
  <array>
    <string>https://your-site.com/global-sale</string>
  </array>
</dict>

4. SKExternalPurchaseCustomLinkRegions (iOS 18.1+)

For custom links to communicate and promote offers. Required if using com.apple.developer.storekit.external-purchase-link entitlement and ExternalPurchaseCustomLink API:

xml

<key>SKExternalPurchaseCustomLinkRegions</key>
<array>
  <string>de</string>  <!-- Germany -->
  <string>fr</string>  <!-- France -->
  <string>nl</string>  <!-- Netherlands -->
  <!-- Add other EU country codes -->
</array>

5. SKExternalPurchaseLinkStreamingRegions (iOS 18.2+)

For music streaming apps only. Required if using com.apple.developer.storekit.external-purchase-link-streaming entitlement:

xml

<key>SKExternalPurchaseLinkStreamingRegions</key>
<array>
  <string>at</string>  <!-- Austria -->
  <string>de</string>  <!-- Germany -->
  <string>fr</string>  <!-- France -->
  <string>nl</string>  <!-- Netherlands -->
  <string>is</string>  <!-- Iceland -->
  <string>no</string>  <!-- Norway -->
  <!-- Add other EU country codes -->
</array>

Common Issues (iOS)

Issue	Cause	Solution
Notice Sheet Not Showing	Missing entitlement or country code	Add `com.apple.developer.storekit.external-purchase` entitlement and configure `SKExternalPurchase` array
canPresent Returns False	Device region not supported	Check device is in supported country (EU, NL, KR)
FeatureNotSupported Error	iOS version too old	Requires iOS 17.4+ (notice sheet), iOS 18.1+ (custom links)

Android example

Billing Programs API (8.2.1+)

Google Play Billing Library 8.2.0 introduced the Billing Programs API, which replaces the legacy alternative billing APIs. Use 8.2.1 or later for its availability, reporting-details, and external-link fixes.

Program Types

ExternalContentLink - For apps that link to external content (e.g., reader apps, music streaming)
ExternalOffer - For apps offering alternative payment options

Kotlin example

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

// Initialize store
val iapStore = OpenIapStore(context = applicationContext)

check(iapStore.initConnection(
    InitConnectionConfig(
        enableBillingProgramAndroid = BillingProgramAndroid.ExternalOffer
    )
)) { "Store connection failed" }

// External Offer flow with Billing Programs API (8.2.1+)
suspend fun handleExternalPurchaseWithBillingPrograms(productId: String) {
    try {
        // Step 1: Check if billing program is available
        val result = iapStore.isBillingProgramAvailable(BillingProgramAndroid.ExternalOffer)
        if (!result.isAvailable) {
            Log.e("IAP", "External offer program not available")
            return
        }

        // Step 2: Create reporting details immediately before redirecting.
        val reportingDetails = iapStore.createBillingProgramReportingDetails(
            BillingProgramAndroid.ExternalOffer
        )

        // Step 3: Let Google Play disclose and launch the external destination.
        val launched = iapStore.launchExternalLink(
            activity,
            LaunchExternalLinkParamsAndroid(
                billingProgram = BillingProgramAndroid.ExternalOffer,
                launchMode = ExternalLinkLaunchModeAndroid.LaunchInExternalBrowserOrApp,
                linkType = ExternalLinkTypeAndroid.LinkToDigitalContentOffer,
                linkUri = "https://your-payment-site.com/checkout"
            )
        )

        if (!launched) {
            Log.e("IAP", "Failed to launch external link")
            return
        }

        // Step 4: launch=true is not purchase completion. Wait for a verified
        // checkout return/deep-link/backend confirmation before reporting.
        val checkout = yourBackend.waitForVerifiedCheckoutCompletion(productId)
        if (!checkout.success) return

        // Report the external transaction from your backend within 24 hours.
        yourBackend.reportExternalTransaction(
            externalTransactionToken = reportingDetails.externalTransactionToken,
            productId = productId
        )

        Log.d("IAP", "Purchase completed!")
    } catch (e: Exception) {
        Log.e("IAP", "Purchase error: ${e.message}")
    }
}

TypeScript example

import {
  initConnection,
  isBillingProgramAvailableAndroid,
  createBillingProgramReportingDetailsAndroid,
  launchExternalLinkAndroid,
} from 'expo-iap';

// Step 0: Enable billing program BEFORE initConnection
const connected = await initConnection({ enableBillingProgramAndroid: 'external-offer' });
if (!connected) throw new Error('Store connection failed');

// External Offer flow with Billing Programs API (8.2.1+)
async function handleExternalPurchaseWithBillingPrograms(productId: string) {
  try {
    // Step 1: Check if billing program is available
    const result = await isBillingProgramAvailableAndroid('external-offer');
    if (!result.isAvailable) {
      console.log('External offer program not available');
      return;
    }

    // Step 2: Create reporting details immediately before redirecting.
    const reportingDetails =
      await createBillingProgramReportingDetailsAndroid('external-offer');

    // Step 3: Let Google Play disclose and launch the external destination.
    const launched = await launchExternalLinkAndroid({
      billingProgram: 'external-offer',
      launchMode: 'launch-in-external-browser-or-app',
      linkType: 'link-to-digital-content-offer',
      linkUri: 'https://your-payment-site.com/checkout',
    });

    if (!launched) {
      console.log('Failed to launch external link');
      return;
    }

    // Step 4: launch=true is not purchase completion. Wait for a verified
    // checkout return/deep-link/backend confirmation before reporting.
    const checkout = await yourBackend.waitForVerifiedCheckoutCompletion({ productId });
    if (!checkout.success) return;

    // Report the external transaction to Google within 24 hours.
    await yourBackend.reportExternalTransaction({
      externalTransactionToken: reportingDetails.externalTransactionToken,
      productId,
    });

    console.log('Purchase completed!');
  } catch (error) {
    console.error('Purchase error:', error);
  }
}

Dart example

dart

import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';

final connected = await FlutterInappPurchase.instance.initConnection(
  enableBillingProgramAndroid: BillingProgramAndroid.ExternalOffer,
);
if (!connected) throw StateError('Store connection failed');

// External Offer flow with Billing Programs API (8.2.1+)
Future<void> handleExternalPurchaseWithBillingPrograms(String productId) async {
  try {
    // Step 1: Check if billing program is available
    final result = await FlutterInappPurchase.instance
        .isBillingProgramAvailableAndroid(BillingProgramAndroid.ExternalOffer);
    if (!result.isAvailable) {
      print('External offer program not available');
      return;
    }

    // Step 2: Create reporting details immediately before redirecting.
    final reportingDetails = await FlutterInappPurchase.instance
        .createBillingProgramReportingDetailsAndroid(
          program: BillingProgramAndroid.ExternalOffer,
        );

    // Step 3: Let Google Play disclose and launch the external destination.
    final launched = await FlutterInappPurchase.instance.launchExternalLinkAndroid(
      billingProgram: BillingProgramAndroid.ExternalOffer,
      launchMode: ExternalLinkLaunchModeAndroid.LaunchInExternalBrowserOrApp,
      linkType: ExternalLinkTypeAndroid.LinkToDigitalContentOffer,
      linkUri: 'https://your-payment-site.com/checkout',
    );

    if (!launched) {
      print('Failed to launch external link');
      return;
    }

    // Step 4: launch=true is not purchase completion. Wait for a verified
    // checkout return/deep-link/backend confirmation before reporting.
    final checkout = await yourBackend.waitForVerifiedCheckoutCompletion(productId);
    if (!checkout.success) return;

    // Report the external transaction from your backend within 24 hours.
    await yourBackend.reportExternalTransaction(
      externalTransactionToken: reportingDetails.externalTransactionToken,
      productId: productId,
    );

    print('Purchase completed!');
  } catch (e) {
    print('Purchase error: $e');
  }
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

var mutate = (MutationResolver)OpenIapClient.Instance;
var connected = await mutate.InitConnectionAsync(new InitConnectionConfig
{
    EnableBillingProgramAndroid = BillingProgramAndroid.ExternalOffer,
});
if (!connected) throw new InvalidOperationException("Store connection failed");

async Task HandleExternalPurchaseWithBillingProgramsAsync(string productId)
{
    // Step 1: Check program availability.
    var availability = await mutate.IsBillingProgramAvailableAndroidAsync(
        BillingProgramAndroid.ExternalOffer);
    if (!availability.IsAvailable) return;

    // Step 2: Create reporting details immediately before redirecting.
    var reportingDetails = await mutate.CreateBillingProgramReportingDetailsAndroidAsync(
        BillingProgramAndroid.ExternalOffer);

    // Step 3: Let Google Play disclose and launch the external destination.
    var launched = await mutate.LaunchExternalLinkAndroidAsync(
        new LaunchExternalLinkParamsAndroid
        {
            BillingProgram = BillingProgramAndroid.ExternalOffer,
            LaunchMode = ExternalLinkLaunchModeAndroid.LaunchInExternalBrowserOrApp,
            LinkType = ExternalLinkTypeAndroid.LinkToDigitalContentOffer,
            LinkUri = "https://your-payment-site.com/checkout",
        });
    if (!launched) return;

    // Step 4: launch=true is not purchase completion. Wait for a verified
    // checkout return/deep-link/backend confirmation before reporting.
    var checkout = await YourBackend.WaitForVerifiedCheckoutCompletionAsync(productId);
    if (!checkout.Success) return;

    // Report from your backend to Google within 24 hours.
    await YourBackend.ReportExternalTransactionAsync(
        reportingDetails.ExternalTransactionToken,
        productId);
}

Kotlin (KMP) example

import io.github.hyochan.kmpiap.KmpIAP
import io.github.hyochan.kmpiap.openiap.*

// Initialize store
val kmpIAP = KmpIAP()

check(kmpIAP.initConnection(
    InitConnectionConfig(
        enableBillingProgramAndroid = BillingProgramAndroid.ExternalOffer
    )
)) { "Store connection failed" }

// External Offer flow with Billing Programs API (8.2.1+)
suspend fun handleExternalPurchaseWithBillingPrograms(productId: String) {
    try {
        // Step 1: Check if billing program is available
        val result = kmpIAP.isBillingProgramAvailableAndroid(BillingProgramAndroid.ExternalOffer)
        if (!result.isAvailable) {
            Log.e("IAP", "External offer program not available")
            return
        }

        // Step 2: Create reporting details immediately before redirecting.
        val reportingDetails = kmpIAP.createBillingProgramReportingDetailsAndroid(
            BillingProgramAndroid.ExternalOffer
        )

        // Step 3: Let Google Play disclose and launch the external destination.
        val launched = kmpIAP.launchExternalLinkAndroid(
            LaunchExternalLinkParamsAndroid(
                billingProgram = BillingProgramAndroid.ExternalOffer,
                launchMode = ExternalLinkLaunchModeAndroid.LaunchInExternalBrowserOrApp,
                linkType = ExternalLinkTypeAndroid.LinkToDigitalContentOffer,
                linkUri = "https://your-payment-site.com/checkout"
            )
        )

        if (!launched) {
            Log.e("IAP", "Failed to launch external link")
            return
        }

        // Step 4: launch=true is not purchase completion. Wait for a verified
        // checkout return/deep-link/backend confirmation before reporting.
        val checkout = yourBackend.waitForVerifiedCheckoutCompletion(productId)
        if (!checkout.success) return

        // Report the external transaction from your backend within 24 hours.
        yourBackend.reportExternalTransaction(
            externalTransactionToken = reportingDetails.externalTransactionToken,
            productId = productId
        )

        Log.d("IAP", "Purchase completed!")
    } catch (e: Exception) {
        Log.e("IAP", "Purchase error: ${e.message}")
    }
}

GDScript example

# Enable the program while constructing the BillingClient.
func _ready() -> void:
    var config = InitConnectionConfig.new()
    config.enable_billing_program_android = BillingProgramAndroid.EXTERNAL_OFFER
    var connected = await iap.init_connection(config)
    if not connected:
        push_error("Store connection failed")
        return

# External Offer flow with Billing Programs API (8.2.1+)
func handle_external_purchase_with_billing_programs(product_id: String) -> void:
    # Step 1: Check if billing program is available
    var result = await iap.is_billing_program_available_android(
        BillingProgramAndroid.EXTERNAL_OFFER
    )
    if not result.is_available:
        print("External offer program not available")
        return

    # Step 2: Create reporting details immediately before redirecting.
    var reporting_details = await iap.create_billing_program_reporting_details_android(
        BillingProgramAndroid.EXTERNAL_OFFER
    )

    # Step 3: Let Google Play disclose and launch the external destination.
    var params = LaunchExternalLinkParamsAndroid.new()
    params.billing_program = BillingProgramAndroid.EXTERNAL_OFFER
    params.launch_mode = ExternalLinkLaunchModeAndroid.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
    params.link_type = ExternalLinkTypeAndroid.LINK_TO_DIGITAL_CONTENT_OFFER
    params.link_uri = "https://your-payment-site.com/checkout"

    var launched = await iap.launch_external_link_android(params)

    if not launched:
        print("Failed to launch external link")
        return

    # Step 4: launch=true is not purchase completion. Wait for a verified
    # checkout return/deep-link/backend confirmation before reporting.
    var checkout = await your_backend.wait_for_verified_checkout_completion(product_id)
    if not checkout.success:
        return

    # Report from your backend to Google within 24 hours.
    if reporting_details and reporting_details.external_transaction_token:
        await your_backend.report_external_transaction(
            reporting_details.external_transaction_token,
            product_id
        )

        print("Purchase completed!")

External Payments (8.3.0+ - Japan Only)

Google Play Billing Library 8.3.0 introduces the External Payments program, currently available only in Japan. This presents a side-by-side choice between Google Play Billing and the developer's external payment option directly in the purchase flow.

Key Differences from Other Programs

Side-by-side choice: User sees both Google Play and developer payment options in the same purchase dialog
DeveloperProvidedBillingListener: New callback when user selects developer billing (different from UserChoiceBillingListener)
DeveloperBillingOptionParams: Configure the developer billing option in BillingFlowParams
EnableBillingProgramParams: Required to enable EXTERNAL_PAYMENTS with DeveloperProvidedBillingListener

Kotlin example

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

// Initialize store
val iapStore = OpenIapStore(context = applicationContext)

check(iapStore.initConnection(
    InitConnectionConfig(
        enableBillingProgramAndroid = BillingProgramAndroid.ExternalPayments
    )
)) { "Store connection failed" }

// Step 1: Set up listener for when user selects developer billing
iapStore.addDeveloperProvidedBillingListener { details ->
    Log.d("IAP", "User selected developer billing")
    Log.d("IAP", "External transaction token received; send it to your backend without logging it.")

    // Step 2: Process payment with your backend
    lifecycleScope.launch {
        try {
            val paymentResult = yourBackend.createPayment(
                productId = currentProductId,
                userId = userId,
                amount = productPrice
            )

            if (paymentResult.success) {
                // Step 3: Report the external transaction token to Google
                // This must be done within 24 hours
                yourBackend.reportExternalTransaction(
                    token = details.externalTransactionToken,
                    orderId = paymentResult.orderId,
                    productId = currentProductId
                )

                Log.d("IAP", "External payment completed and reported!")
            }
        } catch (e: Exception) {
            Log.e("IAP", "External payment error: ${e.message}")
        }
    }
}

// Purchase flow with External Payments
suspend fun handlePurchaseWithExternalPayments(productId: String) {
    try {
        // Check if External Payments is available (Japan only)
        val result = iapStore.isBillingProgramAvailable(
            BillingProgramAndroid.ExternalPayments
        )
        if (!result.isAvailable) {
            Log.w("IAP", "External Payments not available (not in Japan)")
            // Fall back to standard Google Play purchase
            return
        }

        iapStore.setActivity(activity)

        // Launch purchase with developer billing option
        // User will see side-by-side choice dialog
        val props = RequestPurchaseProps(
            request = RequestPurchaseProps.Request.Purchase(
                RequestPurchasePropsByPlatforms(
                    google = RequestPurchaseAndroidProps(
                        skus = listOf(productId),
                        developerBillingOption = DeveloperBillingOptionParamsAndroid(
                            billingProgram = BillingProgramAndroid.ExternalPayments,
                            linkUri = "https://your-payment-site.com/checkout",
                            launchMode = DeveloperBillingLaunchModeAndroid.LaunchInExternalBrowserOrApp
                        )
                    )
                )
            ),
            type = ProductQueryType.InApp
        )

        iapStore.requestPurchase(props)

        // If user selects Google Play → onPurchaseSuccess callback
        // If user selects developer billing → DeveloperProvidedBillingListener callback
    } catch (e: Exception) {
        Log.e("IAP", "Purchase error: ${e.message}")
    }
}

TypeScript example

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

const connected = await initConnection({ enableBillingProgramAndroid: 'external-payments' });
if (!connected) throw new Error('Store connection failed');

// Step 1: Set up listener for when user selects developer billing
async function handleDeveloperBilling(details: DeveloperProvidedBillingDetailsAndroid) {
    console.log('User selected developer billing');
    console.log('External transaction token received; send it to your backend without logging it.');

    try {
      // Step 2: Process payment with your backend
      const paymentResult = await yourBackend.createPayment({
        productId: currentProductId,
        userId,
        amount: productPrice,
      });

      if (paymentResult.success) {
        // Step 3: Report the external transaction token to Google
        // This must be done within 24 hours
        await yourBackend.reportExternalTransaction({
          token: details.externalTransactionToken,
          orderId: paymentResult.orderId,
          productId: currentProductId,
        });

        console.log('External payment completed and reported!');
      }
    } catch (error) {
      console.error('External payment error:', error);
    }
}

const developerBillingSubscription = developerProvidedBillingListenerAndroid(
  (details) => {
    void handleDeveloperBilling(details);
  }
);

// Purchase flow with External Payments
async function handlePurchaseWithExternalPayments(productId: string) {
  try {
    // Check if External Payments is available (Japan only)
    const result = await isBillingProgramAvailableAndroid('external-payments');
    if (!result.isAvailable) {
      console.log('External Payments not available (not in Japan)');
      // Fall back to standard Google Play purchase
      return;
    }

    // Launch purchase with developer billing option
    // User will see side-by-side choice dialog
    await requestPurchase({
      request: {
        google: {
          skus: [productId],
          developerBillingOption: {
            billingProgram: 'external-payments',
            linkUri: 'https://your-payment-site.com/checkout',
            launchMode: 'launch-in-external-browser-or-app',
          },
        },
      },
      type: 'in-app',
    });

    // If user selects Google Play → purchaseUpdatedListener callback
    // If user selects developer billing → developerProvidedBillingListenerAndroid callback
  } catch (error) {
    console.error('Purchase error:', error);
  }
}

// Clean up when done
// developerBillingSubscription.remove();

Dart example

dart

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

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

// Step 1: Set up listener for when user selects developer billing
Future<void> handleDeveloperBilling(DeveloperProvidedBillingDetailsAndroid details) async {
  print('User selected developer billing');
  print('External transaction token received; send it to your backend without logging it.');

  try {
    // Step 2: Process payment with your backend
    final paymentResult = await yourBackend.createPayment(
      productId: currentProductId,
      userId: userId,
      amount: productPrice,
    );

    if (paymentResult.success) {
      // Step 3: Report the external transaction token to Google
      // This must be done within 24 hours
      await yourBackend.reportExternalTransaction(
        token: details.externalTransactionToken,
        orderId: paymentResult.orderId,
        productId: currentProductId,
      );

      print('External payment completed and reported!');
    }
  } catch (e) {
    print('External payment error: $e');
  }
}

FlutterInappPurchase.instance.developerProvidedBillingAndroid.listen((details) {
  unawaited(handleDeveloperBilling(details));
});

// Purchase flow with External Payments
Future<void> handlePurchaseWithExternalPayments(String productId) async {
  try {
    // Check if External Payments is available (Japan only)
    final result = await FlutterInappPurchase.instance
        .isBillingProgramAvailableAndroid(BillingProgramAndroid.ExternalPayments);
    if (!result.isAvailable) {
      print('External Payments not available (not in Japan)');
      // Fall back to standard Google Play purchase
      return;
    }

    // Launch purchase with developer billing option
    // User will see side-by-side choice dialog
    await FlutterInappPurchase.instance.requestPurchase(
      RequestPurchaseProps.inApp((
        apple: null,
        google: RequestPurchaseAndroidProps(
          skus: [productId],
          developerBillingOption: DeveloperBillingOptionParamsAndroid(
            billingProgram: BillingProgramAndroid.ExternalPayments,
            linkUri: 'https://your-payment-site.com/checkout',
            launchMode: DeveloperBillingLaunchModeAndroid.LaunchInExternalBrowserOrApp,
          ),
        ),
      )),
    );

    // If user selects Google Play → purchaseUpdatedListener callback
    // If user selects developer billing → developerProvidedBillingAndroid callback
  } catch (e) {
    print('Purchase error: $e');
  }
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

var iap = OpenIapClient.Instance;
var mutate = (MutationResolver)iap;

async Task HandleDeveloperBillingSafelyAsync(DeveloperProvidedBillingDetailsAndroid details)
{
    try
    {
        await YourBackend.HandleDeveloperBillingAsync(details);
    }
    catch (Exception error)
    {
        System.Diagnostics.Debug.WriteLine(quot;Developer billing error: {error.Message}");
    }
}

using var developerBillingSubscription = iap.DeveloperProvidedBillingAndroid.Subscribe(
    details => _ = HandleDeveloperBillingSafelyAsync(details));

var connected = await mutate.InitConnectionAsync(new InitConnectionConfig
{
    EnableBillingProgramAndroid = BillingProgramAndroid.ExternalPayments,
});
if (!connected) throw new InvalidOperationException("Store connection failed");

var availability = await mutate.IsBillingProgramAvailableAndroidAsync(
    BillingProgramAndroid.ExternalPayments);
if (availability.IsAvailable)
{
    await mutate.RequestPurchaseAsync(new RequestPurchaseProps
    {
        RequestPurchase = new RequestPurchasePropsByPlatforms
        {
            Google = new RequestPurchaseAndroidProps
            {
                Skus = new[] { "premium" },
                DeveloperBillingOption = new DeveloperBillingOptionParamsAndroid
                {
                    BillingProgram = BillingProgramAndroid.ExternalPayments,
                    LinkUri = "https://your-payment-site.com/checkout",
                    LaunchMode = DeveloperBillingLaunchModeAndroid.LaunchInExternalBrowserOrApp,
                },
            },
        },
        Type = ProductQueryType.InApp,
    });
}

Kotlin (KMP) example

import io.github.hyochan.kmpiap.KmpIAP
import io.github.hyochan.kmpiap.openiap.*

val kmpIAP = KmpIAP()

scope.launch {
    try {
        val details = kmpIAP.developerProvidedBillingAndroid()
        yourBackend.handleDeveloperBilling(details)
    } catch (e: Exception) {
        Log.e("IAP", "Developer billing error: ${e.message}")
    }
}

check(kmpIAP.initConnection(
    InitConnectionConfig(
        enableBillingProgramAndroid = BillingProgramAndroid.ExternalPayments
    )
)) { "Store connection failed" }

suspend fun handlePurchaseWithExternalPayments(productId: String) {
    val availability = kmpIAP.isBillingProgramAvailableAndroid(
        BillingProgramAndroid.ExternalPayments
    )
    if (!availability.isAvailable) return

    kmpIAP.requestPurchase(
        RequestPurchaseProps(
            request = RequestPurchaseProps.Request.Purchase(
                RequestPurchasePropsByPlatforms(
                    google = RequestPurchaseAndroidProps(
                        skus = listOf(productId),
                        developerBillingOption = DeveloperBillingOptionParamsAndroid(
                            billingProgram = BillingProgramAndroid.ExternalPayments,
                            linkUri = "https://your-payment-site.com/checkout",
                            launchMode = DeveloperBillingLaunchModeAndroid.LaunchInExternalBrowserOrApp
                        )
                    )
                )
            ),
            type = ProductQueryType.InApp
        )
    )
}

GDScript example

# Enable External Payments while constructing the BillingClient.
func _ready() -> void:
    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

    # Step 1: Set up listener for when user selects developer billing
    iap.developer_provided_billing_android.connect(_on_developer_provided_billing)
    iap.purchase_updated.connect(_on_purchase_updated)

func _on_developer_provided_billing(details: DeveloperProvidedBillingDetailsAndroid) -> void:
    print("User selected developer billing")
    print("External transaction token received; send it to your backend without logging it.")

    # Step 2: Process payment with your backend
    var payment_result = await your_backend.create_payment(
        current_product_id,
        user_id,
        product_price
    )

    if payment_result.success:
        # Step 3: Report the external transaction token to Google
        # This must be done within 24 hours
        await your_backend.report_external_transaction(
            details.external_transaction_token,
            payment_result.order_id,
            current_product_id
        )
        print("External payment completed and reported!")

# Purchase flow with External Payments
func handle_purchase_with_external_payments(product_id: String) -> void:
    # Check if External Payments is available (Japan only)
    var result = await iap.is_billing_program_available_android(
        BillingProgramAndroid.EXTERNAL_PAYMENTS
    )
    if not result.is_available:
        print("External Payments not available (not in Japan)")
        # Fall back to standard Google Play purchase
        return

    # Launch purchase with developer billing option
    # User will see side-by-side choice dialog
    var props = RequestPurchaseProps.new()
    props.request = RequestPurchasePropsByPlatforms.new()
    props.request.google = RequestPurchaseAndroidProps.new()
    props.request.google.skus = [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-payment-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)

    # If user selects Google Play -> purchase_updated signal
    # If user selects developer billing -> developer_provided_billing_android signal

External Payments Flow Diagram

Step	API / Action	Description
0	`initConnection(enableBillingProgramAndroid)`	Enable External Payments program BEFORE initConnection
1	`addDeveloperProvidedBillingListener()`	Register callback for when user selects developer billing
2	`isBillingProgramAvailable(EXTERNAL_PAYMENTS)`	Check if available (Japan only)
3	`requestPurchase(developerBillingOption: ...)`	Launch purchase with developer billing option configured
4	User Choice Dialog	User sees side-by-side choice: Google Play or Developer Billing
5a	If Google Play: `onPurchaseSuccess`	Normal Google Play purchase flow
5b	If Developer: `DeveloperProvidedBillingListener`	Callback receives externalTransactionToken
6	Process Payment	Process payment with your payment gateway
7	Report Token	Report externalTransactionToken to Google within 24 hours

DeveloperBillingLaunchMode Options

Mode	Behavior
`LAUNCH_IN_EXTERNAL_BROWSER_OR_APP`	Google Play will launch the linkUri in an external browser or eligible app. Use this for web-based payment flows.
`CALLER_WILL_LAUNCH_LINK`	Google Play returns control to your app without launching. Your app handles launching the payment flow. Use this for in-app payment experiences.

Requirements

Google Play Billing 6.2+ - For alternative billing only mode (legacy)
Google Play Billing 7.0+ - For user choice mode
Google Play Billing 8.2.0+ - For External Content Links; 8.2.1+ for External Offers
Play Console Setup - Configure alternative billing in console
Token Reporting - Must report token within 24 hours

Configuration

Kotlin example

val iapStore = OpenIapStore(applicationContext)

val connected = iapStore.initConnection(
    InitConnectionConfig(
        enableBillingProgramAndroid = BillingProgramAndroid.ExternalOffer
        // or BillingProgramAndroid.UserChoiceBilling
    )
)
check(connected) { "Store connection failed" }

TypeScript example

import { initConnection } from 'expo-iap';

// Choose one program for this connection.
const billingProgram = 'external-offer'; // Or 'user-choice-billing'
const connected = await initConnection({
  enableBillingProgramAndroid: billingProgram,
});
if (!connected) throw new Error('Store connection failed');

Dart example

dart

import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';

// Choose ExternalOffer or UserChoiceBilling for this connection.
final connected = await FlutterInappPurchase.instance.initConnection(
  enableBillingProgramAndroid: BillingProgramAndroid.ExternalOffer,
);
if (!connected) throw StateError('Store connection failed');

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;

var connected = await ((MutationResolver)OpenIapClient.Instance).InitConnectionAsync(
    new InitConnectionConfig
    {
        EnableBillingProgramAndroid = BillingProgramAndroid.ExternalOffer,
        // or BillingProgramAndroid.UserChoiceBilling
    });
if (!connected) throw new InvalidOperationException("Store connection failed");

Kotlin (KMP) example

val kmpIAP = KmpIAP()

val connected = kmpIAP.initConnection(
    InitConnectionConfig(
        enableBillingProgramAndroid = BillingProgramAndroid.ExternalOffer
        // or BillingProgramAndroid.UserChoiceBilling
    )
)
check(connected) { "Store connection failed" }

GDScript example

# External Offer (recommended)
func _ready_external_offer() -> void:
    var config = InitConnectionConfig.new()
    config.enable_billing_program_android = BillingProgramAndroid.EXTERNAL_OFFER
    var success = await iap.init_connection(config)
    if not success:
        push_error("Store connection failed")

# Or User Choice mode
func _ready_user_choice() -> void:
    var config = InitConnectionConfig.new()
    config.enable_billing_program_android = BillingProgramAndroid.USER_CHOICE_BILLING
    var success = await iap.init_connection(config)
    if not success:
        push_error("Store connection failed")

Common Issues (Android)

Issue	Cause	Solution
Not Available Error	Not configured in Play Console	Enable alternative billing in console
Token Creation Failed	Invalid product ID or state	Verify product ID and payment status
User Choice Not Showing	Wrong billing library version	Update to Billing Library 7.0+

Testing (Android)

Configure alternative billing in Google Play Console
Use internal testing track for testing
Test with licensed test accounts
Verify token generation and reporting

Implementation Flow#

The complete external purchase flow involves coordination between your app, external website, and backend. The flow differs between iOS and Android:

iOS Flow (iOS 17.4+)

Step	API / Action	Description
1	`canPresentExternalPurchaseNoticeIOS()`	Check if device supports external purchase notice sheet
2	`presentExternalPurchaseNoticeSheetIOS()`	Show Apple's notice sheet informing user about external purchase
3	User Action	User taps "Continue" or dismisses the notice sheet
4	`presentExternalPurchaseLinkIOS(url)`	If user continued, present external purchase link (user acknowledges external purchase)
5	Backend Payment Processing	App calls backend API to process payment with payment gateway (Stripe, PayPal, etc.) and grant entitlements
6	Unlock Content	App unlocks purchased content after backend confirmation

Android example

Billing Programs API (8.2.1+ recommended)

Step	API / Action	Description
0	`enableBillingProgram(program)`	Enable billing program BEFORE initConnection
1	`isBillingProgramAvailable(program)`	Check if billing program is available for this user
2	`launchExternalLink(activity, params)`	Launch external link (browser or app) with configured params
3	Backend API Call	Call backend API to process payment with payment gateway (Stripe, PayPal, etc.)
4	`createBillingProgramReportingDetails(program)`	After successful payment, create reporting details with token
5	Token Reporting	Send externalTransactionToken to Google Play backend within 24 hours
6	Unlock Content	Backend grants entitlements and app unlocks content

Complete Examples#

For complete, production-ready examples with full UI implementation, please refer to the native example apps:

iOS (SwiftUI)

AlternativeBillingScreen.swift - Complete implementation with notice sheet and external purchase link presentation

This example demonstrates:

Complete UI implementation with state management
Notice sheet presentation (iOS 17.4+)
Deep link handling and verification flow
Error handling and user feedback
Production-ready code patterns

Android example

Android (Jetpack Compose)

AlternativeBillingScreen.kt - Complete Android implementation with External Offer and Billing Choice programs

This example demonstrates:

Complete UI implementation with state management
Program switching (External Offer / Billing Choice)
Token generation and reporting
Deep link handling and verification flow
Error handling and user feedback
Production-ready code patterns

External Purchase Types - Type definitions and parameters
Onside Store Setup - alternative marketplace flow for expo-iap
Alternative Billing Types - Type definitions and config
Request Purchase API - API reference for requestPurchase
Error Codes - Error handling reference

Native References#

Apple · StoreKit External Purchase entitlement
Apple · StoreKit ExternalPurchase — notice sheet and link APIs
Google · User Choice Billing
Google · Alternative billing in Play Billing Library
Google · Play Billing 8.3.0 — External Payments (Japan)

External Purchase

Overview

Platform Support

Common Requirements#

Backend Verification System

Platform-Specific Implementation#

iOS - External Purchase

Basic Usage

Requirements

Configuration (iOS)

1. SKExternalPurchase (Required)

2. SKExternalPurchaseLink (Optional - iOS 15.4+)

3. SKExternalPurchaseMultiLink (iOS 17.5+)

4. SKExternalPurchaseCustomLinkRegions (iOS 18.1+)

5. SKExternalPurchaseLinkStreamingRegions (iOS 18.2+)

Common Issues (iOS)

Implementation Flow#

iOS Flow (iOS 17.4+)

Complete Examples#

iOS (SwiftUI)

Related Documentation#

Native References#