Stripe

A Stripe configuration needs two things from your Stripe account: the API secret key, which the broker uses to create checkouts and customers, and a webhook, through which Stripe tells the broker about every payment. Without the webhook, no payment is confirmed.

1. API secret key

1In Stripe, open Developers → API keys. Use Test mode for a sandbox configuration and live mode for production.
2Copy the Secret key: sk_test_… in test, sk_live_… in production. The Publishable key (pk_…) is not used.
3In Gateways → Add gateway → Stripe, paste it into API secret key and save.

The API secret key has nothing to do with webhooks: it authenticates the broker's calls to Stripe. The webhook secret (whsec_…) is a different one, and comes in step 3.

2. Webhook on Stripe

1Once saved, the gateway page gains a Webhook block: copy the Webhook URL from there. It carries this configuration's id, so it only exists after saving.
2In Stripe, open Developers → Webhooks → Add destination (or Add endpoint) and pick events from Your account.
3Paste the Webhook URL as the endpoint and select the events below. Any API version works: the broker reads both the old and the new shapes.
4Testing locally (localhost)? Stripe delivers only to public URLs. Run stripe listen --forward-to <Webhook URL> with the Stripe CLI and use the whsec_ it prints in step 3.

Events to select

Select exactly these. An extra event is ignored; a missing one leaves payments or renewals unconfirmed.

Events

checkout.session.completed
checkout.session.async_payment_succeeded
checkout.session.async_payment_failed
checkout.session.expired
payment_intent.succeeded
charge.succeeded
charge.updated
charge.refunded
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.paid
invoice_payment.paid
payment_intent.payment_failed
charge.failed
charge.dispute.created
charge.dispute.updated
charge.dispute.closed

checkout.session.completedThe customer finished the checkout: confirms a card payment and activates a subscription.

checkout.session.async_payment_succeededA method that settles later (boleto, bank debit) was paid.

checkout.session.async_payment_failedThat later payment failed.

checkout.session.expiredThe checkout expired unpaid.

payment_intent.succeededThe payment was captured.

charge.succeededThe charge went through.

charge.updatedStripe announced the balance transaction later: this is where the fee comes from.

charge.refundedThe charge was refunded.

customer.subscription.createdThe subscription was created on Stripe.

customer.subscription.updatedStatus, period, a scheduled cancellation or past_due changed.

customer.subscription.deletedThe subscription ended.

invoice.paidA subscription cycle was paid: it becomes a renewal in the statement.

invoice_payment.paidLinks the payment to its invoice on accounts with API 2025-03-31 or newer.

payment_intent.payment_failedAn attempt was declined (funds, expired card…): the reason shows on the payment page; the customer may still try another card.

charge.failedThe charge failed: completes the decline reason with the bank's code.

charge.dispute.createdThe customer's bank opened a chargeback: the payment shows the dispute and the app hears session.disputed.

charge.dispute.updatedThe dispute moved (evidence sent, under review): its status on the payment follows.

charge.dispute.closedThe bank decided the dispute, won or lost: the app hears session.dispute_closed.

3. Webhook secret

1When the endpoint is created, Stripe shows a Signing secret (whsec_…). Click Reveal and copy it.
2In the broker, in the gateway's Webhook block, paste it into Webhook secret and click Save webhook.
3The broker checks every event's Stripe-Signature with it; an event with a wrong signature is refused.

Which secret goes where

sk_test_… / sk_live_…Stripe's API secret key. Goes on the gateway, in API secret key.

whsec_…Stripe's Signing secret. Goes on the gateway, in Webhook secret.

pk_test_… / pk_live_…Stripe's publishable key. Not used: Stripe hosts the checkout.

pwhsec_…The secret the broker signs the webhooks it sends your app with. It lives in your app (PAY_WEBHOOK_SECRET), never on the gateway.

4. Test it

1With the gateway in Sandbox and test keys, use Connection test → Run a sandbox payment on the gateway page: it runs a real test payment and shows the events that arrived.
2If the test never leaves processing, the webhook is not arriving: check the URL, the events and the webhook secret.
3In Webhooks → Received, every Stripe event shows with how it was processed.

Next: Quick start · Apps & routing · Outbound events