In-app Payments

Bilt Payments connects App Store and Google Play purchase options to your app’s benefits: stable entitlement codes such as pro or no_ads. Your app checks those benefits while Bilt verifies store purchases and maintains access on the backend. Open Payments in your project, then use Catalog to choose Apple App Store or Google Play. An Android-only project can connect Google Play without setting up Apple.

​

Before you start

Payments use Bilt’s own Google account. You do not need a Cloud project, API setup or JSON key for payments. Publishing still uses your separate publishing service key. Enable payments checks Bilt’s app and financial access; a successful test purchase confirms order-management access. Read In-app purchase rules before designing the paywall. Bilt’s initial Google scope is monthly and annual auto-renewing subscriptions, plus one-time permanent buy options at quantity one. Consumables, credits, prepaid or installment plans, rentals, preorders, multi-quantity purchases, and offer-only one-time options are outside this scope.

​

Set up Google Play payments

​

Keep the catalog current

The Google Play catalog uses the same product cards and small Edit / Archive buttons as the App Store catalog. Edit opens a dialog to update the displayed translation’s title and description in Google Play. Other translations, prices, availability and existing benefit codes stay unchanged. Use Save checkout selection in that dialog to change a supported subscription offer separately. Archive stops new sales through Bilt while retaining the benefit mapping for existing purchases; Restore makes a supported archived option available again. It does not deactivate the product in Google Play. Refresh after changing Play Console configuration. Missing, draft or inactive options cannot be offered for new purchases. Choose Expand in the setup reminder to view its instructions. They disappear automatically once app access, payments and notification delivery are verified. If notifications are still missing, a compact reminder remains above the catalog. Confirm checkout is available, then ask the chat:

Add a paywall offering the configured Pro monthly and annual Google Play options. Show the selected price and renewal terms, add Restore purchases and Manage subscriptions, and hide exports unless the user has the pro benefit.

Bilt passes exact options and benefit codes to the generator. The app uses @biltme/iap and needs a native build for real purchases. SDK configuration uses platform: 'IOS' or platform: 'Android', the product ID, the Google base-plan or buy-option ID and any selected subscription offer. Render the selected product’s displayPrice and pricingPhases, then call purchaseProduct(product). Checkout refreshes the native price and offer; show changed terms before retrying. Web mocks select their platform explicitly.

​

Google Play access troubleshooting

• Waiting after granting permissions: check the copied Bilt email, exact package and all three app permissions. New grants can take up to 36 hours to become valid, according to RevenueCat’s service-credentials guidance. Choose Check again later; Bilt does not send an email or recheck in the background.
• Permissions were granted at account level: move the grant to this app under App permissions and remove broader account access. The account-wide grant can include other apps; it is not needed for Bilt Payments.
• Access check unavailable: retry later. A temporary Google outage or API quota issue is separate from an app permission grant. Do not create or upload another key.
• Products missing: upload a build with the billing permission, create supported active products in Play Console, then refresh. An empty catalog can still have working app access.
• Products load, but adding or editing is denied: confirm Manage store presence is saved for Bilt’s email on this app. If the app is still marked Draft, also enable Edit and delete draft apps. The read-only Check again result does not confirm product-editing access.
• Purchase seen, acknowledgement pending: confirm Manage orders and subscriptions is saved for Bilt’s email on this app. The read-only access check cannot prove that permission. In Payments → Users, the test purchase should no longer show Acknowledgement pending.

​

Google Play notifications

Google Play can tell Bilt when purchases renew, are cancelled or are refunded. Bilt provides the value to connect these updates; you do not need to request it or create another key. You configure each Play app. Open Payments → Catalog → Google Play and find Notifications in the checklist. Copy the displayed value, then open Play Console → Monetize → Monetization setup:

1. Enable real-time notifications.
2. Paste the copied projects/<project-id>/topics/<topic-id> into Topic name.
3. Select Subscriptions, voided purchases, and all one-time products.
4. Save and send a test notification.
5. Return to Bilt and check again. Waiting for a test notification becomes Notifications verified with the receipt date after Bilt receives it.

Verification is advisory and does not block Enable payments. Bilt also refreshes subscriptions every six hours and near expiry, with hourly permanent-purchase revocation scans. If the topic block is absent, notification setup has not been configured for that Bilt environment; do not invent a topic or enter a webhook URL. Use the production topic for released apps. A separate development topic is for a dedicated test app: switching a released app to it redirects that app’s real purchase notifications. See Google’s notification setup.

What the Bilt operator configures

Bilt provisions its payments account and the receiving topic with an authenticated push subscription to Billing. Creators grant only app-level Play access to the email shown in Payments. Notification delivery permissions stay with Bilt’s infrastructure:

Identity	Permission and scope
google-play-developer-notifications@system.gserviceaccount.com	Pub/Sub Publisher (roles/pubsub.publisher) on the receiving topic
Google’s service-<project-number>@gcp-sa-pubsub.iam.gserviceaccount.com service agent	iam.serviceAccounts.getOpenIdToken on the selected push account; Service Account Token Creator (roles/iam.serviceAccountTokenCreator) supplies it if not already granted
The operator creating or updating the push subscription	iam.serviceAccounts.actAs on the selected push service account

