Stripen käyttöönotto

Kun olet käynyt oppaan läpi, sinulla on toimiva Stripe-tili, kaksi API-avainjoukkoa (testi + tuotanto), webhook-päätepisteet molemmissa ympäristöissä osoittamassa Cabintale-tiliisi, ja tiedät, miten koko kulku testataan paikallisesti Stripe CLI:llä ennen tuotantoon siirtymistä.

Stripe on vain maksujenkäsittelijä: hinnoittelu on sinun

Cabintale ei luo tuotteita Stripeen etukäteen. Jokainen Checkout-istunto rakennetaan tilanteen mukaan täsmälleen sillä summalla, jonka varauksesi laskee (yöt × hinta, ennakkomaksun määrä, loppumaksu, mikä tahansa). Sinun ei tarvitse luoda tuotekatalogia Stripeen eikä sinulla tarvitse olla kiinteitä hintoja.

Mitä Stripe antaa:

• Isännöity maksusivu, joka hyväksyy kortit (ja muut käyttöön ottamasi tavat) vieraan kielellä ja valuutassa
• Webhook-tapahtumat, jotka kertovat Cabintalelle, kun maksu onnistuu, epäonnistuu tai vanhenee
• Hallintapaneeli tilityksille ja riidoille (hyvitykset teet suoraan Cabintalessa, katso Hyvitykset ja peruutukset)

Siinä kaikki. Cabintale hoitaa kaiken muun.

Vaihe 1: Rekisteröidy Stripeen

Siirry osoitteeseen stripe.com ja luo tili.

Voit aloittaa testitilassa aktivoimatta yritystäsi. Testitilassa voit tehdä realistisia kulkuja alusta loppuun testikorteilla (ei oikeaa rahaa). Kun olet valmis ottamaan vastaan oikeita maksuja, sinun on aktivoitava tili (annettava pankkitiedot, yritystiedot, henkilöllisyystodistus).

Vaihe 2: Kytke Testitila päälle

Stripe Dashboardin oikea yläkulma → kytke "Test mode" (sandbox/kehitysvalinta).

Kun valinta on päällä:

• Kaikki API-avaimet, webhookit, asiakkaat, maksut ja hallintapaneelit ovat erillään tuotantotiedoista
• Testikortit toimivat, oikeat kortit hylätään
• Voit rikkoa asioita vapaasti

Kun valinta on pois päältä, katsot tuotantoympäristöä: sama käyttöliittymä, erilliset tiedot.

Testi ja tuotanto ovat täysin erillisiä. Eri avaimet, eri webhook-päätepisteet, eri allekirjoitusavaimet, eri asiakkaat, eri maksut. Mikään ei ylitä rajaa. Määrität kummankin kerran.

Vaihe 3: Etsi API-avaimesi

Stripe Dashboardissa → Developers (vasen sivupalkki) → API keys.

Näet:

• Publishable key (julkinen avain): alkaa pk_test_… (testi) tai pk_live_… (tuotanto). Turvallinen jakaa.
• Secret key (salainen avain): alkaa sk_test_… / sk_live_…. Napsauta Reveal test key nähdäksesi sen. Älä koskaan jaa tätä. Kohtele sitä kuin salasanaa.

Kopioi molemmat. Liitä ne Cabintalen ikkunaan vastaavassa tilassa (Testitila valittuna → liitä testiavaimet. Vaihda Tuotantotilaan → liitä tuotantoavaimet).

Stripe näyttää salaisen avaimen joskus vain kerran. Jos näin käy, napsauta Reveal test key (testi) tai Reveal live key (tuotanto) nähdäksesi sen uudelleen. Tuotannossa Stripe voi pakottaa sinut lähettämään avaimen itsellesi sähköpostilla. Kopioi se ennen ikkunan sulkemista.

Vaihe 4: Luo event destination (webhook)

Stripe nimesi webhookit uudelleen event destinations -kohteiksi. Stripe Dashboardissa → Developers → Webhooks napsauta Add destination. Kolmivaiheinen opastus aukeaa.

