Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Make general improvements to our billing docs. 

With a few wording tweaks from tabbott to the "Upgrading a Zulip
organization" section.
This commit is contained in:
Eeshan Garg 2021-12-28 20:41:45 -05:00 committed by Tim Abbott
parent afd8d5ef0c
commit 9e1fd26125
1 changed files with 90 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

133
docs/subsystems/billing.md
View File

@ -5,8 +5,9 @@ This section deals with developing and testing the billing system.
## Common setup ## Common setup
- Create a Stripe account - Create a Stripe account
- Make sure that the country of your Stripe account is set to USA when you create the account. - Make sure that the country of your Stripe account is set to USA when
- You might probably need to use a VPN for this. you create the account.
- You might need to use a VPN for this.
- Ensure that the [API version](https://stripe.com/docs/api/versioning) of - Ensure that the [API version](https://stripe.com/docs/api/versioning) of
your Stripe account is same as `STRIPE_API_VERSION` defined in your Stripe account is same as `STRIPE_API_VERSION` defined in
`corporate/lib/stripe.py`. You can upgrade to a higher version from `corporate/lib/stripe.py`. You can upgrade to a higher version from
@ -17,71 +18,117 @@ This section deals with developing and testing the billing system.
## Manual testing ## Manual testing
Manual testing involves testing the various flows like upgrade, card change etc manually through the browser. This is the bare minimum testing that you need to do when you review a PR or is working on adding a new feature. Manual testing involves testing the various flows like upgrade, card change,
etc. through the browser. This is the bare minimum testing that you need to
do when you review a billing PR or when you are working on adding a new
feature to billing.
### Setup ### Setup
Apart from the common setup mentioned above, you also need to setup your dev environment to receive webhook events Apart from the common setup mentioned above, you also need to setup your
from Stripe. development environment to receive webhook events from Stripe.
- Install Stripe CLI by following the instructions at <https://stripe.com/docs/webhooks/test> in your machine locally. - Install the Stripe CLI locally by following the instructions
- Login to Stripe CLI by `stripe login` [here](https://stripe.com/docs/webhooks/test).
- Run run the Stripe CLI to forward all the Stripe webhook events to our billing system webhook endpoint. - Login to Stripe CLI using the command `stripe login`.
- You can get Stripe CLI to forward all Stripe webhook events to our local
webhook endpoint using the following command:
`stripe listen --forward-to http://localhost:9991/stripe/webhook/` `stripe listen --forward-to http://localhost:9991/stripe/webhook/`
- Wait for the `stripe listen` command in the previous step to output the webhook signing secret. - Wait for the `stripe listen` command in the previous step to output the
- The signing secret would be used by our billing system to verify that the events that are sent to our webhook endpoint is sent by Stripe and not by an intruder. In production, there is no Stripe CLI, so the step for configuring this is a bit different. See the production section for more details. webhook signing secret.
- Copy the webhook signing secret and set it as `stripe_webhook_endpoint_secret` in `zproject/dev-secrets.conf`. - The signing secret would be used by our billing system to verify that
- The billing system is now all set to receive webhook events from Stripe. the events received by our webhook endpoint are sent by Stripe and not
by an intruder. In production, there is no Stripe CLI, so the step for
configuring this is a bit different. See Stripe's documentation on
[taking webhooks live](https://stripe.com/docs/webhooks/go-live) for
more details.
- Copy the webhook signing secret and set it as `stripe_webhook_endpoint_secret`
in `zproject/dev-secrets.conf`.
- Your development environment is now all set to receive webhook events from
Stripe.
### Test card numbers ### Test card numbers
Stripe provides various card numbers to test for specific responses from Stripe. Thee commonly used ones are mentioned in the documentation below wherever appropriate. The full list is available at <https://stripe.com/docs/testing> Stripe provides various card numbers to test for specific responses from Stripe.
The most commonly used ones are mentioned in below wherever appropriate. The full
list is available [here](https://stripe.com/docs/testing#cards).
### Flows to test ### Flows to test
These are the flows that you can test manually from the browser. There are various flows that you can test manually from the browser. Here are
a few things to keep in mind while conducting these tests manually:
- Upgrade a Zulip organization - The flows work from start to end as expected.
- Flows to test - We show appropriate success and error messages to users.
- When free trial is not enabled, ie `FREE_TRIAL_DAYS` is not set to any value in `dev_settings.py`. Free trial is rarely enabled. So when you are manually testing make sure that `FREE_TRIAL_DAYS` is not set to any value unless you want to test the free trial functionality. - Charges are made or not made (free trial) as expected. You can verify this
- Using a valid card number like `4242 4242 4242 4242` through the Stripe dashboard. However, this is not super important since
- Using an invalid card number like `4000000000000341` which will add the card to the Customer account but charge fails. our automated tests take care of such granular testing for us.
- Retry the upgrade by adding a new card by clicking on the retry upgrade link. - Renewals cannot be tested manually and are tested in our automated tests.
- Retry the upgrade from scratch.
- Upgrade an organization when free trial is enabled. You can set `FREE_TRIAL_DAYS` to a number greater than `0` in `dev_settings.py` to enable free trial. This is a setting that is not commonly used. #### Upgrading a Zulip organization
- There are two different flows to test here.
- Right after the organization is created by following the instructions in the onboarding page. Here are some flows to test when upgrading a Zulip organization:
- Make sure that after the upgrade is complete the billing page shows a link to go to the organization.
- By manually going to billing page and upgrading the organization. - When free trials are not enabled, i.e. `FREE_TRIAL_DAYS` is not set
- What to test? to any value in `dev_settings.py` (aka the default). You can
- The flows work from start to end as expected. double-check that the setting is disabled by verifying
- We show appropriate success and error messages to users. `./scripts/get-django-setting FREE_TRIAL_DAYS` returns 0.
- Charges are made or not made(free trial) as expected. You can check this through the Stripe dashboard. Though not that super important since we check these in automated tests anyway.
- Testing that involves renewal and all is not possible through manual testing. It is taken care of in backend tests. - Using a valid card number like `4242 4242 4242 4242`.
- Change the card - Using an invalid card number like `4000000000000341`, which will add the card
- Flows to test to the customer account but the charge will fail.
- Go to the billing page of an organization that is upgraded using card. Then try changing the card to another valid card like `5555555555554444`. - Retry the upgrade after adding a new card by clicking on the retry upgrade
- Make sure that the flow completes without any error and the new card details is now shown in the billing page instead of the old card. link.
- You can also try adding a card number that results in it getting attached to the customer but charges fails. But to test that you need pending invoices since we try to pay pending invoices when the card is changed. It's taken care of in backend tests so it's not super necessary to test manually. - Retry the upgrade from scratch.
- Upgrade an organization when free trials are enabled. The free
trials setting has been (possibly permanently) disabled in
production for some time now, so testing this code path is not a
priority. You can set `FREE_TRIAL_DAYS` to any number greater than
`0` in `dev_settings.py` to enable free trials. There are two
different flows to test here:
- Right after the organization is created by following the instructions in the
onboarding page.
- Make sure that after the upgrade is complete the billing page shows a link to
go to the organization.
- By manually going to the `/billing` page and upgrading the organization.
#### Changing the card
The following flow should be tested when updating cards in our billing system:
- Go to the `/billing` page of an organization that has already been upgraded
using a card. Try changing the card to another valid card such as
`5555555555554444`.
- Make sure that the flow completes without any errors and that the new card
details are now shown on the billing page instead of the older card.
- You can also try adding a card number that results in it getting attached to
the customer's account but charges fail. However, to test this, you need pending
invoices since we try to charge for pending invoices when the card is updated.
This is tested in our automated tests so it is not strictly necessary to test this
manually.
## Upgrading Stripe API versions ## Upgrading Stripe API versions
Stripe makes pretty regular updates to their API. The process for upgrading Stripe makes pretty regular updates to their API. The process for upgrading
our code is: our code is:
- Go to <https://dashboard.stripe.com/developers> in your Stripe account. - Go to the [Stripe Dashboard](https://dashboard.stripe.com/developers) in
your Stripe account.
- Upgrade the API version. - Upgrade the API version.
- Run `tools/test-backend --generate-stripe-fixtures` - Run `tools/test-backend --generate-stripe-fixtures`.
- Fix any failing tests, and manually look through `git diff` to understand - Fix any failing tests, and manually look through `git diff` to understand
the changes. Ensure that there are no material changes. the changes. Ensure that there are no material changes.
- Update the value of `STRIPE_API_VERSION` in `corporate/lib/stripe.py`. - Update the value of `STRIPE_API_VERSION` in `corporate/lib/stripe.py`.
- Commit the diff, and open a PR. - Commit the changes, and open a PR.
- Ask to Tim to go to <https://dashboard.stripe.com/developers> in the - Ask Tim Abbott to upgrade the API version on the
zulipchat Stripe account, and upgrade the API version there. [Stripe Dashboard](https://dashboard.stripe.com/developers) for Zulip's official
Stripe account.
We currently aren't set up to do version upgrades where there are breaking We currently aren't set up to do version upgrades where there are breaking
changes, though breaking changes should be unlikely given the parts of the changes, though breaking changes should be unlikely given the parts of the
product we use. The main remaining work for handling breaking version upgrades product we use. The main remaining work for handling breaking version upgrades
is ensuring that we set the stripe version in our API calls. is ensuring that we set the stripe version in our API calls.
<https://stripe.com/docs/upgrades#how-can-i-upgrade-my-api> has some Stripe's documentation for
additional information. [Upgrading your API version](https://stripe.com/docs/upgrades#how-can-i-upgrade-my-api)
has some additional information.