Nastavení Stripe

Po dokončení tohoto návodu budete mít fungující Stripe účet, dvě sady API klíčů (test + live), webhook endpointy v obou prostředích směřující na váš Cabintale účet, a budete vědět, jak otestovat celé flow lokálně přes Stripe CLI předtím, než půjdete naživo.

Stripe je jen platební procesor — ceny jsou vaše

Cabintale ve Stripe nepředvytváří produkty. Každá Checkout session se sestaví ad-hoc s přesnou částkou, kterou vaše rezervace spočítá (počet nocí × cena, výše zálohy, doplatek, cokoli). Ve Stripe nemusíte nastavovat katalog produktů; nemusíte mít fixní ceny.

Co Stripe poskytuje:

• Hostovanou stránku checkoutu, která přijímá karty (a další metody, které povolíte) v jazyce a měně hosta
• Webhook události, které Cabintale řeknou, kdy platba uspěla, selhala nebo vypršela
• Dashboard pro detaily plateb a řešení reklamací (vrácení peněz děláte přímo v cabintale — viz Vrácení a zrušení rezervací)

To je vše. Cabintale řeší zbytek.

Krok 1: Zaregistrujte se u Stripe

Jděte na stripe.com a vytvořte si účet.

Můžete začít v Test režimu bez aktivace firmy — Test režim umožňuje realistické end-to-end flow s testovacími kartami (žádné skutečné peníze). Až budete připraveni přijímat skutečné platby, budete potřebovat aktivovat (poskytnout bankovní údaje, údaje o firmě, doklad totožnosti).

Krok 2: Přepněte na Test režim

Pravý horní roh Stripe Dashboardu → přepněte "Test mode" (sandbox/dev přepínač).

Když je přepínač zapnutý:

• Všechny API klíče, webhooky, zákazníci, platby a dashboardy jsou oddělené od live dat
• Testovací karty fungují; skutečné karty jsou odmítnuty
• Můžete bez obav rozbíjet, co chcete

Když je přepínač vypnutý, díváte se na live prostředí — stejné UI, oddělená data.

Test a Live jsou kompletně oddělené. Jiné klíče, jiné webhook endpointy, jiné signing secrety, jiní Customers, jiné Payments. Nic se nepřekrývá. Nastavujete je každý zvlášť.

Krok 3: Najděte své API klíče

Ve Stripe Dashboardu → Developers (levá lišta) → API keys.

Uvidíte:

• Publishable key — začíná na pk_test_… (test) nebo pk_live_… (live). Bezpečné sdílet.
• Secret key — začíná na sk_test_… / sk_live_…. Klikněte na Reveal test key pro zobrazení. Tento klíč nikdy nesdílejte; chovejte se k němu jako k heslu.

Zkopírujte oba. Vložte je do dialogu cabintale do odpovídajícího režimu (vybraný Test režim → vložte testovací klíče; přepněte na Live režim → vložte live klíče).

Stripe někdy zobrazí secret jen jednou. Pokud se to stane, klikněte na Reveal test key (test) nebo Reveal live key (live) pro opětovné zobrazení. Pro live vás Stripe může donutit, abyste si klíč poslali e-mailem — zkopírujte ho předtím, než zavřete modal.

Krok 4: Vytvořte cíl událostí (webhook)

Stripe přejmenoval webhooky na cíle událostí (event destinations). Ve Stripe Dashboardu → Developers → Webhooks klikněte na Add destination. Otevře se třístupňový průvodce.

1. Select events (výběr událostí)

• Event destination scope — zvolte Your account.
• API version — ponechte výchozí (např. 2020-08-27).
• V sekci Events pomocí vyhledávacího pole najděte a zaškrtněte těchto pět:
  • checkout.session.completed (zásadní — označuje rezervace jako zaplacené)
  • checkout.session.expired (uvolňuje datumy, když host nedokončí v čase)
  • payment_intent.succeeded (záložní pojistka)
  • payment_intent.payment_failed (označuje neúspěšné pokusy)
  • charge.refunded (synchronizuje vrácení zpět do cabintale — vystavené z cabintale i ze Stripe Dashboardu, oboje funguje)
• Klikněte Continue.

2. Choose destination type (typ cíle)

Zvolte Webhook endpoint (ne Amazon EventBridge ani Azure Event Grid). Klikněte Continue.

3. Configure destination (nastavení cíle)

• Destination name — libovolný název, např. Cabintale production.
• Endpoint URL — vložte URL z dialogu cabintale ze sekce "Webhook URL". Vypadá takto:

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

Tato URL je unikátní pro váš Cabintale účet. Token na konci říká našemu serveru, ke kterému účtu události patří.

• Description — volitelné.
• Klikněte Create destination.

Na stránce cíle najděte Signing secret (začíná na whsec_…), klikněte na ikonu oka pro zobrazení a zkopírujte ho.

Přepněte zpátky do dialogu cabintale → vložte do Podpisový klíč webhooku. Klikněte Uložit.

Starší účty Stripe mohou stále zobrazovat klasické tlačítko Add endpoint místo průvodce. Pole jsou stejná — endpoint URL, události, signing secret — jen na jedné obrazovce.

Krok 5: Otestujte připojení

