belt-pay 0.0.5 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 937d9e1a7ca86c274b1dd20feb2ad16b2f9f9aa8544b0bffd6d72ed1550768f7
4
- data.tar.gz: f33e95b73bd5f8104d3da45c34ce7e3e4e6ca329224721c80271af3f8e7c85d3
3
+ metadata.gz: 75e20f3be237db3416278e50e6ab37a8ba716f03c93a8e6d7b5b45ece3e2b740
4
+ data.tar.gz: '093835f36169b61cc8e24486946ecd249e537f9ece9fbf3127bcd80c9b8baf83'
5
5
  SHA512:
6
- metadata.gz: b1c7f6bb3f97548a05e060090f47b586aaf0435237931cd1c67b55534efd72eb706cf6af1d7294f07a5210268fdd6c232ef951d410722b00de1bdc56f43c30cc
7
- data.tar.gz: 73e0341c2f2441a279814645e959df9f1b94c41d88ba70018bac6b3ef10c144583288e945ee0a1d22e955c057361dc5e71858c5e4a63769e9a2fb47af3d4ad38
6
+ metadata.gz: aedef9e1ac18d26b57e7d43e62609a642ef6f117c69aefbcd469d032f9990646ad5488dc87853e9c05536311fd4a8c6a8c795aef991464546ac8074562c71b31
7
+ data.tar.gz: 7bda16104e9beefd25990383ae0b5c27369faf9a38267cb1ea79cd74ac8172bf53602a771dc6c7edcbd23040a98c1832fffc708b4170eeab9e1e8179d2776bdb
data/CHANGELOG.md CHANGED
@@ -1,5 +1,173 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.0.7 — 2026-11-15
4
+
5
+ Security release for the Stripe webhook. **Read "Upgrading from 0.0.6 or earlier" below
6
+ before deploying**: the steps marked Required are not optional.
7
+
8
+ ### Fixed
9
+
10
+ - **The webhook no longer accepts events signed with the placeholder secret.** The
11
+ generated Terraform seeded the secret with `whsec_PLACEHOLDER` / `sk_test_PLACEHOLDER`,
12
+ and the webhook verified against whatever it found, so on a deploy whose secret was
13
+ never replaced anyone could sign a made-up event. `verify_webhook` now raises
14
+ `Belt::Pay::ConfigurationError` unless the signing secret is a real `whsec_` secret,
15
+ `ensure_api_key!` refuses a missing or placeholder API key, and the Terraform template
16
+ creates the secret empty. `belt pay:setup` warns while either value is unset.
17
+ - **`checkout.session.completed` no longer means paid.** A transaction is completed only
18
+ when the session's `payment_status` is `paid` or `no_payment_required`. A session paid
19
+ by a delayed method (bank debit, voucher) stays `pending` until
20
+ `checkout.session.async_payment_succeeded` completes it or `_failed` fails it.
21
+ - **Refunds and disputes reach the transaction.** `charge.refunded` records
22
+ `amount_refunded_cents` and marks a fully refunded transaction `refunded`;
23
+ `charge.dispute.created` marks it `disputed`; `charge.dispute.closed` returns it to
24
+ `completed` (won) or `refunded` (lost).
25
+ - **A redelivered event changes nothing.** Rows the webhook creates are keyed on the
26
+ Checkout Session / invoice id with a conditional put, and only a `pending` transaction
27
+ can be completed, so Stripe's retries and Dashboard resends no longer add duplicate
28
+ rows or revive a refunded purchase.
29
+ - **`Billable#subscribe!` no longer grants the plan before anything is paid.** `pay_plan`
30
+ is recorded only when the subscription is `active` or `trialing`. The webhook sets it
31
+ when Stripe reports the subscription active and clears it when the subscription is
32
+ `canceled`, `unpaid` or `incomplete_expired` (it asks Stripe for the subscription's
33
+ current status rather than trusting the event). This needs the new
34
+ `Belt::Pay.configuration.customer_class`. The subscription's own transaction is
35
+ `pending` until active. `cancel_subscription!(immediately: true)` clears `pay_plan`
36
+ along with the subscription id.
37
+ - **Events missing a field no longer crash the webhook.** Stripe objects raise on a
38
+ field the event doesn't carry (for example metadata without `app_customer_id`, or
39
+ `invoice.subscription` on API versions from 2025-03-31), which made such events fail
40
+ with a 500 on every retry. Fields are now read defensively.
41
+ - **Secrets are read without an app patch.** `fetch_api_key` / `fetch_webhook_secret`
42
+ relied on a `SecretsHelper` Belt doesn't ship and returned nil without one. They now
43
+ read the configured secret from AWS Secrets Manager directly (a `::SecretsHelper`
44
+ defined by the app is still used when present).
45
+ - The webhook controller decodes a base64-encoded body (`isBase64Encoded`). Belt itself
46
+ still rejects such a body before the controller runs, so this only takes effect once
47
+ Belt passes it through.
48
+ - `Checkout.create` no longer records every pending transaction as `usd`: the currency
49
+ comes from the request when it names one, and from the session when it is paid.
50
+
51
+ ### Added
52
+
53
+ - **`Belt::Pay.on(*event_types) { |event, transaction| ... }`** runs your code when the
54
+ webhook receives an event, after the gem's bookkeeping. See "Acting on Events" in the
55
+ README.
56
+ - `Belt::Pay::WebhookHandler::EVENTS` gains `checkout.session.async_payment_succeeded`,
57
+ `checkout.session.async_payment_failed`, `customer.subscription.created`,
58
+ `charge.refunded`, `charge.dispute.created` and `charge.dispute.closed`.
59
+ - `belt pay:setup` offers to add missing events to an existing Stripe endpoint in place,
60
+ keeping its signing secret.
61
+ - `Belt::Pay.configuration.customer_class`, transaction status `disputed`, and the
62
+ transaction fields `amount_refunded_cents` and `provider_payment_intent_id` (now filled
63
+ in). No table or index change is needed.
64
+
65
+ ### Known limits
66
+
67
+ - A refund or dispute is matched to a checkout through its Checkout Session, and to a
68
+ renewal through the charge's `invoice`. Stripe API versions from 2025-03-31 no longer
69
+ put `invoice` on a charge, so on an endpoint using one of those a refunded renewal is
70
+ not marked; use a `Belt::Pay.on('charge.refunded')` hook for those.
71
+ - A part refund has no row of its own: the running total is `amount_refunded_cents` on
72
+ the original transaction.
73
+
74
+ ### Upgrading from 0.0.6 or earlier
75
+
76
+ Do these in order, for every environment (`dev`, `prod`, ...).
77
+
78
+ 1. **Bump the gem.** In the app's `Gemfile` (and `lambda/Gemfile` if it has one) allow
79
+ `belt-pay` 0.0.7 (`gem 'belt-pay', '~> 0.0.7'`), then `bundle update belt-pay`.
80
+
81
+ 2. **Required: run `belt 'pay:setup[<env>]'` once per environment.** It does two things
82
+ this release needs: it subscribes the existing Stripe endpoint to the new events, and
83
+ it tells you if the stored secret is still unset. Do not use `pay:show` for this; it
84
+ prints live credentials. Answer the prompts in this order:
85
+
86
+ | Prompt | Answer |
87
+ |--------|--------|
88
+ | `Stripe secret key [blank keeps existing]` | blank (Enter) |
89
+ | `Create the <mode>-mode webhook endpoint in Stripe now? [y/N]` | `y` |
90
+ | `Stripe <mode> secret key, or restricted key with Webhook Endpoints write [not stored]` | Only appears when the stored key is a restricted key that can't manage endpoints. Needs a person: paste an `sk_` key or a restricted key with Webhook Endpoints: Write. It is used once and not stored |
91
+ | `Add them to this endpoint? (its signing secret stays the same) [Y/n]` | `y` |
92
+ | `Replace it? [y/N]` | `n` |
93
+ | `Stripe webhook signing secret [blank keeps existing]` | blank (Enter) |
94
+
95
+ The output should include `Endpoint we_... now receives 12 events.` (Or do this part
96
+ in the Stripe Dashboard: Developers -> Webhooks -> the endpoint -> add the six events
97
+ listed under "Added".) **Do not skip this**: once this version is deployed, a checkout
98
+ paid by a delayed method stays `pending` until
99
+ `checkout.session.async_payment_succeeded` arrives, and refunds and disputes are only
100
+ seen if the endpoint sends them.
101
+
102
+ 3. **Required: if that run printed `Warning: ... not set in <secret>`**, or said
103
+ `No Stripe secret key stored yet`, the environment still holds the placeholder (or
104
+ nothing). Run `belt 'pay:setup[<env>]'` again and this time give it the real Stripe
105
+ key and let it create the endpoint. Until then, by design, that environment answers
106
+ every webhook with 500 and refuses Stripe calls.
107
+
108
+ 4. **Required if the app uses `subscribe!(plan:)` or reads `pay_plan` / `plan` /
109
+ `plan_allows?` / `within_limit?`:** set the customer model where the app and the
110
+ webhook Lambda boot, and make sure that model is loaded in the webhook Lambda
111
+ (`lambda/pay_webhooks.rb`):
112
+
113
+ ```ruby
114
+ Belt::Pay.configure { |config| config.customer_class = 'Customer' } # your Billable model
115
+ ```
116
+
117
+ Without it `pay_plan` is never set for a subscription that starts unpaid (the webhook
118
+ logs `customer_class is not configured` on each subscription event). Code that relied
119
+ on `pay_plan` being set immediately after `subscribe!` must wait for the webhook, or
120
+ check `result[:status]`.
121
+
122
+ 5. **Check what the webhook Lambda is allowed to do.** Belt Pay does not generate this
123
+ IAM; it is in the app's Terraform (look for the policy attached to the `pay_webhooks`
124
+ Lambda). A missing permission makes the affected events answer 500.
125
+ - On the `<app>-<env>-pay-transactions` table and its indexes: `dynamodb:GetItem`,
126
+ `dynamodb:Query`, `dynamodb:PutItem` and `dynamodb:UpdateItem`. `GetItem` is new in
127
+ this release.
128
+ - If you set `customer_class` (step 4): `dynamodb:GetItem`, `dynamodb:PutItem` and
129
+ `dynamodb:UpdateItem` on that model's table.
130
+ - `secretsmanager:GetSecretValue` on the Stripe secret (the generated
131
+ `read_secrets_policy_arn`).
132
+ - If the runtime Stripe key is a restricted key (`rk_`): at least Read on Checkout
133
+ Sessions (to find the purchase behind a refund or dispute) and on Subscriptions.
134
+
135
+ 6. **Check code that reads transactions.** `checkout`/`subscription` rows can now be
136
+ `pending` after checkout completes, and `refunded` or `disputed` later. Treat only
137
+ `status == 'completed'` as paid. Rows written by the webhook use the Stripe id
138
+ (`cs_...`, `in_...`, `sub_...`) as `id` instead of a UUID. `Transaction.record_checkout`,
139
+ `record_subscription` and `record_renewal` return nil when the row already exists.
140
+
141
+ 7. **Remove app patches this release replaces** (optional, they keep working): a
142
+ `prepend` over `fetch_api_key` / `fetch_webhook_secret` that reads Secrets Manager,
143
+ and controller overrides that only check `payment_status`, refuse the placeholder
144
+ secret or de-duplicate events. An overridden controller that calls
145
+ `Belt::Pay.provider.verify_webhook` and `WebhookHandler.send(:dispatch, event)` keeps
146
+ working; `dispatch` now also runs `Belt::Pay.on` hooks.
147
+
148
+ 8. **Stop seeding placeholders in Terraform (optional hygiene).** In the app's generated
149
+ `infrastructure/modules/pay/variables.tf`, change the defaults of `stripe_secret_key`
150
+ and `stripe_webhook_secret` from `"sk_test_PLACEHOLDER"` / `"whsec_PLACEHOLDER"` to
151
+ `""`. Edit those two lines by hand; do not regenerate with `belt g pay --force`,
152
+ which would also overwrite `lambda/pay_webhooks.rb` and the Lambda config. Existing
153
+ secrets are not touched (`ignore_changes`); this only affects environments created
154
+ later.
155
+
156
+ 9. Deploy (`belt apply <env>` / your usual deploy), then send a test event from the
157
+ Stripe Dashboard and confirm the endpoint answers 200.
158
+
159
+ ## 0.0.6 — 2026-11-02
160
+
161
+ - **`pay:setup` works with a restricted runtime key.** The stored key is what the app
162
+ runs with, so it should be a restricted key (`rk_`) holding only what checkout and the
163
+ portal need. Setup used to manage the webhook endpoint with that same key, so a
164
+ restricted key without Webhook Endpoints access failed with a Stripe permission error.
165
+ When Stripe refuses the stored key, setup now asks once for a key that can manage
166
+ endpoints (an `sk_` secret key, or a restricted key with Webhook Endpoints: Write),
167
+ uses it for the endpoint list/create/delete calls in that run only, and never stores
168
+ it. A key from the other Stripe mode is refused. Leaving the prompt blank, or a second
169
+ refusal, falls back to the Dashboard steps; the stored key is still saved either way.
170
+
3
171
  ## 0.0.5 — 2026-10-31
