Tutorial

Payments

What Payments owns, the order of work, and where to go next.

Checked 2026-10-07

Payments charges your customers through your own Stripe account. You connect the account once, declare your prices in one price catalog, send buyers to a hosted checkout, and ask entitlement_grants:check whether someone has access. Your app holds no Stripe key, no webhook route and no billing table; there is nothing to deploy, and one key in your project is enough.

#What Payments gives you

• You stay merchant of record. Money is paid into your own Stripe account; Sylphx keeps the connected account id. Connect with OAuth, or with a restricted key (rk_test_…, rk_live_…), never a secret key.
• One catalog. Products, prices in several currencies, trials and the features each product grants live in one catalog, pushed to Stripe by :sync. A changed amount makes a new Stripe price, so existing subscribers keep the price they signed up at. A pricing page reads the catalog; it never hard-codes an amount.
• Hosted checkout and portal. A checkout session returns Stripe's hosted page; a portal session lets a customer update a card, read invoices or cancel. Subscriptions and one-time purchases both work.
• One answer for access. entitlement_grants:check answers whether a subject holds a feature now, and until when, whether they paid on the web, in the App Store or on Google Play.
• Webhooks handled for you. Money creates its own webhook endpoint on your Stripe account and applies every event once, so a repeated or late event changes nothing. A renewal whose webhook lags keeps access for a 3-day grace.
• Subscriptions you can manage. Cancel now or at period end, resume, change plan, or change the seat count, all through the API.

#Names and ids

Seller

orgs/{org}/projects/{project}/envs/{env}/merchant_accounts/default

Catalog

orgs/{org}/projects/{project}/envs/{env}/price_catalogs/default

Checkout

…/envs/{env}/checkout_sessions/{checkout_session}

Subscription

…/envs/{env}/customer_subscriptions/{customer_subscription}

Subject

{"end_user": "<your account id>"} or {"customer_organization": "<id>"}

The subject is any stable id your app already has for a person or a customer organization, 1 to 255 characters; it does not have to be a Sylphx Auth id.

#The scopes

• billing:write — connecting the seller, writing and syncing the catalog, creating checkout and portal sessions, and changing subscriptions. Call these from your server.
• billing:read — reading the catalog, subscriptions and checkouts, and entitlement_grants:check.

Keys and scopes covers the two kinds of key.