feat: encourage payment setup for paid relays without making it required #40

2026-04-20T20:30:19Z

userAdityaa commented

2026-04-20 20:30:19 +00:00

Stripe uses pay-in-advance billing: when a subscription starts, an invoice is created immediately. This PR implements the correct flow to match that model.

What changed:

When a user creates/upgrades a relay to a paid plan, show a payment dialog with a Lightning invoice immediately (not a setup screen)
In the payment dialog, offer "Set up payment method instead" to skip Lightning and connect NWC/card for future invoices
When NWC is first saved, automatically attempt to pay any outstanding open invoices
Fixed misleading banner text about when invoices are due
Added BTC_PRICE_USD_OVERRIDE env var for local testing when price APIs are unreachable
Billing stays the same: users are encouraged to pay but never blocked; relays only mark delinquent after the grace period ends.

Related to #28, #29

Stripe uses pay-in-advance billing: when a subscription starts, an invoice is created immediately. This PR implements the correct flow to match that model. What changed: * When a user creates/upgrades a relay to a paid plan, show a payment dialog with a Lightning invoice immediately (not a setup screen) * In the payment dialog, offer "Set up payment method instead" to skip Lightning and connect NWC/card for future invoices * When NWC is first saved, automatically attempt to pay any outstanding open invoices Fixed misleading banner text about when invoices are due * Added `BTC_PRICE_USD_OVERRIDE` env var for local testing when price APIs are unreachable Billing stays the same: users are encouraged to pay but never blocked; relays only mark delinquent after the grace period ends. Related to #28, #29 <img width="1434" alt="Screenshot 2026-04-21 at 4.09.00 AM.png" src="attachments/aabfee8d-3ccc-42a0-bd1e-0e2ac2f2f134"> <img width="1434" alt="Screenshot 2026-04-21 at 4.12.42 AM.png" src="attachments/a49da848-82f6-4377-8154-e57a5a730a1d">

Screenshot 2026-04-21 at 4.09.00 AM.png

263 KiB

Screenshot 2026-04-21 at 4.12.42 AM.png

362 KiB

userAdityaa commented

2026-04-20 20:30:53 +00:00

There isn't a hard requirement for this PR, just included as an optional improvement to encourage payment setup.

There isn't a hard requirement for this PR, just included as an optional improvement to **encourage payment** setup.

hodlbod commented

2026-04-20 20:33:34 +00:00

This isn't a bad idea, but the wording is a little off — because the invoice hasn't been generated yet we also can't accept payment yet. We can have them set up nwc/stripe, but they can't pay the bill in advance.

👍 1

userAdityaa commented

2026-04-20 20:45:12 +00:00

Got it, Updating the wordings to:

"This relay is on a paid plan. Invoices are generated at the end of the billing period, so you cannot pay in advance. You can set up NWC or Stripe now to be ready when an invoice is issued."

Got it, Updating the wordings to: > "This relay is on a paid plan. Invoices are generated at the end of the billing period, so you cannot pay in advance. You can set up NWC or Stripe now to be ready when an invoice is issued."

userAdityaa commented

2026-04-20 20:55:15 +00:00

Got it, Updating the wordings to:

"This relay is on a paid plan. Invoices are generated at the end of the billing period, so you cannot pay in advance. You can set up NWC or Stripe now to be ready when an invoice is issued."

Updated the image in the PR description with the revised wording.

> Got it, Updating the wordings to: > > "This relay is on a paid plan. Invoices are generated at the end of the billing period, so you cannot pay in advance. You can set up NWC or Stripe now to be ready when an invoice is issued." Updated the image in the PR description with the revised wording.

hodlbod commented

2026-04-20 21:06:34 +00:00

Sorry, I was wrong about this — I think the default for stripe is to pay in advance. Which means once the subscription is created, a payable invoice will be created as well. So what we should do is:

Create subscription when adding non-free relay
Allow the user to pay the invoice immediately using lightning
After successful payment, encourage the user to set up a payment method
Allow the user to set up a payment method instead of paying immediately
When a payment method is set up, if there is a due invoice attempt to pay it
Same thing when upgrading a relay
Downgrading a relay will result in customer credit and a prorated invoice the next period; I think this is automatically handled by stripe but it would be worth validating

So, again we encourage the user to pay, but don't require it. When the invoice is delinquent after a grace period, then we mark relays as delinquent.

