Bring your own Stripe — paid subscriptions setup
This guide is for writers who choose Mode B (bring your own account) for reader paid subscriptions. In Mode B, you are the seller of record: Readers pay into your own Stripe account, Stripe issues the receipts and handles tax, and LetterFlight never touches the money. LetterFlight only receives subscription events so it can unlock paid archive access.
> Online version of this page: /help/byo · Dashboard: /payments · Questions: support@letterflight.com
What you need
- A Stripe account in a country Stripe supports.
- A Stripe payment link for your paid subscription (monthly and/or yearly).
- A Stripe webhook signing secret (
whsec_…) for the endpoint LetterFlight gives you. - Optional: a Stripe restricted, read-only API key (
rk_…) with onlysubscriptions.readandcustomers.read— used for the “re-sync” button. It cannot move money.
Never give LetterFlight your Stripe secret key (sk_…) or your password. The webhook signing secret can only verify signatures; the restricted key is read-only.
Step 1 — Create your payment link
In Stripe: Product catalogue → Payment links → New. Create a recurring price (monthly or yearly), then copy the payment link (for example https://buy.stripe.com/…). Paste it into LetterFlight → /payments → Pricing & public-page settings and select Mode B. You also set the seller name and support email shown on the paywall (required for EU pre-sale disclosure).
Step 2 — Copy your LetterFlight webhook endpoint
On /payments, find Stripe connection (Mode B). The endpoint URL looks like:
https://letterflight.com/api/v1/billing/stripe/webhook/<your-endpoint-token>
Each writer gets a stable token, so the URL is visible before you save anything.
Step 3 — Add the endpoint in Stripe
In Stripe: Developers → Webhooks → Add endpoint. Paste the endpoint URL and select exactly these events:
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.paid
invoice.payment_succeeded
invoice.payment_failed
charge.refunded
charge.dispute.created
charge.disputed
charge.dispute.closed
Save, then copy the signing secret (whsec_…) Stripe shows for this endpoint and paste it into /payments → Stripe connection → Webhook signing secret → Save & verify.
Why these ten: created unlocks paid access, updated carries renewals and status changes, deleted marks cancellation, the invoice events cover successful and failed renewals, charge.refunded marks a refund, and the dispute events pause access while a chargeback is open and restore it if you win.
Step 4 (optional) — Add the read-only restricted key
In Stripe: Developers → API keys → Create restricted key. Grant read access to subscriptions and customers only. Paste it into the same form. The key is encrypted at rest, shown only as a prefix after saving, and can be revoked at any time. It powers the Re-sync subscription status button.
Step 5 — Test the connection
- Turn on Stripe test mode and make a test subscription through your payment link.
- Within a minute, the subscription should appear on /payments and your paid archive unlocks for that reader.
- Use Re-sync subscription status to check the last event LetterFlight received.
- When you go live, repeat with a real small payment, then refund it and confirm the reader's access follows your refund policy.
Cancellations belong to you
LetterFlight does not have the keys to your Stripe account, so it cannot cancel a Reader's subscription. Cancellation is done by the Reader in your Stripe customer portal (or by you in the Stripe dashboard). LetterFlight syncs the resulting event and updates access — refunds and cancellations keep access until the end of the paid period, unless you revoke it earlier. Your paywall tells Readers: *cancel through the seller*.
Tax receipts and invoices
In Mode B you are the seller of record. Stripe issues the Reader's receipts/invoices and you are responsible for VAT/sales tax registration and remittance. LetterFlight does not issue Reader invoices or collect tax in Mode B. If you need tax handling done for you, use Mode A (hosted) instead.
Troubleshooting
| Symptom | Check |
|---|---|
| Stripe says the endpoint returns 400 | The signing secret in LetterFlight does not match this endpoint. Re-copy whsec_… from Stripe. |
| No events arrive at all | The endpoint URL is wrong, the endpoint is disabled in Stripe, or you selected the wrong events. Re-send a test event from the Stripe dashboard. |
| Payment happened but the reader still sees the paywall | The payment email may differ from the email the Reader used at checkout (Apple private relay, work vs personal). Ask the Reader to use /activate and enter the email used at payment, or map it manually on /payments → Unmatched payments. |
| Reader paid twice | Refund one charge in Stripe; the refund event keeps the subscription correct. |
| Chargeback | A dispute event pauses access automatically. Add delivery evidence in Stripe. If you win, access restores automatically. |
Security and privacy
- LetterFlight stores the webhook signing secret and optional restricted key encrypted, never logs them, and only displays a short prefix.
- You can revoke the connection at any time on /payments; webhooks then stop updating subscriptions.
- Reader data LetterFlight receives: email, subscription status, Stripe customer/subscription IDs, amount and timestamps. Full card details never reach LetterFlight.
- Mode B is covered by the LetterFlight Privacy Policy; Stripe is your processor, not LetterFlight's.