Stripe docs improvements (pay-rails#1007)

* Some improvements for Stripe docs * Update 5_webhooks.md --------- Co-authored-by: Chris Oliver <[email protected]>
tumes · Aug 6, 2024 · 5391002 · 5391002
1 parent 8fff5e3
commit 5391002
Show file tree

Hide file tree

Showing 5 changed files with 36 additions and 6 deletions.
diff --git a/docs/2_configuration.md b/docs/2_configuration.md
@@ -73,6 +73,14 @@ Pay will also check environment variables for API keys:
 * `PADDLE_CLASSIC_PUBLIC_KEY_BASE64`
 * `PADDLE_CLASSIC_ENVIRONMENT`
 
+> [!TIP]
+>
+> Are you using any of these payment processors for the very first time? Take a look at their respective configuration doc for generating these keys:
+>
+> - [Stripe](/docs/stripe/2_credentials.md)
+> - [Paddle Billing](/docs/paddle_billing/1_overview.md#configuration)
+> - [Paddle Classic](/docs/paddle_classic/1_overview.md#paddle-public-key)
+
 #### STRIPE_WEBHOOK_RECEIVE_TEST_EVENTS (Default to TRUE)
 As per the guidance from https://support.stripe.com/questions/connect-account-webhook-configurations: "When a connected account is linked solely in live mode to your platform, both live and test events are sent to your live Connect Webhook Endpoint." Therefore, you can set this to false if you wish to receive only live events in Production.
 

diff --git a/docs/7_webhooks.md b/docs/7_webhooks.md
@@ -16,7 +16,7 @@ Pay comes with a bunch of different webhook handlers built-in. Each payment proc
 
 Webhooks are automatically mounted at `/pay/webhooks/:provider`
 
-To configure webhooks on your payment processor, use the following URLs (with your domain):
+To configure webhooks on your payment processor, use the following URLs while replacing `example.org` with your own domain:
 
 * **Stripe** - `https://example.org/pay/webhooks/stripe`
 * **Braintree** - `https://example.org/pay/webhooks/braintree`

diff --git a/docs/stripe/2_credentials.md b/docs/stripe/2_credentials.md
@@ -4,11 +4,15 @@ To use Stripe with Pay, you'll need to add your API keys and Signing Secret(s) t
 
 ### API keys
 
-You can find your Stripe private (secret) and pubilc (publishable) keys in the [Stripe Dashboard](https://dashboard.stripe.com/test/apikeys).
+You can create (or find) your Stripe private (secret) and public (publishable) keys in the [Stripe Dashboard](https://dashboard.stripe.com/test/apikeys).
+
+>[!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 toggle the "test mode" option off and repeat all steps again for live payments.
 
 ### Signing secrets
 
-Webhooks use signing secrets to verify the webhook was sent by Stripe. You can find these on your Stripe Dashboard or the Stripe CLI.
+Webhooks use signing secrets to verify the webhook was sent by Stripe. Check out [Webhooks](/docs/stripe/5_webhooks.md#enable-stripe-webhooks) doc for detailed instructions on where/how to get these.
 
 #### Dashboard
 

diff --git a/docs/stripe/5_webhooks.md b/docs/stripe/5_webhooks.md
@@ -1,14 +1,29 @@
 # Stripe Webhooks
 
-### Development
+Pay listens to Stripe's webhooks to keep the local payments data in sync. 
+
+For development, we use the Stripe CLI to forward webhooks to our local server. 
+In production, webhooks are directly sent directly to our app's domain.
+
+## Development webhooks with the Stripe CLI
 
 You can use the [Stripe CLI](https://stripe.com/docs/stripe-cli) to test and forward webhooks in development.
 
 ```bash
+stripe login
 stripe listen --forward-to localhost:3000/pay/webhooks/stripe
 ```
 
-### Events
+## Production webhooks for Stripe
+
+1. Visit https://dashboard.stripe.com/webhooks/create.
+2. Use the default "Add an endpoint" form.
+3. Set "endpoint URL" to https://example.org/pay/webhooks/stripe (Replace `example.org` with your domain)
+4. Under "select events to listen to" choose "Select all events" and click "Add events". Or if you want to listen to specific events, check out [events we listen to](#events).
+5. Finalize the creation of the endpoint by clicking "Add endpoint".
+6. After creating the webhook endpoint, click "Reveal" under the heading "Signing secret". Copy the `whsec_... ` value to wherever you have configured your keys for Stripe as instructed in [Credentials](/docs/2_configuration.md#credentials) section under Configurations doc.
+
+## Events
 
 Pay requires the following webhooks to properly sync charges and subscriptions as they happen.
 

diff --git a/docs/stripe/8_stripe_checkout.md b/docs/stripe/8_stripe_checkout.md
@@ -2,7 +2,10 @@
 
 [Stripe Checkout](https://stripe.com/docs/payments/checkout) allows you to simply redirect to Stripe for handling payments. The main benefit is that it's super fast to setup payments in your application, they're SCA compatible, and they will get improved automatically by Stripe.
 
-📝 **Warning**: You need to configure webhooks before using Stripe Checkout otherwise your application won't be updated with the correct data.
+> [!WARNING]
+> You need to configure webhooks before using Stripe Checkout otherwise your application won't be updated with the correct data.
+>
+> See [Webhooks](/docs/stripe/5_webhooks.md) section on how to do that.
 
 ![stripe checkout example](https://i.imgur.com/nFsCBCK.gif)