Cabintale spustí test připojení automaticky při Uložit (zavolá Stripe API s vaším tajným klíčem). Výsledek se zobrazí jako flash zpráva nahoře na /settings.

Test můžete znovu spustit kdykoliv kliknutím na Nastavení na kartě Stripe → otevření dialogu → tlačítko Otestovat připojení vedle panelu uložených klíčů.

Výsledek:

• Connection OK — zelený badge, vše funguje
• Connection failed — červený badge s chybovou hláškou ze Stripe; obvykle špatný tajný klíč nebo špatný režim

Krok 6: End-to-end test rezervace (Test režim)

Nastavte ubytování na Přijímat platby — viz Přijímání plateb. Použijte Test režim klíče Stripe.

Pak:

1. Otevřete veřejnou URL widgetu (použijte Zobrazit veřejný widget na stránce úpravy widgetu)
2. Vyberte datumy → Rezervovat
3. Vyplňte formulář → Zaplatit
4. Stripe Checkout se otevře v nové záložce
5. Použijte testovací kartu:
   • Úspěch: 4242 4242 4242 4242
   • Odmítnutí: 4000 0000 0000 0002
   • Vyžadováno ověření (3DS): 4000 0025 0000 3155
   • Jakákoliv budoucí expirace, libovolné 3místné CVC, libovolné PSČ

1. Po platbě Stripe přesměruje na /payments/success (cabintale)
2. Otevřete rezervaci v adminu → ověřte, že je paid a tabulka Plateb ukazuje transakci

Pokud něco selže, zkontrolujte Stripe Dashboard → Developers → Webhooks → klikněte na váš endpoint → Recent deliveries. Uvidíte každou událost, kterou se Stripe pokoušel poslat, response code a tělo požadavku. 200 = dobré. Cokoli jiného = něco na straně cabintale; detaily najdete v logu.

Lokální vývoj se Stripe CLI

Stripe webhooky se nedostanou na localhost. Stripe CLI tomu pomáhá — bere události ze Stripe a posílá je na vaše lokální cabintale.

Instalace

brew install stripe/stripe-cli/stripe
stripe login

stripe login otevře okno prohlížeče — autorizujte, vraťte se do terminálu.

Forwardování webhooků

stripe listen --forward-to http://admin.cabintale.local:8888/api/webhooks/stripe/{váš_webhook_token}

Nahraďte {váš_webhook_token} UUID z webhook URL v dialogu cabintale — stačí URL zkopírovat a spustit.

CLI vypíše:

> Ready! Your webhook signing secret is whsec_abc123…

Tento signing secret se liší od toho ve Stripe Dashboardu. Je generovaný CLI. Vložte tenhle do Test režimu v cabintale do pole Podpisový klíč webhooku. Ten z dashboardu je pro endpoint dashboardu; ten z CLI je pro forwarder CLI.

Nechte stripe listen běžet. Teď jakákoliv testovací rezervace přes lokální widget spustí události, které poputují přes Stripe → CLI → váš localhost.

Spouštění fixture událostí přímo

Bez nutnosti dělat skutečnou testovací rezervaci můžete přehrávat události:

stripe trigger checkout.session.completed

Užitečné pro testování okrajových případů webhook handleru. Pro realistické flow projděte normální dialog rezervace s testovací kartou.

Znovuposlat konkrétní událost

Pokud potřebujete přehrát konkrétní událost (např. takovou, která vrátila 5xx):

stripe events resend evt_1XXXXXXXXXXXX

(ID události dostanete z výpisu stripe listen nebo ze Stripe Dashboardu → Events.)

Přechod na ostro

Až budete připraveni přijímat skutečné platby:

1. Vypněte Test mode ve Stripe Dashboardu
2. Aktivujte účet, pokud jste to ještě neudělali (bankovní údaje, doklad)
3. Developers → API keys → zkopírujte live sk_live_… a pk_live_…
4. Developers → Webhooks → Přidejte NOVÝ endpoint směřující na stejnou URL cabintale (musíte přidat samostatný endpoint pro live režim — jsou nezávislé)
5. Vyberte stejné události jako v Kroku 4 výše
6. Zkopírujte live signing secret
7. Otevřete dialog cabintale → přepněte na Ostrý režim → vložte live klíče → uložte
8. Otevřete jedno ze svých ubytování a ověřte, že je stále na Přijímat platby. Udělejte malou testovací rezervaci se skutečnou kartou — vy sami nebo přítel s malou částkou.

V dialogu můžete nechat uložené i Test klíče — přepínáním režimu v cabintale se mění, kterou sadu používáme pro nové Checkout sessions, a umožňuje to vrátit se zpátky k testování bez ztráty live klíčů.

Řešení potíží

Odkazy do dokumentace Stripe

• API klíče: https://docs.stripe.com/keys
• Webhooky: https://docs.stripe.com/webhooks
• Testovací karty: https://docs.stripe.com/testing
• CLI: https://docs.stripe.com/stripe-cli
• Lokalizace Checkoutu: https://docs.stripe.com/payments/checkout/customization/appearance#supported-languages

Související návody

• Platební brány (nastavení v cabintale) — Platební brány
• Přijímání plateb na ubytování — Přijímání plateb na ubytování