Connect Stripe

Stripe is the firm that takes the card payment. Your website never sees a card number. The buyer types the card into a Stripe form, on your own web address, and Stripe sends the money to your bank.

The Stripe account is yours. It is in your business name, and the money goes to your bank. So you set this up yourself. It takes one sitting, and you do it once.

Here is the whole job. You copy two keys out of Stripe and paste them into the panel. Then you click one button, and your website sets up the link back from Stripe on its own.

Before you start

You need a Stripe account in your own business name. Making one takes about twenty minutes. Stripe asks for your bank details and proof of who you are.

Have the panel open in one browser tab and Stripe in another. You will move between them.

Stripe moves its screens around now and then. If a menu name here does not match what you see, type it into Stripe’s own search box.

Step 1. Sign in to Stripe

Go to https://dashboard.stripe.com and sign in. If you have no account yet, create one there first.

Start in test mode. Stripe has a switch for it. Test mode uses fake cards, so nothing is charged while you try things out. Test mode first says how to move to real money later.

Step 2. Copy the publishable key

1. In Stripe, click Developers, then API keys.
2. Find the row called Publishable key.
3. Copy the value. It starts with pk_.

This key is safe. It is the only one that reaches a visitor’s browser.

Step 3. Make a restricted key

The second key can charge cards. Read the warning first.

1. On the same API keys screen, click Create restricted key.
2. Give it a name, such as Website.
3. Set each row as in the table on Stripe key and sales tax. Leave every other row at None.
4. Click Create key, then copy the value. It starts with rk_.

Do not skip Webhook Endpoints. It is what lets your website set up the link back from Stripe in step 5. Without it, that step cannot work.

Step 4. Paste the two keys into the panel

1. Go to Plugins, then Commerce.
2. Click the Settings tab.
3. Click Stripe keys → at the top. A short form opens.
4. Paste the pk_ value into Stripe publishable key.
5. Paste the rk_ value into Stripe secret key.
6. Leave Stripe webhook signing secret empty. Step 5 fills it in for you.
7. Click Save Settings.

The secret boxes show dots from now on, not the key. That is normal. To change one, type the new key over the dots and save again.

Step 5. Create the webhook

A webhook is a message from Stripe to your website. It is how your site hears that a payment went through. With no webhook, money moves and no order appears.

You do not build it by hand. Your website does it with your new key.

1. Go back to Plugins, then Commerce, and click the Settings tab.
2. Near the top, click View Stripe connection information to open it. It ends in needs attention.
3. A warning box reads This store has no Stripe webhook, so no order will ever be created.
4. Click the button in that box. It starts with Create the endpoint at, then your web address.
5. A message reads “Stripe webhook is now sending every event this store needs.”

The warning box goes away. In its place, one quiet line starts with Stripe webhook: sending every event this store needs. That line is how you know it worked.

If the button shows an error that names a setting on your website, the webhook was not made. Contact us. See the box at the end of this page.

Your website also saved the webhook’s secret code for you. Stripe only shows that code once, which is why the button is the safe way to do this.

The eighteen events

The webhook sends eighteen kinds of message. You never pick them yourself. The button does. They are listed here so you can check them in Stripe, under Developers, then Webhooks.

• checkout.session.completed
• checkout.session.async_payment_succeeded
• checkout.session.async_payment_failed
• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• invoice.paid
• invoice.payment_failed
• invoice.created
• charge.refunded
• refund.updated
• checkout.session.expired
• payment_intent.succeeded
• payment_intent.processing
• payment_intent.payment_failed
• payment_intent.canceled
• setup_intent.succeeded
• charge.dispute.created

If the Settings tab shows a different warning

The Settings tab checks the webhook each time you open it. It names the problem and the fix.

Warning box says	What to do
Your Stripe webhook is not sending every event this store needs	Click Add these events. It adds the missing ones and keeps the rest. The box names each missing one, and what goes wrong without it.
Your Stripe webhook has no signing secret, so every event is rejected	A webhook already existed in Stripe. Open it in Stripe, copy its signing secret (it starts with whsec_), and paste it into Stripe webhook signing secret. Then click Save Settings.
This Stripe key cannot manage webhook endpoints	Your key is missing the Webhook Endpoints row. Add it in Stripe, as on Stripe key and sales tax, and try again.

A line that starts with Stripe webhook: not checked means the check could not run, for example before you have saved a key. It is not an error.

A line that says the webhook “points at the old address” needs nothing from you. Your website moves it on its own.

Step 6. Turn off Stripe’s receipt

This one lives in Stripe, not in the panel.

Settings, then Customer emails. Switch off Stripe’s own receipt for successful payments.

Test mode first

In test mode the keys look a little different. The publishable key starts with pk_test_ and the restricted key starts with rk_test_. Cards are fake, so nothing is charged. You can run a whole sale and see the order arrive.

When you are happy, move to real money.

1. Switch Stripe out of test mode.
2. Copy the live publishable key, and make a live restricted key with the same permissions.
3. Paste both over the test ones, as in step 4, and click Save Settings.
4. Open the Settings tab again. The warning box is back, because a test webhook does not carry live payments.
5. Click the Create the endpoint at button again.

Test sales stay out of your live reports on their own. There is nothing to clean up.