Release 14.4.12 - Alternative Billing Support
· 5 min read
React Native IAP 14.4.12 introduces comprehensive alternative billing support for both iOS and Android, empowering developers to use external payment systems alongside or instead of App Store and Google Play billing. This enables reduced platform fees and greater flexibility in monetization strategies while maintaining compliance with platform policies.
🚀 What's New
Alternative Billing APIs
This release adds full alternative billing functionality for both platforms:
Android
- Alternative Billing Only Mode: Exclusive use of your payment system
- User Choice Billing Mode: Users choose between Google Play and your payment system
- Three-step flow: check availability → show dialog → create reporting token
- Automatic token generation for Google Play reporting (required within 24 hours)
- Reduced service fees (4% reduction when using alternative billing)
iOS
- External Purchase Links: Redirect users to your external website (iOS 16.0+)
- Purchase Notice Sheets: Required disclosure before external redirects (iOS 18.2+)
- Expo config plugin support for automatic entitlement and Info.plist setup
- Support for multiple URLs per country (up to 5 for music streaming apps)
- Custom link regions and streaming-specific configurations
New APIs
Android Alternative Billing
import {
initConnection,
checkAlternativeBillingAvailabilityAndroid,
showAlternativeBillingDialogAndroid,
createAlternativeBillingTokenAndroid,
userChoiceBillingListenerAndroid,
} from 'react-native-iap';
// Initialize with alternative billing mode
await initConnection({
alternativeBillingModeAndroid: 'alternative-only', // or 'user-choice'
});
// 3-step alternative billing flow
const isAvailable = await checkAlternativeBillingAvailabilityAndroid();
const userAccepted = await showAlternativeBillingDialogAndroid();
const token = await createAlternativeBillingTokenAndroid(productId);
// User choice billing event listener
const subscription = userChoiceBillingListenerAndroid((details) => {
console.log('User selected alternative billing');
// Report to backend for Google Play compliance
});
iOS External Purchase
import {
canPresentExternalPurchaseNoticeIOS,
presentExternalPurchaseNoticeSheetIOS,
presentExternalPurchaseLinkIOS,
} from 'react-native-iap';
// Check availability (iOS 18.2+)
const canPresent = await canPresentExternalPurchaseNoticeIOS();
// Present notice sheet before external link
const noticeResult = await presentExternalPurchaseNoticeSheetIOS();
if (noticeResult.result === 'continue') {
// Redirect to external purchase URL
const result = await presentExternalPurchaseLinkIOS(
'https://your-website.com/purchase',
);
}
Expo Config Plugin Enhancement
Automatic iOS alternative billing configuration:
// app.config.ts
export default {
plugins: [
[
'react-native-iap',
{
iosAlternativeBilling: {
// Required: Countries (ISO 3166-1 alpha-2)
countries: ['kr', 'nl', 'de', 'fr'],
// Optional: External URLs per country
links: {
kr: 'https://your-site.com/kr/checkout',
nl: 'https://your-site.com/nl/checkout',
},
// Optional: Multiple URLs (iOS 17.5+, up to 5)
multiLinks: {
de: [
'https://your-site.com/de/checkout',
'https://your-site.com/de/offer',
],
},
// Optional: Custom regions (iOS 18.1+)
customLinkRegions: ['de', 'fr', 'nl'],
// Optional: Streaming regions (iOS 18.2+, music apps)
streamingLinkRegions: ['at', 'de', 'fr', 'nl'],
// Enable entitlements
enableExternalPurchaseLink: true,
enableExternalPurchaseLinkStreaming: false, // music apps only
},
},
],
],
};
The config plugin automatically adds:
- Required entitlements (
com.apple.developer.storekit.external-purchase, etc.) - Info.plist configuration (
SKExternalPurchase,SKExternalPurchaseLink, etc.) - Proper URL validation and country code formatting
useIAP Hook Integration
Alternative billing is fully integrated into the useIAP hook:
import {useIAP} from 'react-native-iap';
const {
checkAlternativeBillingAvailabilityAndroid,
showAlternativeBillingDialogAndroid,
createAlternativeBillingTokenAndroid,
} = useIAP({
// Android alternative billing configuration
alternativeBillingModeAndroid: 'alternative-only',
// User choice billing event handler
onUserChoiceBillingAndroid: (details) => {
console.log('User selected alternative billing');
reportToBackend(details.externalTransactionToken);
},
});
Example App
A complete alternative billing example is now included in the example app:
Features
- Platform-specific flows (iOS external URLs vs. Android billing modes)
- Billing mode switcher for Android (alternative-only vs. user-choice)
- Real-time status updates and result display
- Step-by-step guidance for compliance requirements
- Deep linking recommendations for iOS
Access
Run the example app and navigate to "Alternative Billing" from the home screen.
🔧 Technical Details
Android Implementation
- Uses OpenIAP Google v1.2.12 with native alternative billing support
- Auto-reconnection handling for billing service state
- Proper token creation and reporting flow
- User choice billing listener with event deduplication
iOS Implementation
- Leverages StoreKit External Purchase APIs (iOS 16.0+)
- Support for new notice sheets (iOS 18.2+)
- Proper entitlement management via config plugin
- URL validation and country code handling
Type Safety
All alternative billing APIs are fully typed with TypeScript:
AlternativeBillingModeAndroid:'none'|'alternative-only'|'user-choice'UserChoiceBillingDetails: Product list and external transaction tokenExternalPurchaseNoticeResultIOS: Notice sheet result with actionExternalPurchaseLinkResultIOS: External link presentation result
📖 Documentation
Comprehensive documentation added:
- API Reference: Complete method signatures and examples in Core Methods
- Type Definitions: All alternative billing types in Types
- Expo Plugin Guide: Configuration examples and requirements
- Example App: Working implementation for both platforms
⚠️ Important Notes
Platform Approval Required
Both platforms require special approval to use alternative billing:
- iOS: External purchase entitlement approval from Apple
- Android: Alternative billing approval in Google Play Console
Compliance Requirements
- iOS: URLs must use HTTPS, no query parameters, ≤1,000 characters
- Android: External transaction tokens must be reported within 24 hours
- Fees: Reduced platform fees apply (varies by platform and region)
Supported Regions
- iOS: US, EU, and approved countries (varies by feature)
- Android: South Korea, India, EEA (varies by app type)
📦 Installation
npm install react-native-iap@14.4.12
# or
yarn add react-native-iap@14.4.12
# or
bun add react-native-iap@14.4.12
For Expo projects, run npx expo prebuild after updating your config plugin.
🔗 References
- OpenIAP Alternative Billing: openiap.dev/docs/alternative-billing
- Apple External Purchase: developer.apple.com/storekit/external-purchase
- Google Alternative Billing: developer.android.com/google/play/billing/alternative
- OpenIAP Apple: v1.2.10 with external purchase support
- OpenIAP Google: v1.2.12 with alternative billing APIs
🙏 Acknowledgments
This release builds on the alternative billing implementation from expo-iap, bringing the same powerful features to React Native CLI projects.
Try out alternative billing in 14.4.12 and let us know your feedback via GitHub issues!