Android Setup Guide

Setting up in-app purchases for Android requires configuration in Google Play Console and your Android project. Building for another Android-compatible store? See Store Setup for Horizon OS, Fire OS, Vega OS, and alternative marketplace targets.

Prerequisites#

Before you can implement and test in-app purchases on Android, you must complete these essential steps:

1. Google Play Developer Account#

  • Register for a Google Play Developer account ($25 one-time fee)
  • Complete identity verification
  • Accept all developer agreements
  • Set up payment profile in Google Play Console

2. Merchant Account Setup#

  • Navigate to Setup → Payments profile
  • Link a Google Payments Merchant account
  • Complete tax information
  • Verify banking details
  • Important: Products won't work without a verified merchant account

Google Play Console Configuration#

1. Create Your App#

  • Sign in to Google Play Console
  • Click "Create app"
  • Fill in app details (name, default language, app/game category)
  • Select free or paid app
  • Accept the Developer Program Policies

2. Upload Your App#

You must upload at least one APK/AAB to create in-app products:

  • Go to Release → Testing → Internal testing
  • Create a new release
  • Upload your signed APK or App Bundle
  • Save and review the release
  • Roll out to internal testing

3. Create In-App Products#

  • Navigate to Monetization → In-app products
  • Click "Create product"
  • Choose your product type:
    • Managed Products: One-time purchases or consumables
    • Subscriptions: Recurring subscriptions (requires separate setup)

4. Configure Product Details#

For each product, provide:

  • Product ID: Unique identifier (e.g., premium_upgrade, coins_100)
  • Name: Display name for users
  • Description: Product description
  • Price: Set price for each country/region
  • Set product status to Active

5. Configure Subscriptions (if applicable)#

  • Navigate to Monetization → Subscriptions
  • Create subscription with base plans and offers
  • Configure billing period (weekly, monthly, yearly, etc.)
  • Set up free trials or introductory pricing if desired
  • Add subscription benefits for user display

Android Project Configuration#

1. Minimum SDK Requirements#

The OpenIAP Android core library (openiap-google) requires minSdk 23 (Android 6.0) with Google Play Billing 9.1.0. Each framework library may require a higher minimum — check the framework-specific setup page for the exact value.

2. Add Billing Permission#

In your AndroidManifest.xml:

<uses-permission android:name="com.android.vending.BILLING" />
<uses-permission android:name="android.permission.INTERNET" />

3. Update build.gradle#

Add the OpenIAP Android dependency:

// build.gradle.kts
dependencies {
    implementation("io.github.hyochan.openiap:openiap-google:3.5.1")
}

// Or build.gradle (Groovy)
dependencies {
    implementation 'io.github.hyochan.openiap:openiap-google:3.5.1'
}

Check the latest version at Maven Central.

4. Configure ProGuard (if using)#

Add to your proguard-rules.pro:

-keep class com.android.billingclient.** { *; }
-keep class com.android.vending.billing.** { *; }

Testing Setup#

1. Set Up License Testing#

  • In Google Play Console, go to Setup → License testing
  • Add tester email addresses (Gmail accounts)
  • Set license response to LICENSED
  • Save changes

2. Create Test Track#

  • Use Internal testing track for fastest updates
  • Add testers by email or Google Groups
  • Share opt-in link with testers
  • Testers must accept the invitation

3. Testing Best Practices#

  • Use the same Google account on the test device as added to license testing
  • Ensure the app is downloaded from Play Store (via test track)
  • Test purchases will show "(Test)" in the purchase dialog
  • Test cards are automatically used - no real charges occur

Integration with OpenIAP Libraries#

To implement in-app purchases on Android, use one of the OpenIAP specification libraries:

These libraries implement the OpenIAP specification and handle Android-specific requirements — refer to each library's documentation for implementation details.

Android-Specific Requirements#

Purchase Acknowledgment#

Android requires acknowledging purchases within 3 days. Unacknowledged purchases are automatically refunded by Google Play. In OpenIAP SDKs the completion order is: verify with a trusted verifier (your backend or IAPKit), grant and persist the entitlement so it survives a restart, then acknowledge through finishTransaction.

Consumable Products#

Consumable products must be consumed before they can be purchased again. This prevents duplicate purchases of items like coins or lives. Consumption is the finishTransaction call with isConsumable: true.

Purchase Verification#

Always verify purchases through a trusted verifier that calls the Google Play Developer API — either your backend or IAPKit — to prevent fraud and ensure purchase validity. See the Purchase Verification guide.

Billing Choice and Billing Programs#

OpenIAP's Android core uses Google Play Billing 9.1.0. Billing Choice is exposed through the Billing Programs API with BillingProgramAndroid.BillingChoice in native Kotlin and 'billing-choice' in TypeScript.

Subscription Management#

Subscriptions require special handling including:

  • Grace periods for payment failures
  • Upgrade/downgrade proration
  • Subscription status verification
  • Renewal notifications

OpenIAP libraries handle these Android-specific requirements automatically. Consult the library documentation for your chosen framework to ensure proper implementation.

Common Issues#

Products Not Loading#

Problem: fetchProducts() returns empty array

Solutions:

Check Prerequisites:#

  • Verify merchant account is set up and verified
  • Ensure app is uploaded to at least internal testing track
  • Confirm products are set to "Active" status
  • Wait 2-24 hours after creating products for propagation

Verify Configuration:#

  • Product IDs match exactly (case-sensitive)
  • App package name matches Play Console
  • Version code in app ≥ version in Play Console
  • App is signed with the same certificate

Purchase Flow Issues#

Problem: "This item is not available" error

Solution:

  • Test on real device (not emulator)
  • Download app from Play Store test track
  • Use test account added to license testing
  • Clear Play Store cache and data

Subscription Issues#

Problem: Subscriptions not appearing

Solution:

  • Query subscriptions separately with type: 'subs'
  • Ensure subscription is fully configured with base plans
  • Check if country/region pricing is set
  • Verify subscription benefits are added

Production Checklist#

  • ✅ Server-side receipt validation implemented
  • ✅ Purchase acknowledgment within 3 days
  • ✅ Proper error handling for all purchase states
  • ✅ Restore purchases functionality
  • ✅ Network error retry logic
  • ✅ Obfuscated user/profile IDs for fraud prevention
  • ✅ Analytics tracking for purchase events
  • ✅ Clear purchase flow UI/UX
  • ✅ Refund handling process
  • ✅ Subscription management UI (if applicable)

Best Practices#

  • Always validate purchases through your backend or IAPKit using the Google Play Developer API
  • Implement exponential backoff for network retries
  • Cache product information locally for offline display
  • Show clear pricing and subscription terms
  • Handle grace periods for subscription billing issues
  • Implement proper subscription upgrade/downgrade flows
  • Test thoroughly with different Google accounts
  • Monitor purchase metrics in Play Console