How Voidhash works — Voidhash Docs

The parts of Voidhash and what happens on a purchase, an access check, a paywall and an event.

Voidhash sits between your app, the stores and your backend. The SDK in your app talks to the Voidhash API, which validates purchases with the store, keeps access current and tells your backend what changed. You configure it in Studio.

Your app makes the purchase with the store directly (dashed). Voidhash validates it and keeps access current.

Part	What it does
Your app and the SDK	Shows paywalls, makes purchases, checks access and records events, with a publishable key.
Studio	The web dashboard for products, perks, paywalls, experiments, settings and analytics.
Voidhash API	Validates purchases, keeps subscriptions and access current, serves paywalls and stores events.
Payment providers	The App Store, Google Play, Stripe and payment sources. Voidhash never handles payment details.
Your backend	Receives webhooks and calls the API with a secret key, such as to check access.

How the data fits together

Everything below the team belongs to one project.

Each project keeps its own keys, catalog, people and data. Store products map to your products, which unlock perks. A person has one or more distinct IDs. Each purchase grants an entitlement to its product's perks while it stays active. A location shows one paywall's live build or runs an A/B test; see Paywalls in your app. Purchases, entitlements and events are kept per environment, so test purchases never mix with production.

What happens on a purchase

On iOS and Android:

Your app calls the SDK's purchase method, often from a paywall. The SDK starts it with StoreKit or Google Play Billing.
The store charges the person and hands the SDK a transaction.
The SDK reports the App Store transaction ID or Google Play purchase token to Voidhash. Offline, it keeps the report and sends it later.
Voidhash verifies the transaction with the store using your store credentials (Help center). A transaction the store doesn't confirm grants nothing.
Voidhash records the purchase and grants its product's perks. The SDK refreshes the person, so your app sees the new access.
Voidhash records revenue events and sends webhooks such as subscription.created to your backend.

Later changes come from the store: Apple's server notifications (Help center) and Google's real-time developer notifications (RTDN). Renewals, cancellations, billing problems, refunds and expiry update access without the app running. See Subscription lifecycle.

On the web, your server creates the Stripe checkout and Voidhash learns of the sale from Stripe's events. Payment sources report sales from your backend. Steps 5 and 6 are the same for both.

If you already have a purchase system, the SDK can report purchases without making them; see Observer mode.

How access is checked

Your app checks a perk, such as premium, through the SDK. The SDK answers from a snapshot of the person's access on the device. It refreshes the snapshot after purchases, restores and identity changes, and treats it as stale after 5 minutes. A snapshot is kept for up to 2 days, so access survives a short time offline. See People and identity for how the SDK knows who the person is.

Your backend should not trust the app for anything that matters. It asks Voidhash with a secret key, or keeps its own copy of access current from webhooks. The server libraries for Node.js, PHP, Go and Rust check access in one call; from any other language, check over HTTP.

How paywalls are delivered

You design and build a paywall in Studio; deploying a build makes it live. You show the paywall at a location, a slug such as onboarding that your app asks for.

When your app presents the location, Voidhash answers with the paywall placed there, or one arm of a running A/B test, and its live build. The SDK downloads, verifies, caches and renders the build natively. Changing what a location shows needs no app release.

How analytics events flow

The SDKs queue events such as screen views, app opens and your custom events, and send them in batches. Voidhash tags each with the environment of the sending key and drops events you blocked in Settings → Events. Revenue events come from purchases Voidhash validated, so revenue reports never depend on the app. Studio combines both in Analytics. See Events.

Next steps