URnetwork API: Subscription

Stop the Stripe subscription billing the caller's network at the end of the paid period (cancel_at_period_end); the customer keeps Pro until end_time. Only store "stripe" (the default) is acted on: the other stores answer with error.message and, for Apple/Google, the store's subscriptions page in manage_url. Idempotent: an already-cancelling subscription is not written again.

Undo /subscription/cancel while the paid period is still running: the Stripe subscription renews again. Same request and result shapes.

Check if the balance code is valid.

Redeem the balance code and add the transfer balance to the caller network.

Creates an anonymous payment identifier to be used with purchases. This keeps network information out of the payment processor system. For example in Google Play this is called the "obfuscated account id".

The android app reports its purchase token BEFORE acknowledging it. The server verifies the token with the Android Publisher API and credits it through the same advisory-lock gate as the RTDN webhook and the payment reconciler, so this is idempotent against both. Because the client only acknowledges after a terminal answer, a lost webhook is no longer lost money: the store keeps redelivering the proof to the client until the server has seen it.

credited, already_credited, wrong_network and invalid are TERMINAL -- stop retrying and finalize with the store. pending is retryable (the purchase is on hold, paused or in its grace period), as is any non-2xx, which is a transport or store failure and carries no status. wrong_network means the token's linked account is a different network than the session's. The credited sku is always the store's, never the client's.

Shares a per-account budget with the Apple endpoint; every attempt counts, including failures.

The Apple app reports its StoreKit transaction JWS (Transaction.jwsRepresentation) BEFORE calling finish(). A client report is an unauthenticated-content push, so the JWS goes through the FULL pinned-root webhook verifier -- ES256, a three-certificate x5c chain carrying Apple's policy extensions, terminating at a pinned Apple root, with the chain judged at the JWS's own signedDate -- and the bundle and environment must match this app. The signed-date freshness window is deliberately NOT applied, because a report may legitimately be retried days after the purchase; that is the whole point of the retryable reporting path.

The verified claims then credit through the same transaction ledger gate as the notification webhook and the reconciler. Statuses are the same as the Play endpoint: a JWS that fails verification is terminal invalid, never an error, so the client stops retrying.

Cheap validation runs first, then the shared per-account budget, then the cryptographic verification -- so a malformed request burns no budget and an over-budget caller burns no CPU.

Prepare an inline Stripe PaymentSheet purchase of Pro (the non-Play Android flavors, Windows and Linux; never the play flavor or iOS/macOS). The server creates or reuses the Stripe customer (metadata network_id) and the subscription at the caller's regional tier price: the yearly plan with the 14-day trial and, when the caller's welcome offer is redeemable, the 25% coupon applied server-side; the monthly plan without a trial. The sheet confirms the returned intent: a SetupIntent for the yearly plan (intent_type: setup, setup_intent_client_secret) or the first invoice's PaymentIntent for the monthly plan (intent_type: payment, payment_intent_client_secret). Configure the sheet with customer_id, ephemeral_key_secret and publishable_key; pass the Stripe API version the mobile SDK requires as stripe_version.

The trial is credited only once the card is attached (setup_intent.succeeded); an abandoned sheet leaves nothing behind. The charged tier is finalized from the card's billing country before the trial ends and the tier is recorded on the subscription. Calling again replaces a pending, unfinished sheet.