1. Select events

• Event destination scope: valitse Your account.
• API version: jätä oletus (esim. 2020-08-27).
• Kohdassa Events käytä hakukenttää ja valitse nämä viisi:
  • checkout.session.completed (kriittinen: merkitsee varaukset maksetuiksi)
  • checkout.session.expired (vapauttaa päivät, kun vieraat eivät viimeistele ajoissa)
  • payment_intent.succeeded (päällekkäinen varmistus)
  • payment_intent.payment_failed (merkitsee epäonnistuneet yritykset)
  • charge.refunded (synkronoi hyvitykset takaisin Cabintaleen: sekä Cabintalen käyttöliittymästä että Stripe Dashboardista tehdyt toimivat)
• Napsauta Continue.

2. Choose destination type

Valitse Webhook endpoint (ei Amazon EventBridge tai Azure Event Grid). Napsauta Continue.

3. Configure destination

• Destination name: mikä tahansa, minkä tunnistat, esim. Cabintale production.
• Endpoint URL: liitä osoite Cabintalen ikkunan "Webhook-osoitteemme" -osiosta. Se näyttää tältä:

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

Tämä osoite on yksilöllinen Cabintale-tilillesi. Lopussa oleva tunniste kertoo palvelimellemme, mille tilille tapahtumat kuuluvat.

• Description: valinnainen.
• Napsauta Create destination.

Etsi kohteen sivulta Signing secret (alkaa whsec_…), napsauta silmäkuvaketta paljastaaksesi sen ja kopioi se.

Palaa Cabintalen ikkunaan → liitä se kenttään Webhookin allekirjoitusavain. Napsauta Tallenna.

Vanhemmissa Stripe-tileissä voi yhä näkyä perinteinen Add endpoint -painike kohdeopastuksen sijaan. Kentät ovat samat (päätepisteen osoite, tapahtumat, allekirjoitusavain), vain yhdellä näytöllä.

Vaihe 5: Testaa yhteys

Cabintale ajaa yhteystestin automaattisesti tallennettaessa (se kutsuu Stripen rajapintaa salaisella avaimellasi). Tulos näkyy ilmoituksena sivun /settings yläreunassa.

Voit myös testata uudelleen milloin tahansa napsauttamalla Stripe-kortin Asetukset-painiketta → avaamalla ikkunan → Testaa yhteys -painike tallennettujen avainten paneelin vieressä.

Tulos:

• Yhteys toimii: vihreä merkki, kaikki hyvin
• Yhteys epäonnistui: punainen merkki ja Stripen virheviesti. Yleensä väärä salainen avain tai väärä tila

Vaihe 6: Testivaraus alusta loppuun (Testitila)

Aseta kohde tilaan Ota maksuja vastaan, katso Maksujen vastaanotto. Käytä Stripen testitilan avaimia.

Sitten:

1. Avaa julkisen widgetin osoite (käytä widgetin muokkaussivun Näytä julkinen widgetti -toimintoa)
2. Valitse päivät → Tee varaus
3. Täytä lomake → Maksa nyt
4. Stripe Checkout aukeaa uuteen välilehteen
5. Käytä testikorttia:
   • Onnistuu: 4242 4242 4242 4242
   • Hylätään: 4000 0000 0000 0002
   • Vaatii tunnistautumisen (3DS): 4000 0025 0000 3155
   • Mikä tahansa tuleva voimassaoloaika, mikä tahansa 3-numeroinen CVC, mikä tahansa postinumero

1. Maksun jälkeen Stripe ohjaa osoitteeseen /payments/success (Cabintale)
2. Avaa varaus hallintapaneelissa → varmista, että se on tilassa paid ja Maksut-taulukossa näkyy maksupalvelun tapahtuma

Jos jokin epäonnistuu, tarkista Stripe Dashboard → Developers → Webhooks → napsauta päätepistettäsi → Recent deliveries. Näet jokaisen tapahtuman, jonka Stripe yritti lähettää, vastauskoodin ja pyynnön sisällön. 200 = hyvä. Mikä tahansa muu = jokin Cabintalen päässä. Sivu kirjaa tiedot sinne.

