bullet_train 1.17.0 → 1.17.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/docs/billing/stripe.md +184 -39
- data/lib/bullet_train/version.rb +1 -1
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 303bc16a62d52b4427268c44fc6825975d3655eed8d0231e6001609b7cb273cc
|
|
4
|
+
data.tar.gz: 710a00d08cf479ee808adee240d85e061d8ed3d826127baeb4127cd14ae1b6ad
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 1e653280d2fd3d1df048fa13cbd6751fe690d6802b7cff729c3213653b85960d58c0589c63be9ad6d396efe15ec70f1c5b1f5495f85e4eb7472057955d3b5ac2
|
|
7
|
+
data.tar.gz: 73e6d04f7059f4645903e2c73ecaf4ebdf889bae3754bc07d4b619192fba93f3df9aac10a9d0ada6ccf95c56cdd04c0ce13fd0ba8d73eabc061730529f7d1a0a
|
data/docs/billing/stripe.md
CHANGED
|
@@ -4,13 +4,13 @@ When you're ready to start billing customers for the product you've created with
|
|
|
4
4
|
|
|
5
5
|
We also provide a Stripe-specific adapter package with support for auto-configuring those products and prices in your Stripe account. It also takes advantage of completely modern Stripe workflows, like allowing customers to purchase your product with Stripe Checkout and later manage their subscription using Stripe Billing's customer portal. It also automatically handles incoming Stripe webhooks as well, to keep subscription state in your application up-to-date with activity that has happened on Stripe's platform.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Option A: Using the Paid Bullet Train Pro gem via Gemfury
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
### A.1. Purchase Bullet Train Billing for Stripe
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
First, [purchase Bullet Train Billing for Stripe](https://buy.stripe.com/28o8zg4dBbrd59u7sM). Once you've completed this process, you'll be issued a private token for the Bullet Train Pro package server. (This process is currently completed manually, so please be patient.)
|
|
12
12
|
|
|
13
|
-
### 2.
|
|
13
|
+
### A.2. Add the Private Ruby Gems
|
|
14
14
|
|
|
15
15
|
You'll need to specify both Ruby gems in your `Gemfile`, since we have to specify a private source for both:
|
|
16
16
|
|
|
@@ -21,13 +21,50 @@ source "https://YOUR_TOKEN_HERE@gem.fury.io/bullettrain" do
|
|
|
21
21
|
end
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
-
###
|
|
24
|
+
### A.3. Bundle Install
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
bundle install
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
**Proceed to the [Installation Instructions](#installation-instructions) section below**
|
|
31
|
+
|
|
32
|
+
## Option B: Using the Open Source version of Bullet Train Billing via git
|
|
33
|
+
|
|
34
|
+
### B.1. Add the Git Repositories
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
# Below the comment labelled YOUR GEMS in your Gemfile
|
|
38
|
+
gem "bullet_train-billing", git: "https://github.com/bullet-train-pro/bullet_train-billing.git"
|
|
39
|
+
gem "bullet_train-billing-stripe", git: "https://github.com/bullet-train-pro/bullet_train-billing-stripe.git"
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### B.2. Bundle Install
|
|
25
43
|
|
|
26
44
|
```
|
|
27
45
|
bundle install
|
|
28
46
|
```
|
|
29
47
|
|
|
30
|
-
|
|
48
|
+
You should expect to see the following output when bundler runs
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
Fetching https://github.com/bullet-train-pro/bullet_train-billing-stripe.git
|
|
52
|
+
Fetching https://github.com/bullet-train-pro/bullet_train-billing.git
|
|
53
|
+
Fetching gem metadata from https://rubygems.org/........
|
|
54
|
+
<all of your normal gems>
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
**Proceed to the [Installation Instructions](#installation-instructions) section below**
|
|
58
|
+
|
|
59
|
+
## Installation Instructions
|
|
60
|
+
|
|
61
|
+
### Prerequisites
|
|
62
|
+
|
|
63
|
+
In order to complete some of the next steps you will need to have the following tools installed and configured for your system:
|
|
64
|
+
- [Stripe CLI](https://docs.stripe.com/stripe-cli#install)
|
|
65
|
+
- [ngrok](https://ngrok.com/downloads)
|
|
66
|
+
|
|
67
|
+
### 1. Copy Database Migrations
|
|
31
68
|
|
|
32
69
|
Use the following two commands on your shell to copy the required migrations into your local project:
|
|
33
70
|
|
|
@@ -40,35 +77,35 @@ Note this is different than how many Rails engines ask you to install migrations
|
|
|
40
77
|
|
|
41
78
|
<aside><small>TODO Let's create a `rake bullet_train:billing:stripe:install` task.</small></aside>
|
|
42
79
|
|
|
43
|
-
### 2.
|
|
80
|
+
### 2. Run Migrations
|
|
44
81
|
|
|
45
82
|
```
|
|
46
83
|
rake db:migrate
|
|
47
84
|
```
|
|
48
85
|
|
|
49
|
-
|
|
86
|
+
### 3. Configure Your Products
|
|
50
87
|
|
|
51
88
|
Bullet Train defines subscription plans and pricing options in `config/models/billing/products.yml` and defines the translatable elements of these plans in `config/locales/en/billing/products.en.yml`. We recommend just getting started with these plans to ensure your setup is working before customizing the attributes of these plans.
|
|
52
89
|
|
|
53
|
-
|
|
90
|
+
### 4. Configure Stripe
|
|
54
91
|
|
|
55
|
-
|
|
92
|
+
#### 4.1. Create API Keys with Stripe
|
|
56
93
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
94
|
+
- Create a Stripe account if you don't already have one.
|
|
95
|
+
- Visit [https://dashboard.stripe.com/test/apikeys](https://dashboard.stripe.com/test/apikeys).
|
|
96
|
+
- Create a new secret key.
|
|
60
97
|
|
|
61
98
|
**Note:** By default we're linking to the "test mode" page for API keys so you can get up and running in development. When you're ready to deploy to production, you'll have to repeat this step and toggle the "test mode" option off to provision real API keys for live payments.
|
|
62
99
|
|
|
63
|
-
|
|
100
|
+
#### 4.2. Configure Stripe API Keys Locally
|
|
64
101
|
|
|
65
102
|
Edit `config/application.yml` and add your new Stripe secret key to the file:
|
|
66
103
|
|
|
67
104
|
```yaml
|
|
68
|
-
STRIPE_SECRET_KEY:
|
|
105
|
+
STRIPE_SECRET_KEY: sk_test_aBunchOfRandomCharacters
|
|
69
106
|
```
|
|
70
107
|
|
|
71
|
-
|
|
108
|
+
#### 4.3. Populate Stripe with Locally Configured Products
|
|
72
109
|
|
|
73
110
|
Before you can use Stripe Checkout or Stripe Billing's customer portal, your locally configured products will have to be created on Stripe as well. To accomplish this, you can have all locally defined products automatically created on Stripe via API by running the following:
|
|
74
111
|
|
|
@@ -76,62 +113,170 @@ Before you can use Stripe Checkout or Stripe Billing's customer portal, your loc
|
|
|
76
113
|
rake billing:stripe:populate_products_in_stripe
|
|
77
114
|
```
|
|
78
115
|
|
|
79
|
-
|
|
116
|
+
#### 4.4. Add Additional Environment Variables
|
|
80
117
|
|
|
81
|
-
The script in the previous step will output some additional environment variables you need to copy into `config/application.yml`.
|
|
82
118
|
|
|
119
|
+
The script from the previous step will output some additional environment variables you need to copy into `config/application.yml`. It will look similar to the following:
|
|
83
120
|
|
|
84
|
-
|
|
121
|
+
```
|
|
122
|
+
OK, put the following in `config/application.yml` or wherever you configure your environment values:
|
|
123
|
+
|
|
124
|
+
STRIPE_PRODUCT_BASIC_MONTHLY_2025_PRICE_ID: price_1QpbQSKKAAAAAAAAAAAAAAAA
|
|
125
|
+
STRIPE_PRODUCT_BASIC_ANNUAL_2025_PRICE_ID: price_1QpbQSKKBBBBBBBBBBBBBBBB
|
|
126
|
+
STRIPE_PRODUCT_PRO_ANNUAL_2025_PRICE_ID: price_1QpbQSKKCCCCCCCCCCCCCCCC
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### 5. Wire Up Webhooks
|
|
85
130
|
|
|
86
131
|
Basic subscription creation will work without receiving and processing Stripe's webhooks. However, advanced payment workflows like SCA payments and customer portal cancelations and plan changes require receiving webhooks and processing them.
|
|
87
132
|
|
|
88
|
-
|
|
133
|
+
#### 5.1. Ensure HTTP Tunneling is Enabled
|
|
89
134
|
|
|
90
135
|
Although Stripe provides free tooling for receiving webhooks in your local environment, the officially supported mechanism for doing so in Bullet Train is using [HTTP Tunneling with ngrok](/docs/tunneling.md). This is because we provide support for many types of webhooks across different platforms and packages, so we already need to have ngrok in play.
|
|
91
136
|
|
|
92
137
|
Ensure you've completed the steps from [HTTP Tunneling with ngrok](/docs/tunneling.md), including updating `BASE_URL` in `config/application.yml` and restarting your Rails server.
|
|
93
138
|
|
|
94
|
-
|
|
139
|
+
#### 5.2. Enable Stripe Webhooks
|
|
140
|
+
|
|
141
|
+
- Visit [https://dashboard.stripe.com/test/webhooks/create](https://dashboard.stripe.com/test/webhooks/create).
|
|
142
|
+
- Use the default "add an endpoint" form.
|
|
143
|
+
- Set "endpoint URL" to `https://YOUR-SUBDOMAIN.ngrok.io/webhooks/incoming/stripe_webhooks`.
|
|
144
|
+
- Under "select events to listen to" choose "select all events" and click "add events".
|
|
145
|
+
- Finalize the creation of the endpoint by clicking "add endpoint".
|
|
95
146
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
- Set "endpoint URL" to `https://YOUR-SUBDOMAIN.ngrok.io/webhooks/incoming/stripe_webhooks`.
|
|
99
|
-
- Under "select events to listen to" choose "select all events" and click "add events".
|
|
100
|
-
- Finalize the creation of the endpoint by clicking "add endpoint".
|
|
147
|
+
*Note:* Depending on your region and when your Stripe account was created, you may be presented with a different admin interface.
|
|
148
|
+
For more details on creating webhooks, please refer to the [Stripe Workbench documentation](https://docs.stripe.com/workbench#webhooks)
|
|
101
149
|
|
|
102
|
-
|
|
150
|
+
#### 5.3. Configure Stripe Webhooks Signing Secret
|
|
103
151
|
|
|
104
152
|
After creating the webhook endpoint, click "reveal" under the heading "signing secret". Copy the `whsec_...` value into your `config/application.yml` like so:
|
|
105
153
|
|
|
106
154
|
```yaml
|
|
107
|
-
STRIPE_WEBHOOKS_ENDPOINT_SECRET:
|
|
155
|
+
STRIPE_WEBHOOKS_ENDPOINT_SECRET: whsec_aBunchOfRandomCharacters
|
|
108
156
|
```
|
|
109
157
|
|
|
110
|
-
|
|
158
|
+
#### 5.4. Test Sample Webhook Delivery
|
|
111
159
|
|
|
112
160
|
- Restart your Rails server with `rails restart`.
|
|
113
|
-
- Trigger a test webhook just to
|
|
161
|
+
- Trigger a test webhook using the Stripe CLI (for instance `stripe trigger payment_intent.succeeded`). You just want to make sure that it results in an HTTP status code of 201.
|
|
162
|
+
|
|
163
|
+
### 6. Test Creating a Subscription
|
|
114
164
|
|
|
115
|
-
|
|
165
|
+
Bullet Train comes preconfigured with a "freemium" plan, which will keep new and existing accounts working as normal. A new **billing** menu item will appear in the **Team** menu.
|
|
116
166
|
|
|
117
|
-
|
|
167
|
+
From the Subscriptions page, click the "Upgrade" button and select one of the two plans presented.
|
|
118
168
|
|
|
119
|
-
|
|
169
|
+
Confirm that you are in the **Test Mode** and fill out the payment information. You can test out different kinds of scenarios which are covered by [Stripes testing documentation](https://docs.stripe.com/testing).
|
|
120
170
|
|
|
121
|
-
|
|
171
|
+
To test a successful purchase use `4242 4242 4242 4242` for the credit card number. Fill out the rest of the payment form and click the "Subscribe" button
|
|
122
172
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
-
|
|
173
|
+
### 7. Configure Stripe Billing's Customer Portal
|
|
174
|
+
|
|
175
|
+
- Visit https://dashboard.stripe.com/test/settings/billing/portal
|
|
176
|
+
- Click the "Activate test link" button
|
|
177
|
+
- Under the "Subscriptions" section turn on:
|
|
178
|
+
- Customers can switch plans
|
|
179
|
+
- Customers can change quantity of their plan (if appropriate)
|
|
180
|
+
- Just below the two toggles will be a section noting "You have not added any products". In the search box below it, add all of your actively available plans.
|
|
126
181
|
|
|
127
182
|
This "products" list is what Stripe will display to users as upgrade and downgrade options in the customer portal. You shouldn't list any products here that aren't properly configured in your Rails app, otherwise the resulting webhook will fail to process. If you want to stop offering a plan, you should remove it from this list as well.
|
|
128
183
|
|
|
129
|
-
|
|
184
|
+
### 8. Finalize Webhooks Testing by Managing a Subscription
|
|
130
185
|
|
|
131
186
|
In the same account where you created your first test subscription, go into the "billing" menu and click "manage" on that subscription. This will take you to the Stripe Billing customer portal.
|
|
132
187
|
|
|
133
188
|
Once you're in the customer portal, you should test upgrading, downgrading, and canceling your subscription and clicking "⬅ Return to {Your Application Name}" in between each step to ensure that each change you're making is properly reflected in your Bullet Train application. This will let you know that webhooks are being properly delivered and processed and all the products in both systems are properly mapped in both directions.
|
|
134
189
|
|
|
190
|
+
#### 8.1 Understanding the Product configuration yml
|
|
191
|
+
|
|
192
|
+
Your `products.yml` should have a structure similar to the following:
|
|
193
|
+
|
|
194
|
+
```yaml
|
|
195
|
+
free:
|
|
196
|
+
limits:
|
|
197
|
+
memberships:
|
|
198
|
+
count: 1
|
|
199
|
+
enforcement: hard
|
|
200
|
+
scaffolding/absolutely_abstract/creative_concepts:
|
|
201
|
+
count: 0
|
|
202
|
+
enforcement: hard
|
|
203
|
+
basic:
|
|
204
|
+
price: basic_2021
|
|
205
|
+
image: "streamline-icon-idea-message.png"
|
|
206
|
+
limits:
|
|
207
|
+
memberships:
|
|
208
|
+
count: 3
|
|
209
|
+
enforcement: hard
|
|
210
|
+
scaffolding/absolutely_abstract/creative_concepts:
|
|
211
|
+
count: null
|
|
212
|
+
prices:
|
|
213
|
+
basic_2021:
|
|
214
|
+
amount: 1000
|
|
215
|
+
currency: USD
|
|
216
|
+
duration: 1
|
|
217
|
+
interval: month
|
|
218
|
+
quantity: memberships
|
|
219
|
+
basic_2021:
|
|
220
|
+
amount: 10000
|
|
221
|
+
currency: USD
|
|
222
|
+
duration: 1
|
|
223
|
+
interval: month
|
|
224
|
+
quantity: memberships
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
Each root level entry (i.e. `free` and `basic`) are the types of subscriptions that will be available to your customers. Each subscription has the following:
|
|
228
|
+
|
|
229
|
+
- `price`: A unique identifer for this price
|
|
230
|
+
- `image`: The product image from `assets/images/products` that is presented to the buyer from the new subscription page
|
|
231
|
+
- `limits`: The resource constraints on what a user can do on this subscription. To learn more, refer to [Bullet Train Usage Limits](/docs/billing/usage.md)
|
|
232
|
+
- `prices`: The list of pricing options for this product, where each price will have the following:
|
|
233
|
+
- `amount`: The cost of the product in *cents*
|
|
234
|
+
- `currency`: The currency that the customer will be billed in (i.e. EUR for Euros, CAD for Canadian Dollars)
|
|
235
|
+
- `duration`: Used for subscriptions to define how many units the subscription is valid for
|
|
236
|
+
- `interval`: The unit of time of the subscription (i.e. day, month, year)
|
|
237
|
+
- `quantity`: The relation used to determine how many of this product are being ordered.
|
|
238
|
+
- If your pricing model charges per seat, this should be set to `memberships`
|
|
239
|
+
- If you are charging a fixed rate, this field should be `1`
|
|
240
|
+
- `highlight`: When set to true, this product will *pop out* from the other product options that are presented to the user
|
|
241
|
+
|
|
242
|
+
There exists a relationship between `duration` and `interval` that is used to determine how often a customers card is billed. For example, if you wanted to bill a
|
|
243
|
+
customer once every three months you'd have the following configuration:
|
|
244
|
+
|
|
245
|
+
```yaml
|
|
246
|
+
duration: 3
|
|
247
|
+
interval: month
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
For full details on product pricing, please refer to the [Product and Prices Overview Documentation on Stripe](https://docs.stripe.com/products-prices/overview)
|
|
251
|
+
|
|
252
|
+
#### 8.2 Replacing Test Products with your own
|
|
253
|
+
|
|
254
|
+
- Before making any changes, be sure to cancel any subscriptions
|
|
255
|
+
- Go to https://dashboard.stripe.com/test/products and find the test products that were added
|
|
256
|
+
- Click on the "..." menu to the right and click "Archive product"
|
|
257
|
+
- Remove the product keys from `config/application.yml`
|
|
258
|
+
- Replace the boilerplate product entries in `config/models/billing/products.yml`
|
|
259
|
+
- A `free` plan **must exist** in order for your application to continue to work without issue
|
|
260
|
+
|
|
261
|
+
#### 8.3 Customizing the Pricing Page content
|
|
262
|
+
|
|
263
|
+
The pricing page and pricing page translations are located within the `bullet_train-billing` gem. If you need to customize either of those you will need to eject them. For more details on ejecting components from Bullet Train gems, refer to the section on [Indirection](https://bullettrain.co/docs/indirection).
|
|
264
|
+
|
|
265
|
+
**Ejecting the pricing page**
|
|
266
|
+
|
|
267
|
+
```
|
|
268
|
+
bin/resolve bullet_train-billing/app/views/account/billing/subscriptions/new.html.erb --eject
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
**Ejecting the subscriptions translations**
|
|
272
|
+
|
|
273
|
+
Subscription translations can be retrieved directly [from github](https://github.com/bullet-train-pro/bullet_train-billing/blob/main/config/locales/en/billing/subscriptions.en.yml) and copied into `config/locales/en/billing`
|
|
274
|
+
|
|
275
|
+
```
|
|
276
|
+
`curl -o config/locales/en/billing/subscriptions.en.yml https://raw.githubusercontent.com/bullet-train-pro/bullet_train-billing/refs/heads/main/config/locales/en/billing/subscriptions.en.yml`
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
|
|
135
280
|
## 9. Rinse and Repeat Configuration Steps for Production
|
|
136
281
|
|
|
137
282
|
As mentioned earlier, all of the links we provided for configuration steps on Stripe were linked to the "test mode" on your Stripe account. When you're ready to launch payments in production, you will need to:
|
|
@@ -145,4 +290,4 @@ As mentioned earlier, all of the links we provided for configuration steps on St
|
|
|
145
290
|
|
|
146
291
|
## 10. You should be done!
|
|
147
292
|
|
|
148
|
-
[Let us know on Discord](http://discord.gg/bullettrain) if any part of this guide was not clear or could be improved!
|
|
293
|
+
[Let us know on Discord](http://discord.gg/bullettrain) if any part of this guide was not clear or could be improved!
|
data/lib/bullet_train/version.rb
CHANGED