4
172
 
5
173
  - **`create_checkout` no longer drops Checkout Session options.** The Stripe provider used
data/README.md CHANGED
@@ -59,7 +59,9 @@ Belt::Pay.plans.paid # => [pro, ...]
59
59
  Belt::Pay.plans.featured # => the :pro plan
60
60
  Belt::Pay.plans.to_a # => [{ key:, name:, prices:, limits:, ... }] for your frontend
61
61
 
62
- # Gate features and enforce limits
62
+ # Gate features and enforce limits. The plan is granted once Stripe reports the
63
+ # subscription active (or trialing) and taken back when it ends; see
64
+ # "Plans follow the subscription" below.
63
65
  customer.on_plan?(:pro) # => true
64
66
  customer.plan_allows?(:sso) # => true
65
67
  customer.within_limit?(:projects, current_count) # => false once the ceiling is hit
@@ -165,9 +167,28 @@ Belt::Pay.configure do |config|
165
167
  config.provider = :stripe # Only :stripe for now
166
168
  config.secret_name = 'myapp-prod-stripe' # Secrets Manager secret
167
169
  config.table_name_prefix = 'myapp-prod' # DynamoDB table prefix
170
+ config.customer_class = 'Customer' # Your Billable model (class or name)
168
171
  end
169
172
  ```
170
173
 
174
+ #### Plans follow the subscription
175
+
176
+ `customer_class` is the model that includes `Belt::Pay::Billable`. Set it wherever the
177
+ webhook Lambda boots (the model must be loadable there). The webhook uses it to find the
178
+ customer named by a subscription's `app_customer_id` and keep `pay_plan` /
179
+ `pay_subscription_id` in step with Stripe:
180
+
181
+ - `subscribe!(plan:)` records `pay_plan` only if the subscription is already `active` or
182
+ `trialing`. One that still needs its first payment (`incomplete`, the usual case)
183
+ grants nothing yet.
184
+ - When Stripe reports the subscription `active` or `trialing`, the webhook sets
185
+ `pay_plan` (the plan declared for the subscription's price, else its `plan` metadata).
186
+ - When it becomes `canceled`, `unpaid` or `incomplete_expired`, the webhook clears
187
+ `pay_plan`. `past_due` keeps it while Stripe retries the payment.
188
+
189
+ Without `customer_class` the webhook cannot do any of this: it logs an error on each
190
+ subscription event and `pay_plan` is never set for a subscription that starts unpaid.
191
+
171
192
  ### Secrets Manager Format
172
193
 
173
194
  The Stripe secret should contain:
@@ -179,6 +200,14 @@ The Stripe secret should contain:
179
200
  }
180
201
  ```