Paikallinen kehitys Stripe CLI:llä

Stripen webhookit eivät tavoita osoitetta localhost. Stripe CLI yhdistää nämä: se ottaa tapahtumat Stripeltä ja välittää ne paikalliseen Cabintaleesi.

Asenna

brew install stripe/stripe-cli/stripe
stripe login

stripe login avaa selainikkunan. Valtuuta se ja palaa päätteeseen.

Välitä webhookit

stripe listen --forward-to http://admin.cabintale.local:8888/api/webhooks/stripe/{your_account_webhook_token}

Korvaa {your_account_webhook_token} Cabintalen ikkunan webhook-osoitteen UUID:lla. Kopioi vain osoite ja aja se.

CLI tulostaa:

> Ready! Your webhook signing secret is whsec_abc123…

Tämä allekirjoitusavain on eri kuin Stripe Dashboardin. Se on CLI:n luoma. Liitä tämä Cabintalen Testitilan webhookin allekirjoitusavain -kenttään. Dashboardin avain on dashboardin päätepisteelle, ja CLI:n avain CLI:n välittäjälle.

Jätä stripe listen käyntiin. Nyt jokainen paikallisessa widgetissäsi tehty testivaraus laukaisee tapahtumia, jotka kulkevat Stripen → CLI:n → localhostisi kautta.

Laukaise testitapahtumia suoraan

Ilman oikean testivarauksen tekemistä voit toistaa tapahtumia:

stripe trigger checkout.session.completed

Hyödyllinen webhook-käsittelijän reunatapausten testaamiseen. Realistisia kulkuja varten käy vain läpi varsinainen varausikkuna testikortilla.

Lähetä tietty tapahtuma uudelleen

Jos tarvitset tietyn tapahtuman toiston (esim. sellaisen, joka palautti 5xx):

stripe events resend evt_1XXXXXXXXXXXX

(Tapahtuman tunniste löytyy stripe listen -lokista tai Stripe Dashboardista → Events.)

Tuotantoon siirtyminen

Kun olet valmis ottamaan vastaan oikeita maksuja:

1. Kytke Stripe Dashboard pois testitilasta
2. Aktivoi tilisi, jos et ole vielä (pankkitiedot, henkilöllisyystodistus)
3. Developers → API keys → kopioi tuotannon sk_live_… ja pk_live_…
4. Developers → Webhooks → lisää UUSI päätepiste, joka osoittaa samaan Cabintale-osoitteeseen (tuotantotilaan on lisättävä erillinen päätepiste, sillä ne ovat toisistaan riippumattomia)
5. Valitse samat tapahtumat kuin yllä vaiheessa 4
6. Kopioi tuotannon allekirjoitusavain
7. Avaa Cabintalen ikkuna → vaihda Tuotantotilaan → liitä tuotantoavaimet → tallenna
8. Avaa yksi kohteistasi ja varmista, että se on yhä tilassa Ota maksuja vastaan. Tee pieni testivaraus oikealla kortilla: itse tai ystävän kanssa pienellä summalla.

Voit jättää myös testitilan avaimet tallennettuina ikkunaan. Tilan vaihtaminen Cabintalessa vaihtaa, kumpaa joukkoa käytetään uusille Checkout-istunnoille, ja antaa sinun palata testaamaan menettämättä tuotantoavaimiasi.

Ongelmanratkaisu

Viitteitä Stripen dokumentaatioon

• API-avaimet: https://docs.stripe.com/keys
• Webhookit: https://docs.stripe.com/webhooks
• Testikortit: https://docs.stripe.com/testing
• CLI: https://docs.stripe.com/stripe-cli
• Checkoutin kielet: https://docs.stripe.com/payments/checkout/customization/appearance#supported-languages

Aiheeseen liittyvät oppaat

• Maksupalvelut (Cabintalen puoli) — Maksupalvelut
• Maksujen vastaanotto kohteessa — Maksujen vastaanotto kohteessa