Paywall API

These endpoints are live in production today, served by the FloKit payments gateway. They are separate from the v1 REST API, which is still in design-partner preview.

The paywall API submits store receipts for verification and logs funnel events for paywall analytics. Paywalls themselves are Flow-owned and served with the Flow page — there is no remote paywall configuration endpoint. Base URL: https://payments-gateway.flokitai.com

Authentication

These endpoints use request-scoped credentials instead of server API keys:

x-app-key header — your app’s publishable key (pk_...), created per app in the FloKit dashboard. It scopes the request to your app and is safe to embed in your app build (it is not a secret and does not authenticate the user). Required on entitlement reads and funnel event writes.
x-app-token header — an optional short-lived app-session token minted from the publishable key via POST /api/paywall/token. Anywhere x-app-key is accepted, x-app-token works instead — send one or the other.
x-user-id header — the user’s identity. userId or anonymousId query parameters are accepted as a fallback where custom headers are inconvenient (the header takes precedence).

Tenant resolution happens server-side from the app key and user identity — clients never send a company or tenant ID.

x-app-key enforcement is on in production. Requests without a valid app credential receive 401 on every endpoint marked as requiring it — there is no grace period. @flokitai/subscriptions-sdk v2.0+ sends it automatically — set appKey in initSubscriptionsSdk() and every call carries x-app-key (or x-app-token) for you.

GET /api/paywall/config

Removed. GET /api/paywall/config returns 410 with {"code": "PAYWALL_CONFIG_REMOVED"}. Remote paywall configuration no longer exists — paywalls are Flow-owned and served with the Flow page. The gateway still proxies the path so older SDK builds receive an honest 410 rather than a 404. Because the path is proxied, two non-410 outcomes are possible and are transport failures rather than statements about the paywall: 503 with {"error": "Flows Gateway is not configured."} when the gateway has no Flows upstream configured, and 502 when that upstream call fails. Treat both as retryable; only 410 is the durable answer.

POST /api/iap/receipts

Renamed from POST /api/paywall/receipt. The body schema is unchanged.

Submits an in-app purchase receipt for server-side verification. Send the Apple StoreKit 2 signed transaction (JWS) or the Google Play package name + purchase token; the gateway forwards it to the verification service and returns the verification result.

Headers

Header	Value
`x-user-id`	Your authenticated user ID (required)
`x-app-key`	Your publishable app key (recommended)
`Content-Type`	`application/json`

Receipt verification is protected by the store signature on the receipt itself, so x-app-key is not enforced here — but send it anyway for uniformity.

Request body

string

required

apple or google.

string

Apple StoreKit 2 signed transaction (JWS). Required for apple.

string

Android package name. Required for google.

string

Google Play purchase token. Required for google.

Example

curl -X POST https://payments-gateway.flokitai.com/api/iap/receipts \
  -H "x-user-id: usr_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "apple",
    "signedTransactionInfo": "eyJhbGciOiJFUzI1NiIs..."
  }'

const res = await fetch(
  'https://payments-gateway.flokitai.com/api/iap/receipts',
  {
    method: 'POST',
    headers: {
      'x-user-id': 'usr_abc123',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      provider: 'google',
      packageName: 'com.yourapp',
      purchaseToken: 'opaque-play-purchase-token',
    }),
  },
);

const result = await res.json();
// { active: true, state: "active", entitlement_key: "com.yourapp.annual", ... }

Response

200 returns the same canonical entitlement shape as GET /api/entitlements/current:

{
  "active": true,
  "entitlement_key": "com.yourapp.annual",
  "expires_at": "2026-09-01T00:00:00.000Z",
  "provider": "apple",
  "state": "active",
  "source_event_id": "evt_01j...",
  "updated_at": "2026-08-01T12:00:00.000Z",
  "source": "entitlement"
}

When the receipt verified but no canonical entitlement has been projected yet, source is provider_verified and the response carries active, provider, state, expires_at, and source only.

Errors

Status	Body	Condition
`400`	`{ "error": "Invalid receipt request." }`	Body fails gateway validation
`400`	`{ "error": "signedTransactionInfo is required for apple." }`	Apple receipt without the signed transaction
`400`	`{ "error": "purchaseToken is required for google." }`	Google receipt without the purchase token
`400`	`{ "error": "Receipt verification failed." }`	The store rejected the receipt
`401`	`{ "error": "x-user-id is required." }`	Missing user identity
`403`	`{ "error": "Receipt does not belong to the authenticated user." }`	Receipt is bound to a different user
`422`	`{ "error": "App authority (companyId/appId) is required." }`	No company/app could be resolved for this request

POST /api/paywall/events

Logs paywall funnel events — impressions, offer taps, purchases, conversions, cancellations — for paywall analytics. Accepts 1–50 events per request. The gateway resolves the request’s country at the edge; a server-resolved country takes precedence over any client-supplied country value.

