Stripe
Card and wallet payments through Stripe, either in a payment form on your own booking page or on Stripe's hosted page. Stripe is also the method that can save a card for the balance, place damage deposit card holds, refund and report disputes.
How the flow works
- The guest chooses Card (Stripe) at checkout, or pays a balance from their booking page.
- Depending on the method's Payment page setting:
- On your site: Stripe's Payment Element opens inside your booking page. Card, wallet and 3D Secure steps all happen in that form.
- Hosted by Stripe: the guest is sent to Stripe's checkout page and comes back to your site afterwards. A hosted page stays open for one hour.
- When the guest comes back, your site reads the payment from Stripe. Nothing in the return address is trusted.
- Separately, Stripe's webhook tells your site about the payment. The booking is confirmed even when the guest closes the tab before coming back.
Card details are entered in Stripe's form or on Stripe's page, never on your server. Payment methods that take time to clear (some bank debits) stay pending until Stripe confirms them.
The payment methods the guest sees are the ones switched on in your Stripe Dashboard. A saved card for the balance and a damage deposit hold need a card.
Setting it up
1. Create the method
Open Configure > Payment methods, click Add method and pick Stripe.
On the General tab give it a Title and Description (shown at checkout), set Published, and leave Test mode on for now. You can limit it to some Currencies.
On the Settings tab:
| Field | Value |
|---|---|
| Payment page | On your site (default) or Hosted by Stripe |
| Test publishable key | Stripe Dashboard > Developers > API keys, in test mode (pk_test_...) |
| Test secret key | Same page (sk_test_..., or a restricted key rk_test_...) |
| Test webhook signing secret | The whsec_... secret of the test webhook you create in step 2 |
| Live publishable key, Live secret key, Live webhook signing secret | The same for live mode (pk_live_..., sk_live_... or rk_live_...) |
| Statement suffix | Up to 22 characters added to your statement descriptor on the guest's card statement (optional) |
Save the method. Its Webhook tab now shows the Webhook address.
A method is not offered at checkout until its current mode has all three values: publishable key, secret key and webhook signing secret. The Test mode switch decides which set is used.
2. Register the webhook at Stripe
In the Stripe Dashboard, open Developers > Webhooks and add an endpoint:
- Endpoint URL: the address from the method's Webhook tab. It looks like
https://your-site/index.php?option=com_nextselfcatering&task=payment.notify&format=raw&method=3where3is the method's id. Copy it from the tab rather than typing it. - Events:
| Group | Events |
|---|---|
| Payments on your site | payment_intent.succeeded, payment_intent.payment_failed |
| Damage deposit holds | payment_intent.amount_capturable_updated, payment_intent.canceled |
| Hosted page | checkout.session.completed, checkout.session.expired, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed |
| Refunds | charge.refunded, refund.failed, charge.refund.updated |
| Disputes | charge.dispute.created, charge.dispute.updated, charge.dispute.closed, charge.dispute.funds_withdrawn, charge.dispute.funds_reinstated |
Add all 16 even if you use only one payment page: switching the page later then needs no change at Stripe.
Copy the endpoint's signing secret (whsec_...) into Test webhook signing secret. Stripe's test and live modes have separate endpoints, each with its own secret.
3. Check the keys
Click Test connection in the method. It reads your Stripe balance with the secret key of the current mode, checks that the key belongs to that mode, and lists anything still missing for it.
Test it
With Test mode on, no real money moves.
- Book a property on your site and pay with Stripe's test card
4242 4242 4242 4242, any future expiry date and any CVC. - Check the booking: the payment shows in its payments card and the booking is confirmed.
- Book again and, after paying, close the browser before you return to your site. The booking should still be confirmed within a minute or so, through the webhook.
- Refund part of a payment from the booking's payments card, and check it appears in the Stripe Dashboard.
- If you use saved cards, tick the consent box at checkout and check that the booking's payments card shows the saved card.
Stripe's test card 4000 0027 6000 3184 always asks for authentication. Use it to see what happens when an automatic balance charge needs the guest: the charge is refused and the guest gets their pay link.
Go live
- Enter the Live publishable key, Live secret key and Live webhook signing secret.
- Create the live webhook endpoint in the Stripe Dashboard (live mode) with the same address and events, and copy its signing secret.
- Switch Test mode off and click Test connection.
- Take one small real payment and refund it.
Test events never touch a live payment: a method in live mode refuses webhook deliveries from test mode, and the other way round.
Saved cards and the balance
When a property collects its balance Automatic, from a saved card, the checkout asks the guest whether Stripe may keep their card and take the balance on its due date. If they agree:
- A Stripe customer is created for that booking only. The card is never offered to anyone else.
- Your site stores only the card brand, the last four digits and the expiry date.
- The Automatic balance charges task takes the balance on its due date. A soft decline is retried once a day; a hard decline, or a card that needs the guest to authenticate, stops automatic collection and sends the guest their pay link.
- The guest can remove the card from their booking page; it is then detached at Stripe.
Damage deposit card holds
A property whose damage deposit is collected As a card pre-authorisation uses the saved card. The Damage deposit card holds task places a hold near the end of the stay, as a Stripe payment with manual capture. The hold shows on the booking with the time it is let go automatically, which comes from Stripe's own limit on the card.
After the inspection, Capture takes all or part of it, once (Stripe lets the rest go at once), or Let go releases it. See Payments and deposits.
Refunds
Refunds from a booking's payments card go to Stripe first, against the original payment, in part or in full. Your site records the refund only once Stripe accepts it. If Stripe gives no answer, the booking shows Refund ... has no answer from the gateway: check the Stripe Dashboard and record what happened.
A refund made in the Stripe Dashboard is recorded on the booking through charge.refunded. A refund that fails later at Stripe (refund.failed) shows a warning on the booking. Each refund is recorded once, whichever side it came from.
Disputes
When a guest disputes a payment, the booking shows The guest disputed ... with the reason and the date to respond by, and staff get an email. Automatic charges on that booking stop. Respond at the gateway opens the dispute in your Stripe Dashboard. When the dispute closes, the booking shows whether you won or lost; a lost dispute records the money as gone.
Currencies
Stripe is offered in the currencies Stripe charges cards in, except ISK, UGX and MGA (Stripe counts their amounts differently). A property priced in another currency does not see the method. Stripe's Adaptive Pricing is switched off, so the guest always pays in the property's currency.
Requirements
- A Stripe account.
- HTTPS and a site Stripe can reach for the webhook. On a local or password-protected site the webhook never arrives, and a payment is confirmed only when the guest comes back.
- PHP's cURL extension, and outgoing HTTPS to
api.stripe.com. The guest's browser loadsjs.stripe.com.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| Stripe is not offered at checkout | The method is unpublished, its app is off, or the current mode lacks one of its three keys. Test connection lists what is missing |
| "This is not a test secret key" / "This is not a live secret key" | The key does not match the Test mode switch. Test needs sk_test_ or rk_test_, live needs sk_live_ or rk_live_ |
| "Stripe refused the key." | The key was revoked, mistyped or belongs to another account |
| "Stripe could not be reached." | Your server cannot make outgoing HTTPS requests. Ask your host |
| Guest paid, booking still held | The webhook does not arrive: check the endpoint address, its events and the signing secret of the current mode |
| Stripe shows the webhook failing with 400 | Wrong signing secret, or a test event sent to a live method (or the reverse) |
| Stripe shows 404 | The method was deleted, or the address has the wrong method id. Copy it again from the Webhook tab |
| Stripe shows 500 | Your site could not finish the update. Stripe delivers again by itself; see the Joomla log if it keeps failing |
| A refund made in Stripe is missing on the booking | charge.refunded is not among the endpoint's events |
| Hosted payments confirm only when the guest comes back | The checkout.session events are missing from the endpoint |
| A balance was not taken from the saved card | See the warning on the booking: a declined card sends the guest their pay link. Check that Joomla's scheduled tasks run |