WHBMP

Stripe

Oct 25, 2026

What it does

With Stripe switched on, the Pay button on a client's invoice sends the client to Stripe's own payment page (Stripe Checkout). Card details are typed on Stripe's page, so they never reach your server.

  • The amount is always worked out on your server from what the invoice still owes, in the invoice's currency. The client cannot change it.
  • The invoice is marked paid only when Stripe confirms the payment. WHBMP then records one payment transaction (with the Stripe payment reference) and moves the invoice to Paid. If Stripe sends the same news twice, nothing is booked twice.
  • If the client closes Stripe's page or presses back, nothing is charged and the invoice stays unpaid.
  • Refunds you make from the invoice go back to the client's card through Stripe.

Stripe handles whatever currency the invoice is in, including currencies without cents (Japanese yen) and with three decimals (Kuwaiti dinar). Stripe may refuse very small amounts, and shows its reason to the client.

Get your keys

  1. Sign in to the Stripe Dashboard. Switch to Test mode (the toggle at the top) while you are trying things out.
  2. Open Developers > API keys.
  3. Copy the Secret key (it starts with sk_test_ in test mode and sk_live_ in live mode). A restricted key (rk_…) also works if it may write Checkout Sessions and Refunds.
  4. The Publishable key (pk_…) is optional. Checkout does not need it.

Set up in WHBMP

  1. Open Settings > Payment Gateways and expand Stripe.
  2. Paste the Secret Key, and the Webhook Signing Secret once you have it (next section). Leave Publishable Key empty if you like.
  3. Switch the gateway on and click Save. Saving refuses a publishable key typed into the secret key box.
  4. Click Test Connection. It asks Stripe for the account behind the key and tells you its name and whether it is test or LIVE mode. If Stripe refuses the key, Stripe's own message is shown.

Keys are stored encrypted. To change one, type the new value; leaving a box empty keeps what is saved.

Set up the webhook

A webhook is how Stripe tells WHBMP that a payment happened, even if the client closed the browser right after paying. Without it, a payment is only confirmed when the client comes back to your site from Stripe's page.

  1. In the Stripe Dashboard open Developers > Webhooks > Add endpoint.
  2. Paste the Webhook URL shown on the Stripe card in WHBMP (it ends with /webhooks/payments/stripe). The address must be reachable from the internet over HTTPS.
  3. Select these events:
    • checkout.session.completed
    • checkout.session.async_payment_succeeded
    • checkout.session.async_payment_failed
    • charge.refunded
    • charge.dispute.created
  4. Save the endpoint, then reveal its Signing secret (it starts with whsec_) and paste it into Webhook Signing Secret in WHBMP.

WHBMP checks the signature of every call and refuses anything that is not from Stripe or is more than five minutes old. Events it does not use are accepted and ignored.

Test mode and live mode each have their own keys and their own webhook endpoint with its own signing secret. When you go live, replace both in WHBMP.

Trying it on your own computer

Stripe cannot call localhost. Payments still work without a webhook, because WHBMP asks Stripe about the payment when the client returns from Stripe's page. To test the webhook itself, use the Stripe CLI:

stripe listen --forward-to http://localhost/webhooks/payments/stripe

The CLI prints a signing secret (whsec_…); use that one as the Webhook Signing Secret while it runs.

Try a test payment

With test keys saved:

  1. Open an unpaid invoice as a client and click Pay with Stripe.
  2. On Stripe's page use the test card 4242 4242 4242 4242, any future expiry date, any three digits for the CVC and any postal code.
  3. You come back to the invoice. It shows as paid once Stripe has confirmed.

Other test cards: 4000 0000 0000 9995 is declined for insufficient funds, and 4000 0025 0000 3155 asks for 3D Secure authentication. More are listed in Stripe's testing documentation.

Refunds

Open the invoice, click Refund and choose Original gateway. For a payment that was taken through Stripe, WHBMP asks Stripe to refund the card (the full amount or the part you enter), then records the refund and updates the invoice. If Stripe refuses, its message is shown and nothing is recorded. You cannot refund more than is left on that Stripe payment.

The other refund choices (manual, account credit) and payments recorded by hand never call Stripe.

A refund you make in the Stripe Dashboard is picked up through the charge.refunded webhook and recorded on the invoice too.

Disputes and failures

When a cardholder disputes a payment, or a delayed payment method fails, WHBMP writes it to System Logs > Payment Gateway Logs as a failed webhook entry. Answer disputes in the Stripe Dashboard before the deadline. A payment that Stripe took but that does not match its invoice (a different amount or currency, or more than the invoice owed) is not booked; it is logged the same way so you can refund it or record it by hand.

Powered by WHBMP