Headers

Header	Value
`x-app-key`	Your publishable app key (required)
`x-user-id`	Your authenticated user ID (required)
`Content-Type`	`application/json`

Every event’s app_id must belong to the app the key was issued for — mismatches are rejected with 403.

Request body

array

required

1–50 event objects.

Each event:

string

required

A name from the canonical event vocabulary. Unknown names are rejected with a non-retriable 400 that discards the whole batch, so validate before sending (the SDK does this on-device).

Group	Names
Paywall render	`impression`, `offer_tap`, `purchase_start`, `trial_start`, `convert`, `cancel`, `purchase_failed`, `paywall_dismiss`
App lifecycle	`first_open`, `app_open`, `session_start`, `session_end`, `day_active`
Entitlement	`entitlement_granted`, `entitlement_revoked`
Web funnel (shared verbatim with the hosted flow runtime)	`flow_view`, `landing_view`, `quiz_start`, `quiz_answered`, `quiz_complete`, `result_view`, `lead_captured`, `offer_view`, `install_click`, `deep_link_click`, `activation_completed`
Checkout + identity	`checkout_start`, `checkout_completed`, `checkout_failed`, `app_activation`, `user_alias`

string

required

Your application identifier.

string

The placement the event happened at, e.g. onboarding_complete. Optional; slug format ^[a-z0-9_]{1,64}$. Lets funnels be sliced by placement in reporting.

object

required

Must include paywall_id and variant_id for the six render-scoped events: impression, offer_tap, purchase_start, trial_start, convert, and cancel. purchase_failed and paywall_dismiss deliberately do not require them, since purchase() can fire those with no paywall in context. All other events may carry arbitrary properties.

string

Client-minted idempotency key. The SDK’s retry queue stamps one on every event so a re-delivered batch does not double-count; forwarded as-is.

string

ISO 3166-1 alpha-2 country code. Used only if server-side resolution fails.

string

Client platform, e.g. ios or android.

string

ISO 8601 timestamp of when the event occurred.

Example

curl -X POST https://payments-gateway.flokitai.com/api/paywall/events \
  -H "x-app-key: pk_live_your_app_key" \
  -H "x-user-id: usr_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_type": "impression",
        "app_id": "your_app",
        "platform": "ios",
        "occurred_at": "2026-06-21T10:30:00Z",
        "properties": {
          "paywall_id": "onboarding",
          "variant_id": "annual_emphasis"
        }
      }
    ]
  }'

const res = await fetch(
  'https://payments-gateway.flokitai.com/api/paywall/events',
  {
    method: 'POST',
    headers: {
      'x-app-key': 'pk_live_your_app_key',
      'x-user-id': 'usr_abc123',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      events: [
        {
          event_type: 'offer_tap',
          app_id: 'your_app',
          platform: 'ios',
          occurred_at: new Date().toISOString(),
          properties: {
            paywall_id: 'onboarding',
            variant_id: 'annual_emphasis',
            product_id: 'com.yourapp.annual',
          },
        },
      ],
    }),
  },
);

const result = await res.json();
// { accepted: 1 }

Response

{
  "accepted": 1
}

Errors

Status	Body	Condition
`400`	`{ "error": "Invalid paywall events request." }`	Bad `event_type`, empty array, more than 50 events, or missing required fields
`401`	`{ "error": "x-app-key is required." }`	Missing app key
`401`	`{ "error": "Invalid app key." }`	Unknown or revoked app key
`401`	`{ "error": "x-user-id is required." }`	Missing user identity
`403`	`{ "error": "event app_id does not match the app key." }`	An event claims an `app_id` the key was not issued for
`422`	`{ "error": "..." }`	Rejected upstream, e.g. no tenant attributed for this user

POST /api/paywall/token

Exchanges the publishable key for a short-lived app-session token bound to the requesting app and user. Use it when you’d rather not attach the raw pk_... key to every request: mint once at SDK init, send the token as x-app-token on subsequent calls, and re-mint when it expires.

Headers

Header	Value
`x-app-key`	Your publishable app key (required — always enforced on this endpoint)
`x-user-id`	Your authenticated user ID (required)

Example

curl -X POST https://payments-gateway.flokitai.com/api/paywall/token \
  -H "x-app-key: pk_live_your_app_key" \
  -H "x-user-id: usr_abc123"

const res = await fetch(
  'https://payments-gateway.flokitai.com/api/paywall/token',
  {
    method: 'POST',
    headers: { 'x-app-key': 'pk_live_your_app_key', 'x-user-id': 'usr_abc123' },
  },
);

const { token } = await res.json();
// send as x-app-token on subsequent calls

Response

{
  "token": "v1.eyJhIjoi...",
  "token_type": "app-session",
  "expires_in": 900
}