Sorry, I was wrong about this — I think the default for stripe is to pay in advance. Which means once the subscription is created, a payable invoice will be created as well. So what we should do is: - Create subscription when adding non-free relay - Allow the user to pay the invoice immediately using lightning - After successful payment, encourage the user to set up a payment method - Allow the user to set up a payment method instead of paying immediately - When a payment method is set up, if there is a due invoice attempt to pay it - Same thing when upgrading a relay - Downgrading a relay will result in customer credit and a prorated invoice the next period; I think this is automatically handled by stripe but it would be worth validating So, again we _encourage_ the user to pay, but don't require it. When the invoice is delinquent after a grace period, then we mark relays as delinquent.

👍 1

userAdityaa marked the pull request as work in progress 2026-04-20 22:26:49 +00:00

userAdityaa added 1 commit 2026-04-21 10:18:04 +00:00

feat: invoice payment flow for paid relays 7696b9e1d4

userAdityaa force-pushed relay-payments from e6b5d821b0 to 7696b9e1d4

2026-04-21 10:18:04 +00:00

Compare

userAdityaa commented

2026-04-21 10:20:31 +00:00

Sorry, I was wrong about this — I think the default for stripe is to pay in advance. Which means once the subscription is created, a payable invoice will be created as well. So what we should do is:

Create subscription when adding non-free relay

Allow the user to pay the invoice immediately using lightning

After successful payment, encourage the user to set up a payment method

Allow the user to set up a payment method instead of paying immediately

When a payment method is set up, if there is a due invoice attempt to pay it

Same thing when upgrading a relay

Downgrading a relay will result in customer credit and a prorated invoice the next period; I think this is automatically handled by stripe but it would be worth validating

So, again we encourage the user to pay, but don't require it. When the invoice is delinquent after a grace period, then we mark relays as delinquent.

Thanks for outlining the flow clearly. I’ve implemented the necessary changes, and the updated user flow, now includes:

User creates or upgrades to a paid relay.
Stripe creates an invoice immediately.
User can pay now with Lightning, or choose setup instead.
If user pays, success screen always encourages setting up automatic payments.
If user sets up NWC, open due invoices are attempted right away.
If user sets up card, payment_method.attached webhook triggers retry of open due invoices.
If user downgrades, system validates proration/credit behavior through upcoming-invoice preview logging.
Payment is encouraged, not forced immediately. If still unpaid through Stripe grace handling, relay is marked delinquent on overdue.

> Sorry, I was wrong about this — I think the default for stripe is to pay in advance. Which means once the subscription is created, a payable invoice will be created as well. So what we should do is: > > - Create subscription when adding non-free relay > - Allow the user to pay the invoice immediately using lightning > - After successful payment, encourage the user to set up a payment method > - Allow the user to set up a payment method instead of paying immediately > - When a payment method is set up, if there is a due invoice attempt to pay it > - Same thing when upgrading a relay > - Downgrading a relay will result in customer credit and a prorated invoice the next period; I think this is automatically handled by stripe but it would be worth validating > > So, again we _encourage_ the user to pay, but don't require it. When the invoice is delinquent after a grace period, then we mark relays as delinquent. Thanks for outlining the flow clearly. I’ve implemented the necessary changes, and the updated user flow, now includes: 1. User creates or upgrades to a paid relay. 2. Stripe creates an invoice immediately. 3. User can pay now with Lightning, or choose setup instead. 4. If user pays, success screen always encourages setting up automatic payments. 5. If user sets up NWC, open due invoices are attempted right away. 6. If user sets up card, payment_method.attached webhook triggers retry of open due invoices. 7. If user downgrades, system validates proration/credit behavior through upcoming-invoice preview logging. 8. Payment is encouraged, not forced immediately. If still unpaid through Stripe grace handling, relay is marked delinquent on overdue.

userAdityaa marked the pull request as ready for review 2026-04-21 10:20:35 +00:00

userAdityaa marked the pull request as work in progress 2026-04-21 11:20:40 +00:00

userAdityaa commented

2026-04-21 11:22:11 +00:00

removing "WIP" after some final checking from my side.

hodlbod marked the pull request as ready for review 2026-04-21 12:48:06 +00:00

hodlbod merged commit bc79da34cf into master

2026-04-21 13:07:27 +00:00

hodlbod referenced this issue from a commit

2026-04-21 13:07:28 +00:00

feat: encourage payment setup for paid relays without making it required (#40)

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: coracle/caravel#40

Allow edits from maintainers