Stripe
From a new Stripe account to live payments — verification, API keys, the webhook endpoint, ACH, test cards and the go-live checklist.
Create and verify the account#
- Sign up at stripe.com with the email address of the person who will own the account.
- Stripe opens in a sandbox (test mode) straight away, so you can set up and test before verification finishes.
- To take live payments, activate the account: business type and details, the representative's identity, the bank account for payouts, and the statement descriptor (the name on buyers' card statements; use your store's name).
- Stripe may ask for documents later. Answer quickly: unanswered requests can pause payouts.
Enable what you sell#
- Cards are on by default.
- ACH (US bank account): Settings → Payment methods → enable ACH Direct Debit. Then tick US bank account on the product here.
- Subscriptions need nothing extra: prices are created automatically from your plans.
- Disputes: nothing to enable; fraud warnings (Radar early fraud warnings) arrive with the events below.
Copy the API keys#
Developers → API keys (in test mode first):
- Publishable key (
pk_test_…). - Secret key (
sk_test_…), or a restricted key (rk_test_…) with write access to the resources this integration uses (Checkout Sessions, Customers, Prices, Products, Refunds, Subscriptions, Invoices, Disputes) and read access to Events, Charges and Balance transactions. If Verify reports a missing permission, add it to the key.
Paste both into a new Stripe credential set with environment Test.
Register the webhook#
Stripe's Workbench → Webhooks → Create an event destination (older accounts: Developers → Webhooks → Add endpoint):
- Choose events from Your account, destination type Webhook endpoint.
- Endpoint URL — the one shown on your credential set:
- Select these events:
checkout.session.completedcheckout.session.async_payment_succeededcheckout.session.async_payment_failedcheckout.session.expiredinvoice.paidinvoice.payment_failedcustomer.subscription.createdcustomer.subscription.updatedcustomer.subscription.deletedcharge.refundedcharge.refund.updatedcharge.dispute.createdcharge.dispute.updatedcharge.dispute.closedradar.early_fraud_warning.created
- Create the destination, open it and reveal the Signing secret (
whsec_…). Paste it into the set's Webhook signing secret.
Then Verify credentials and Put in service (Test).
Test in the sandbox#
| Card | Result |
|---|---|
4242 4242 4242 4242 | Succeeds |
4000 0000 0000 3220 | Asks for 3-D Secure, then succeeds |
4000 0000 0000 9995 | Declined (insufficient funds) |
Use any future expiry date, any CVC and any postal code. For ACH, choose the test bank on Stripe's page; the payment shows Processing, then Paid. Refund the test payment from its page and check that it reaches Refunded.
Go live#
- [ ] Account activated, payouts enabled.
- [ ] A live credential set with
pk_live_…/sk_live_…, its own live webhook destination and signing secret. - [ ] Products switched to the live set under Pay with.
- [ ] One small real payment and refund.
- [ ] Statement descriptor and support email set at Stripe.
Common errors#
| Message | Fix |
|---|---|
| does not look right on a key | Copy the whole key; publishable keys start pk_, secret keys sk_ or rk_. |
| belongs to the live environment, but this set is TEST | Use test keys in a test set and live keys in a live set. |
| Webhook deliveries answer 400 | The signing secret is from another destination or the other mode. |
| Verify says the key lacks permission | A restricted key misses one of the permissions above. |
| ACH tile missing | Enable ACH in Stripe and tick US bank account on the product. |