The token is opaque to clients, expires after 15 minutes, and is only valid for the same x-user-id it was minted for — a token leaked from one user cannot read another user’s entitlements.

Errors

Status	Body	Condition
`401`	`{ "error": "x-app-key is required." }` / `{ "error": "Invalid app key." }`	Missing or invalid key
`401`	`{ "error": "x-user-id is required." }`	Missing user identity
`503`	`{ "error": "App session tokens are not enabled." }`	Token minting not configured on this environment

POST /api/paywall/checkout

Removed. POST /api/paywall/checkout was deleted along with the Offer/Offering entities. Web checkout is created from a published Flow’s paywall and checkout configuration and driven same-origin by @flokitai/checkout-js on the Flow page. The React Native SDK’s startWebCheckout() always throws CheckoutUnavailableError with code: 'WEB_CHECKOUT_MIGRATED'.

Other live gateway endpoints

The gateway serves the endpoints below in production today. They are listed here so the surface is complete; the SDK calls them for you, so most integrations never build these requests by hand. All of them resolve company, app, and environment server-side from the presented app credential (x-app-key or x-app-token) — a request body can never select the tenant.

Endpoint	What it does
`POST /api/identity/alias`	Links the persisted `anonymous_ref` to a known `userId` after login. The SDK’s `identify()`.
`POST /api/identity/handoff`	Mints a signed web→app handoff for a FloKit web funnel.
`POST /api/identity/handoff-exchange`	Redeems a signed handoff. Replay-protected — the token’s `jti` is consumed exactly once.
`POST /api/paywall/handoff/exchange`	Redeems the single-use deep-link code (`hc_…`) from a web-funnel link and adopts the web `anonymous_ref`. The SDK’s `exchangeHandoffCode()`. Returns `503` when handoff exchange is not enabled on the environment.
`POST /api/identity/attribution-signal`	Accepts the Android Play Install Referrer string or an Apple AdServices token so the install joins the acquisition graph. Deduplicated on a deterministic edge id.
`GET /oauth/google-play/callback`	Google Play OAuth connect callback. Part of the dashboard connector flow, not an app-facing endpoint.
`GET /healthz`	Health check.

Provider webhook passthrough

The gateway also exposes webhook receiver endpoints for subscription and attribution providers. Bodies are forwarded as raw bytes — provider signature headers are preserved and verified downstream, so configure these URLs directly in each provider’s dashboard.

Endpoint	Provider
`POST /webhooks/apple`	Apple App Store Server Notifications V2
`POST /webhooks/google`	Google Play RTDN (Pub/Sub push)
`POST /webhooks/paddle/:connectionId`	Paddle Billing, per connection
`POST /webhooks/stripe/:connectionId`	Stripe Direct / Managed Payments, per connection
`POST /webhooks/lemon-squeezy/:connectionId`	Lemon Squeezy, per connection
`POST /api/integrations/mmp/generic-attribution`	Generic MMP attribution callback

Removed: the RevenueCat, Adapty, and generic-subscription webhook receivers (POST /api/providers/revenuecat/webhook, POST /api/providers/adapty/webhook, and POST /api/providers/generic-subscription/webhook) no longer exist on the gateway — there is no RevenueCat or Adapty adapter in the platform, and the generic receiver was deleted. If any of these URLs is still configured in a provider dashboard, its deliveries are being dropped. Third-party subscription events must arrive through a per-connection provider receiver (/webhooks/paddle/:connectionId, /webhooks/stripe/:connectionId, or /webhooks/lemon-squeezy/:connectionId).

If the downstream service cannot be reached, the gateway responds 502; if it times out (10 seconds), 504 — providers treat both as delivery failures and retry.

Live endpoints

API reference

Authentication

GET /api/paywall/config

POST /api/iap/receipts

Headers

Request body

Example

Response

Errors

POST /api/paywall/events

Headers

Request body

Example

Response

Errors

POST /api/paywall/token

Headers

Example

Response

Errors

POST /api/paywall/checkout

Other live gateway endpoints

Provider webhook passthrough

​Authentication

​GET /api/paywall/config

​POST /api/iap/receipts

​Headers

​Request body

​Example

​Response

​Errors

​POST /api/paywall/events

​Headers

​Request body

​Example

​Response

​Errors

​POST /api/paywall/token

​Headers

​Example

​Response

​Errors

​POST /api/paywall/checkout

​Other live gateway endpoints

​Provider webhook passthrough

Authentication

GET /api/paywall/config

POST /api/iap/receipts

Headers

Request body

Example

Response

Errors

POST /api/paywall/events

Headers

Request body

Example

Response

Errors

POST /api/paywall/token

Headers

Example

Response

Errors

POST /api/paywall/checkout

Other live gateway endpoints

Provider webhook passthrough