Payment gateways

By the end of this guide, you'll have a working Stripe gateway saved on your Cabintale account, with both Test and Live keys ready, and you'll know how to test the connection, regenerate the webhook URL, switch defaults, and delete a configuration.

Why a single account-level gateway?

Cabintale is built around the idea that you set up payments once per account, not per property. Most hosts use a single Stripe account for everything, and the gateway you configure here is the default for any property you turn payments on for. If you ever need separate gateways per country or brand, more provider entries (like ČSOB) will appear in the catalog as we add them — for now Stripe is the only active option.

Step 1: Open Settings

Sidebar → Settings. The page now has a Payment gateways section between Account and Close account.

You'll see two cards:

• Stripe — purple icon, Setup button, ready to configure
• ČSOB — faded out with Coming soon. Czech-merchant gateway; not yet available

If you've already set up Stripe before, the card has a green border + checkmark and the button reads Settings instead of Setup.

Step 2: Open the Stripe dialog

Click Setup (or Settings if already configured) on the Stripe card. A dialog opens with:

• The Stripe logo and a short description
• A link to our documentation tutorial (placeholder for now — it points at our docs)
• A Test mode / Live mode switch at the top
• Three input fields below: Secret key, Publishable key, Webhook signing secret
• An Our webhook URL section with a code block
• Footer: Test connection (left) and Cancel + Save (right). When you're editing an existing gateway, a Delete configuration button also appears on the left.

Step 3: Pick a mode and paste your keys

Test mode is selected by default. Start there — it's safer and you can switch to live later.

For the three fields:

1. Secret key — starts with sk_test_… (test) or sk_live_… (live). From Stripe → Developers → API keys.
2. Publishable key — starts with pk_test_… / pk_live_…. Same place.
3. Webhook signing secret — starts with whsec_…. From Stripe → Developers → Webhooks → your endpoint → Signing secret. You'll first need to add a webhook endpoint in Stripe, pointing at the URL we show further down the dialog (see Step 5).

If you're testing locally with the Stripe CLI, the CLI prints a different signing secret — use that one in test mode, not the one from Stripe Dashboard. See Stripe setup.

About the show/hide eye buttons. The Secret key and Webhook signing secret fields are masked by default. Click the eye icon next to them to reveal what you typed. We never store these in a way that lets us read them back to you — once saved, they live encrypted-at-rest on our servers and the dialog will show empty inputs the next time you open it (with a hint that says "Leave blank to keep current").

Step 4: Test the connection

Below the keys is a Test connection button. Click it once you've pasted all three. It calls Stripe's API with your secret key and reports back:

• Connection OK — green badge, you're good
• Connection failed — red badge with a Stripe error message; usually a typo in the secret key or wrong mode (test vs. live)

The test runs against the currently visible mode. If you flip from Test to Live, the inputs change and you can test that side independently.

Step 5: Wire up the webhook URL

Below the test button is Our webhook URL. It's a code block with something like:

https://admin.cabintale.com/api/webhooks/stripe/abc123-def4-...

This URL is unique to your account. Stripe sends payment events here so we can mark bookings as paid in real time.

1. Click Copy URL
2. Go to Stripe Dashboard → Developers → Webhooks → Add destination (Stripe now calls webhooks "event destinations")
3. Select events — set the scope to Your account, then search and tick: checkout.session.completed, checkout.session.expired, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded. Click Continue.
4. Choose destination type — pick Webhook endpoint. Click Continue.
5. Configure destination — paste the copied URL into Endpoint URL, give it a name (e.g. Cabintale production), and click Create destination.
6. On the destination page, reveal the Signing secret (whsec_…) and copy it back into the cabintale dialog's Webhook signing secret field.

The Regenerate link button rotates your account's webhook URL token. Use it if you suspect the URL has leaked. After rotating, you'll need to update the endpoint URL in Stripe Dashboard to match — the old URL stops working immediately.

Older Stripe accounts may still show a single-screen Add endpoint form instead of the three-step destination wizard. Same fields, same result.

Step 6: Save

Click Save. The dialog closes and:

• Your card now has a green border + checkmark (it's the account default)
• The button label changed from Setup to Settings
• A toast confirms "Gateway saved. Testing the connection…" — a real test runs in the background to verify

If you see a 422 error, the keys didn't pass validation. Most common cause: leaving a required field blank or pasting whitespace. Re-check and save again.

After setup: editing, the saved-keys view

Re-open the dialog by clicking Settings on the Stripe card. The dialog now shows a different layout:

• The mode toggle at the top
• A bordered panel saying "Your keys for this mode are saved. They are hidden for security." with two buttons:
  • Test connection — runs an immediate test against Stripe; result appears inline
  • Fill new keys — reveals the input fields so you can replace the keys

If you click Fill new keys, the form returns. Enter new values, click Save. Or click Cancel — keep existing keys to revert.

This view is per-mode: Test could be filled (showing the panel) while Live is still empty (showing inputs), and vice versa. Flipping the mode toggle swaps which panel is visible.

Switching between Test and Live

The most common timeline:

1. Set up Test mode, paste test keys, test bookings end-to-end
2. When ready to go live, open the dialog, flip to Live mode
3. Paste your live keys (and create a separate webhook endpoint in Stripe's live dashboard for the same URL)
4. The dialog now has both modes filled
5. To go live for real, set Live as the active mode and Save

You can flip between Test and Live whenever you want — both sets stay saved. Active mode determines which keys cabintale uses for new Checkout sessions.

Webhooks during the flip. When you flip from test to live, in-flight webhooks for sessions created in the previous mode still verify cleanly — cabintale tries both modes' signing secrets per delivery. So if you flip mid-day and a test-mode webhook lands ten seconds later, it still gets processed correctly.

Multiple gateways (future)

Today the catalog only has Stripe active. ČSOB is a placeholder for the upcoming Czech-merchant gateway. When more providers ship, you'll see additional cards in the catalog. The default-among-configured selection works by clicking the card body — clicking on Stripe's card body (after both providers are configured) will set Stripe as default, indicated by the green border + checkmark.

Deleting a gateway

In the dialog, footer left side, Delete configuration. The dialog asks for confirmation — "Pending or completed transactions tied to this gateway will continue to render with historical data."

Two outcomes:

• If no pending or succeeded transactions reference the gateway → it's deleted (soft-deleted; historical receipts still resolve)
• If any pending or succeeded transactions exist → 409 error inline. You can't delete a gateway that's still mid-flow with a guest. Either wait for those payments to complete, or cancel them from the booking detail page first.

Troubleshooting

Related guides

• Stripe setup (the Stripe-dashboard side) — Stripe setup
• Accept payments on a property — Accept payments on a property
• Account settings — Account settings