The push account is in the subscription’s Cloud project. Pub/Sub supplies a signed identity token; no JSON key for that account is uploaded to Bilt. Keep the standard wrapped payload and coordinate the exact audience, sender email and full subscription name with Billing’s GOOGLE_RTDN_AUDIENCE, GOOGLE_RTDN_SERVICE_ACCOUNT_EMAIL and GOOGLE_RTDN_SUBSCRIPTION settings.Webapp’s GOOGLE_PLAY_RTDN_TOPIC supplies the full topic shown to creators. Configure the push subscription with 10–600 second exponential retries, seven-day retention and no dead-letter topic; Billing accepts authenticated permanent payload failures and retries transient outages through durable recovery.Scope grants to the topic or push account instead of granting project-wide administration. Bilt verifies the token and envelope before processing a notification. Changing the push account, subscription or audience is supported, but requires a coordinated operator update. See Google’s authenticated push setup.

​

What can change after setup?

The publishing JSON key and Android upload signing key serve different purposes. Keep secure backups of both; payment setup replaces neither. See service-account keys and Play App Signing.

​

Set up App Store payments

Choose Apple App Store and connect the App Store setup. Configure App Store Server Notifications with the URL Bilt provides. Add or sync supported subscription products, then save the catalog and benefit mappings. Apple product authoring remains separate from the Google catalog workflow.

​

Benefits and purchase ownership

Your screens check a stable benefit code, never a product ID. For example, an Apple subscription, a Google monthly plan, and a Google annual plan can all grant pro. A permanent Google option should map to a benefit whose permanent access you intend to honor. Keep the code stable after release. Changing a title or retiring a purchase option must not silently change what an existing customer bought. Retired options remain available for historical verification and support. Purchases belong to an app billing identity. Switching accounts does not transfer them. Passive Google recovery quietly skips another account’s purchase and preserves the owner’s background updates. An explicit Restore purchases action can recover a Google purchase from an anonymous predecessor; authenticated owners must use their original app account, and erased owners stay erased. Apple restore behavior is unchanged.

​

Apps with and without login

Apps without an auth provider can sell purchases anonymously. Bilt’s SDK stores a cryptographically generated billing identity on the installation. Apps with login can also allow purchases before signup; signing in adopts that installation’s anonymous purchases, including when the app restarts with a restored session. Bilt Cloud and Supabase auth configure billing automatically. Other providers can use Payments → Authentication → Custom JWT, with the exact issuer, public HTTPS JWKS URL, and audience from the provider. Tokens must have an asymmetric signature, expiration, and a stable string sub. Supabase projects need asymmetric signing keys. Anonymous only supports apps that do not send auth tokens; Automatic follows the connected backend. The generated app reads the current session through the SDK’s getAccessToken callback and refreshes billing when login or logout changes the session. Auth-free apps omit that callback. Provider configuration belongs on the backend; signing secrets and Google service-account credentials never belong in the app. Once authenticated billing users exist, switching to another issuer requires an explicit billing account migration. Equal user IDs from different providers do not prove the same purchaser. Changing signing keys or audience for the same issuer is supported. Disabling auth preserves the issuer boundary, so it cannot be used to bypass this rule. Reinstalling or clearing storage can lose the installation’s anonymous billing identity. On Google Play, choose Restore purchases using the purchasing Google account to recover from an anonymous predecessor: Bilt merges that anonymous identity into the current one. Opening the app alone never transfers ownership. Purchases already linked to an authenticated app account require that same app account. Linking before storage loss also enables account-based recovery. Test login, logout, cold-start adoption, account switching and explicit restore with your provider before release.

​

Pending payments, renewals, and refunds

A pending Google payment grants no access. Once Play reports a completed purchase, Bilt verifies it, durably records the benefit, and acknowledges it on the server. Google purchase finishing is not an app-side step. For subscriptions, cancellation normally stops future renewal while verified access lasts until expiry. Grace-period access, account hold, pause, expiry, and revocation follow the backend’s verified state. A refunded and revoked permanent purchase loses its purchase-derived benefit; a refund without revocation is a different store action. Notifications and periodic reconciliation help recover missed changes. Resubscribing to an expired subscription from the Play Store is supported. Google supplies the previous purchase’s account evidence, so Bilt associates the new subscription with its existing owner and acknowledges it even before the app opens. See Google’s subscription lifecycle. Promo codes redeemed outside the app may lack evidence of an app billing identity. Bilt leaves those purchases unbound and unacknowledged; Google automatically refunds them after three days. Use an in-app purchase flow when assigning access to an app account. If verification or delivery is delayed, show the current pending or recovery state and allow refresh/restore. Do not unlock from the device callback alone or promise immediate access before the backend confirms it.

​

Test before you ship

Mock previews exercise purchase and entitlement UI without charges. They do not prove native checkout, Play permissions, acknowledgement, or notification delivery. Use a native Play test-track build and a license tester for Android. Test the selected monthly/annual options and permanent purchase, pending approval and cancellation, app restart, restore after reinstall, account switching, renewal and expiry, and refunded/revoked access. Use a native StoreKit test build for Apple. Expo Go cannot load the purchase module. See Google’s testing guide. Check the test purchase separately in Payments → Users. Open the customer’s detail view and confirm the purchase appears, its benefit is active after completion, and Acknowledgement pending clears.

​

Customer support and your responsibilities

The Users tab is available when either store is connected. A customer’s detail view shows benefits, store and order information, pending refresh or acknowledgement state, and test-purchase metadata. Use it to reconcile a reported purchase without handling raw purchase tokens. You remain responsible for developer enrollment, seller agreements, prices, review submissions, and clear paywall disclosures: initial and recurring prices, billing period, trial terms, renewal, cancellation, and terms/privacy links. A native store build and recorded purchase tests are required before release.