181
202
 
203
+ Belt Pay reads it straight from Secrets Manager (the webhook and API Lambdas need
204
+ `secretsmanager:GetSecretValue` on it, which the generated `read_secrets_policy_arn`
205
+ grants). The generated Terraform creates the secret with both values empty, and Belt Pay
206
+ refuses to work with a value that is missing or a placeholder: `verify_webhook` raises
207
+ `Belt::Pay::ConfigurationError` (the webhook answers 500) unless the signing secret is a
208
+ real `whsec_` secret, and no Stripe call is made without a real API key. Nothing is ever
209
+ verified against a secret someone else could know.
210
+
182
211
  ### Setting Up and Managing Secrets
183
212
 
184
213
  Belt Pay hooks into Belt through its standard gem-provided Rake task mechanism. The
@@ -200,6 +229,20 @@ either prompt blank to preserve its existing value. Use `--webhook-url` /
200
229
  `BELT_PAY_WEBHOOK_URL` or `--webhook-events` / `BELT_PAY_WEBHOOK_EVENTS` to override the
201
230
  defaults. Test (`sk_test_`) and live (`sk_live_`) keys get separate endpoints and secrets.
202
231
 
232
+ If Stripe already has an endpoint for the URL and it lacks some handled events (one
233
+ created by an older Belt Pay, say), setup offers to add them to it in place, which keeps
234
+ its signing secret. Setup also warns when the key or signing secret is still unset.
235
+
236
+ Prefer a [restricted key](https://docs.stripe.com/keys#limit-access) (`rk_`) as the
237
+ stored key, scoped to what your app calls at runtime (typically Customers, Checkout
238
+ Sessions, Customer portal and Subscriptions). The webhook reads Checkout Sessions (to
239
+ find the purchase a refund or dispute belongs to) and Subscriptions (to check a
240
+ subscription's current status), so give those at least Read. It doesn't need Webhook
241
+ Endpoints access:
242
+ when Stripe refuses it for the endpoint step, setup asks once for a key that can manage
243
+ endpoints (your `sk_` secret key, or a restricted key with Webhook Endpoints: Write),
244
+ uses it for that step only, and doesn't store it.
245
+
203
246
  You can also pass the environment with standard Rake task-argument syntax:
204
247
 
205
248
  ```bash
@@ -306,26 +349,63 @@ end
306
349
 
307
350
  ## Webhook Events
308
351
 
309
- The gem automatically handles these Stripe webhook events:
352
+ The gem automatically handles these Stripe webhook events
353
+ (`Belt::Pay::WebhookHandler::EVENTS`, which is what `belt pay:setup` subscribes the
354
+ endpoint to):
310
355
 
311
356
  | Event | Behavior |
312
357
  |-------|----------|
313
- | `checkout.session.completed` | Marks pending transaction as completed |
314
- | `checkout.session.expired` | Marks pending transaction as failed |
315
- | `invoice.paid` | Records subscription renewal transaction |
358
+ | `checkout.session.completed` | Completes the transaction if the session is paid (`payment_status` `paid` or `no_payment_required`). A session paid by a delayed method (bank debit, voucher) stays `pending` |
359
+ | `checkout.session.async_payment_succeeded` | Completes the pending transaction of a delayed payment |
360
+ | `checkout.session.async_payment_failed` | Marks it `failed` |
361
+ | `checkout.session.expired` | Marks pending transaction as `failed` |
362
+ | `invoice.paid` | Records a subscription renewal transaction (once per invoice) |
316
363
  | `invoice.payment_failed` | Logs payment failure |
317
- | `customer.subscription.deleted` | Logs subscription cancellation |
318
- | `customer.subscription.updated` | Logs subscription status changes |
364
+ | `customer.subscription.created` / `.updated` / `.deleted` | Sets or clears the customer's `pay_plan` to match the subscription (see [Plans follow the subscription](#plans-follow-the-subscription)) and settles the subscription's transaction |
365
+ | `charge.refunded` | Records `amount_refunded_cents`; a full refund marks the transaction `refunded` |
366
+ | `charge.dispute.created` | Marks the transaction `disputed` |
367
+ | `charge.dispute.closed` | Won: `completed` again. Lost: `refunded` |
368
+
369
+ Stripe delivers events at least once, and anyone with Dashboard access can send one
370
+ again. Handling is safe to repeat: rows the webhook creates are keyed on the Checkout
371
+ Session or invoice id, and only a `pending` transaction can become `completed`, so a
372
+ redelivered event never adds a row or revives a refunded purchase.
373
+
374
+ **Only `completed` means the customer has paid.** If your app decides what someone owns
375
+ from `customer.transactions`, check `status == 'completed'`.
376
+
377
+ ### Acting on Events
378
+
379
+ Register a hook to run your own code when an event arrives, after the gem's bookkeeping.
380
+ The block gets the Stripe event and the `Belt::Pay::Transaction` it touched (`nil` when
381
+ the event has none):
382
+
383
+ ```ruby
384
+ # Wherever the webhook Lambda boots
385
+ Belt::Pay.on('checkout.session.completed', 'checkout.session.async_payment_succeeded') do |event, transaction|
386
+ Orders.fulfil(transaction) if transaction&.status == 'completed'
387
+ end
388
+
389
+ Belt::Pay.on('charge.refunded', 'charge.dispute.created', 'charge.dispute.closed') do |event, transaction|
390
+ Orders.revoke(transaction) if transaction && transaction.status != 'completed'
391
+ end
392
+ ```
393
+
394
+ Hooks run on every delivery, including repeats, so make them safe to run twice and go by
395
+ `transaction.status` rather than the event alone. A hook that raises fails the webhook
396
+ (HTTP 500) and Stripe sends the event again later. A hook can be registered for any
397
+ event type, including ones the gem does nothing with; add those to the endpoint with
398
+ `--webhook-events` or in the Dashboard.
319
399
 
320
400
  ### Customizing Webhook Behavior
321
401
 
322
- Override the webhook controller to add custom logic:
402
+ For anything a hook can't do, override the webhook controller:
323
403
 
324
404
  ```bash
325
405
  belt g pay --controllers
326
406
  ```
327
407
 
328
- This generates a controller in your app that inherits from the gem's default. Override individual handler methods as needed.
408
+ This generates a controller in your app that inherits from the gem's default.
329
409
 
330
410
  ## Transaction Model
331
411
 
@@ -343,14 +423,16 @@ end
343
423
 
344
424
  | Field | Description |
345
425
  |-------|-------------|
346
- | `id` | UUID primary key |
426
+ | `id` | Primary key: a UUID, or the Stripe id (Checkout Session, invoice, subscription) for rows that must exist only once |
347
427
  | `customer_id` | Your app's customer/user ID |
348
428
  | `provider` | Payment provider (`stripe`) |
349
429
  | `provider_session_id` | Stripe checkout session ID |
350
430
  | `provider_subscription_id` | Stripe subscription ID |
431
+ | `provider_payment_intent_id` | Stripe PaymentIntent ID of a paid checkout |
351
432
  | `type` | `checkout`, `subscription`, `subscription_renewal`, `refund` |
352
- | `status` | `pending`, `completed`, `failed`, `refunded`, `canceled` |
433
+ | `status` | `pending` (not paid yet), `completed` (paid), `failed`, `refunded`, `disputed`, `canceled` |
353
434
  | `amount_cents` | Amount in cents |
435
+ | `amount_refunded_cents` | How much of it has been refunded, if any |
354
436
  | `currency` | ISO currency code |
355
437
  | `metadata` | Free-form JSON metadata |
356
438
  | `created_at` | ISO 8601 timestamp |
@@ -365,12 +447,12 @@ module "pay" {
365
447
  app_name = var.app_name
366
448
  environment = var.environment
367
449
 
368
- # Set these or update secrets manually after apply
369
- # stripe_secret_key = var.stripe_secret_key
370
- # stripe_webhook_secret = var.stripe_webhook_secret
371
450
  }
372
451
  ```
373
452
 
453
+ The secret is created empty. Store the real values with `belt pay:setup <env>` after
454
+ `belt apply`; until then Belt Pay refuses to call Stripe or accept a webhook.
455
+
374
456
  ## Stripe Dashboard Setup
375
457
 
376
458
  `BELT_ENV=<env> belt pay:setup` creates the webhook endpoint and stores its signing
@@ -380,11 +462,17 @@ secret for you. To do it by hand instead:
380
462
  2. Add endpoint: `https://<your-api-domain>/pay/webhooks`
381
463
  3. Select events:
382
464
  - `checkout.session.completed`
465
+ - `checkout.session.async_payment_succeeded`
466
+ - `checkout.session.async_payment_failed`
383
467
  - `checkout.session.expired`
384
468
  - `invoice.paid`
385
469
  - `invoice.payment_failed`
386
- - `customer.subscription.deleted`
470
+ - `customer.subscription.created`
387
471
  - `customer.subscription.updated`
472
+ - `customer.subscription.deleted`
473
+ - `charge.refunded`
474
+ - `charge.dispute.created`
475
+ - `charge.dispute.closed`
388
476
  4. Copy the signing secret into your Secrets Manager secret
389
477
 
390
478
  ## Removing
@@ -48,7 +48,11 @@ module Belt
48
48
  #
49
49
  # Pass either a declared plan key (`plan:`) or a raw `price_id:`.
50
50
  # When a plan key is given, the customer's `pay_plan` is recorded so
51
- # limits/features can be checked later without a Stripe round-trip.
51
+ # limits/features can be checked later without a Stripe round-trip, but only
52
+ # once the subscription is active or trialing. A subscription that still needs
53
+ # its first payment (the usual case: status `incomplete`) grants nothing here;
54
+ # the webhook sets `pay_plan` when Stripe reports it active, and takes it back
55
+ # when the subscription ends. That needs `Belt::Pay.configuration.customer_class`.
52
56
  #
53
57
  # @param plan [Symbol, String, nil] A declared plan key (see Belt::Pay.plans)
54
58
  # @param price_id [String, nil] Provider price ID (overrides plan lookup)
@@ -59,7 +63,7 @@ module Belt
59
63
  result = Belt::Pay.subscribe(self, plan: plan, price_id: price_id,
60
64
  interval: interval, metadata: metadata)
61
65
  self.pay_subscription_id = result[:subscription_id]
62
- self.pay_plan = plan.to_s if plan
66
+ self.pay_plan = plan.to_s if plan && Subscription::ACTIVE_STATUSES.include?(result[:status].to_s)
63
67
  save(validate: false)
64
68
  result
65
69
  end
@@ -111,8 +115,13 @@ module Belt
111
115
  # @param immediately [Boolean] Cancel now (true) or at period end (false, default)
112
116
  def cancel_subscription!(immediately: false)
113
117
  Belt::Pay.cancel_subscription(self, immediately: immediately)
114
- self.pay_subscription_id = nil if immediately
115
- save(validate: false) if immediately
118
+ return unless immediately
119
+
120
+ # The plan goes with the subscription. At period end it stays until Stripe
121
+ # deletes the subscription and the webhook takes it back.
122
+ self.pay_subscription_id = nil
123
+ self.pay_plan = nil
124
+ save(validate: false)
116
125
  end
117
126
 
118
127
  # Generate a billing portal URL for self-service management.
@@ -37,7 +37,7 @@ module Belt
37
37
  provider_session_id: result[:session_id],
38
38
  type: mode == 'subscription' ? 'subscription' : 'checkout',
39
39
  status: 'pending',
40
- currency: 'usd',
40
+ currency: checkout_currency(line_items, options),
41
41
  description: "Checkout session created (#{mode})",
42
42
  metadata: metadata
43
43
  )
@@ -47,6 +47,20 @@ module Belt
47
47
 
48
48
  result
49
49
  end
50
+
51
+ private
52
+
53
+ # The currency the session will charge in, when the request says: the
54
+ # session's `currency:` or the first line item's inline price. A session
55
+ # sold by price id doesn't say, so the pending row has none and the webhook
56
+ # fills it in from the paid session.
57
+ def checkout_currency(line_items, options)
58
+ first = Array(line_items).first
59
+ price_data = first.is_a?(Hash) ? (first[:price_data] || first['price_data']) : nil
60
+ inline = price_data.is_a?(Hash) ? (price_data[:currency] || price_data['currency']) : nil
61
+ currency = options[:currency] || inline
62
+ currency&.to_s&.downcase
63
+ end
50
64
  end
51
65
  end
52
66
  end
data/lib/belt/pay/cli.rb CHANGED
@@ -14,6 +14,7 @@ module Belt
14
14
  module Pay
15
15
  class CLI
16
16
  class Error < StandardError; end
17
+ class EndpointKeyUnavailable < StandardError; end
17
18
 
18
19
  COMMANDS = %w[secrets:setup secrets:show secrets:edit].freeze
19
20
  WEBHOOK_PATH = '/pay/webhooks'
@@ -127,14 +128,30 @@ module Belt
127
128
  updated['stripe_webhook_secret'] = webhook_secret unless blank?(webhook_secret)
128
129
 
129
130
  update_secret(response, original, updated)
130
- delete_replaced_endpoints(updated['stripe_secret_key'], replaced)
131
+ delete_replaced_endpoints(replaced)
132
+ warn_unset(updated)
133
+ end
134
+
135
+ # Belt Pay refuses to call Stripe or verify a webhook with a value that is
136
+ # missing or still a placeholder, so say so while the operator is here.
137
+ def warn_unset(secret)
138
+ unset = %w[stripe_secret_key stripe_webhook_secret].select { |key| unset?(secret[key]) }
139
+ return if unset.empty?
140
+
141
+ @out.puts "Warning: #{unset.join(' and ')} #{unset.size == 1 ? 'is' : 'are'} not set in #{@secret_name}."
142
+ @out.puts 'Payments and webhooks are refused until a real value is stored; run this command again to set it.'
143
+ end
144
+
145
+ # Blank, or the placeholder older generated Terraform seeded the secret with.
146
+ def unset?(value)
147
+ blank?(value) || value.strip.match?(/_PLACEHOLDER\z/i)
131
148
  end
132
149
 
133
150
  # Returns [signing_secret, endpoints_to_delete]. Offers to create the Stripe
134
151
  # webhook endpoint (Stripe only returns a signing secret at creation time);
135
152
  # otherwise prints Dashboard instructions and prompts for the secret.
136
153
  def webhook_secret_for(api_key, existing_secret)
137
- if blank?(api_key)
154
+ if unset?(api_key)
138
155
  @out.puts 'No Stripe secret key stored yet, so the webhook endpoint cannot be created for you.'
139
156
  return [manual_webhook_secret(nil), []]
140
157
  end
@@ -144,11 +161,13 @@ module Belt
144
161
  @out.puts "Stripe account mode: #{mode}"
145
162
  @out.puts "Webhook endpoint URL: #{url || '(unknown; run `belt apply` first or pass --webhook-url)'}"
146
163
 
147
- create = !url.nil? && confirm("Create the #{mode}-mode webhook endpoint in Stripe now?", default: blank?(existing_secret))
164
+ create = !url.nil? && confirm("Create the #{mode}-mode webhook endpoint in Stripe now?", default: unset?(existing_secret))
148
165
  return [manual_webhook_secret(url, mode: mode), []] unless create
149
166
 
150
- existing = stripe_endpoints(api_key).select { |endpoint| endpoint.url == url }
167
+ @endpoint_key = api_key
168
+ existing = with_endpoint_key(mode) { |key| stripe_endpoints(key) }.select { |endpoint| endpoint.url == url }
151
169
  if existing.any?
170
+ existing.each { |endpoint| add_missing_events(endpoint, mode) }
152
171
  ids = existing.map(&:id).join(', ')
153
172
  @out.puts "Stripe already has an endpoint for this URL (#{ids}). Stripe never re-sends a signing secret,"
154
173
  @out.puts 'so setup can only replace it with a new endpoint (the old secret stops working).'
@@ -158,12 +177,33 @@ module Belt
158
177
  end
159
178
  end
160
179
 
161
- endpoint = ::Stripe::WebhookEndpoint.create(
162
- { url: url, enabled_events: webhook_events, description: "Belt Pay (#{@app_name} #{@environment})" },
163
- { api_key: api_key }
164
- )
180
+ endpoint = with_endpoint_key(mode) do |key|
181
+ ::Stripe::WebhookEndpoint.create(
182
+ { url: url, enabled_events: webhook_events, description: "Belt Pay (#{@app_name} #{@environment})" },
183
+ { api_key: key }
184
+ )
185
+ end
165
186
  @out.puts "Created #{mode}-mode webhook endpoint #{endpoint.id} for #{webhook_events.size} events."
166
187
  [endpoint.secret, existing.map(&:id)]
188
+ rescue EndpointKeyUnavailable => e
189
+ @out.puts e.message
190
+ [manual_webhook_secret(url, mode: mode), []]
191
+ end
192
+
193
+ # An endpoint made by an older Belt Pay is subscribed to fewer events than the
194
+ # handler now acts on. Adding them in place keeps the endpoint's signing secret.
195
+ def add_missing_events(endpoint, mode)
196
+ current = Array(endpoint.enabled_events)
197
+ missing = webhook_events - current
198
+ return if current.include?('*') || missing.empty?
199
+
200
+ @out.puts "Endpoint #{endpoint.id} is not subscribed to: #{missing.join(', ')}"
201
+ return unless confirm('Add them to this endpoint? (its signing secret stays the same)', default: true)
202
+
203
+ with_endpoint_key(mode) do |key|
204
+ ::Stripe::WebhookEndpoint.update(endpoint.id, { enabled_events: current | webhook_events }, { api_key: key })
205
+ end
206
+ @out.puts "Endpoint #{endpoint.id} now receives #{(current | webhook_events).size} events."
167
207
  end
168
208
 
169
209
  def manual_webhook_secret(url, mode: nil)
@@ -183,13 +223,38 @@ module Belt
183
223
  hidden_prompt('Stripe webhook signing secret [blank keeps existing]')
184
224
  end
185
225
 
186
- def delete_replaced_endpoints(api_key, ids)
226
+ def delete_replaced_endpoints(ids)
187
227
  ids.each do |id|
188
- ::Stripe::WebhookEndpoint.delete(id, {}, { api_key: api_key })
228
+ ::Stripe::WebhookEndpoint.delete(id, {}, { api_key: @endpoint_key })
189
229
  @out.puts "Deleted replaced webhook endpoint #{id}"
190
230
  end
191
231
  end
192
232
 
233
+ # The stored key is what the app runs with, so it is usually a restricted key
234
+ # (rk_) without Webhook Endpoints access. When Stripe refuses it, ask once for a
235
+ # key that can manage endpoints (an sk_ secret key, or a restricted key with
236
+ # Webhook Endpoints: Write), use it for the endpoint calls in this run only, and
237
+ # never store it.
238
+ def with_endpoint_key(mode)
239
+ yield @endpoint_key
240
+ rescue ::Stripe::PermissionError => e
241
+ raise EndpointKeyUnavailable, "Stripe refused that key too: #{e.message}" if @endpoint_key_borrowed
242
+
243
+ @out.puts 'The stored Stripe key cannot manage webhook endpoints (a restricted key usually cannot).'
244
+ @out.puts 'Setup can use a second key for this step only; it is not stored.'
245
+ key = hidden_prompt("Stripe #{mode} secret key, or restricted key with Webhook Endpoints write [not stored]")
246
+ raise EndpointKeyUnavailable, 'No key given.' if blank?(key)
247
+
248
+ key = key.strip
249
+ unless stripe_mode(key) == mode
250
+ raise EndpointKeyUnavailable, "That is a #{stripe_mode(key)}-mode key; the stored key is #{mode} mode."
251
+ end
252
+
253
+ @endpoint_key = key
254
+ @endpoint_key_borrowed = true
255
+ retry
256
+ end
257
+
193
258
  def stripe_endpoints(api_key)
194
259
  ::Stripe::WebhookEndpoint.list({ limit: 100 }, { api_key: api_key }).auto_paging_each.to_a
195
260
  end
@@ -419,7 +484,8 @@ module Belt
419
484
 
420
485
  Security:
421
486
  secrets:setup reads values without echo and sends them directly through the
422
- AWS SDK. secrets:show writes the complete secret to stdout. secrets:edit uses
487
+ AWS SDK. If the stored key is a restricted key without Webhook Endpoints
488
+ access, it asks for a second key for the endpoint step and never stores it. secrets:show writes the complete secret to stdout. secrets:edit uses
423
489
  a mode-0600 temporary file, validates JSON, and removes the file afterward.
424
490
  HELP
425
491
  end
@@ -4,7 +4,7 @@ module Belt
4
4
  module Pay
5
5
  class Configuration
6
6
  attr_accessor :provider, :secret_name, :webhook_secret_name,
7
- :table_name_prefix, :logger, :test_mode
7
+ :table_name_prefix, :logger, :test_mode, :customer_class
8
8
 
9
9
  def initialize
10
10
  @provider = :stripe
@@ -13,6 +13,18 @@ module Belt
13
13
  @table_name_prefix = "#{ENV['APP_NAME']}-#{ENV['ENVIRONMENT']}"
14
14
  @logger = nil
15
15
  @test_mode = ENV['BELT_PAY_MODE'] != 'live'
16
+ @customer_class = nil
17
+ end
18
+
19
+ # The app model that includes Belt::Pay::Billable, as set in `customer_class`
20
+ # (the class, or its name as a String so it need not be loaded yet). The
21
+ # webhook finds customers through it to keep `pay_plan` in step with the
22
+ # subscription. Nil when not configured.
23
+ # @return [Class, nil]
24
+ def customer_model
25
+ return nil if customer_class.nil?
26
+
27
+ customer_class.is_a?(String) ? Object.const_get(customer_class) : customer_class
16
28
  end
17
29
 
18
30
  def transactions_table_name
@@ -31,9 +31,11 @@ module Belt
31
31
  private
32
32
 
33
33
  # Get the raw request body for signature verification.
34
- # Stripe requires the exact raw body — not parsed JSON.
34
+ # Stripe requires the exact raw body — not parsed JSON. API Gateway sends
35
+ # it base64-encoded when isBase64Encoded is set.
35
36
  def raw_body
36
- event.dig('body') || ''
37
+ body = event.dig('body') || ''
38
+ event.dig('isBase64Encoded') ? body.unpack1('m') : body
37
39
  end
38
40
 
39
41
  def headers