Maksupalvelut

Kun olet käynyt oppaan läpi, Cabintale-tilillesi on tallennettu toimiva maksupalvelu, jonka sekä Testi- että Tuotanto-avaimet ovat valmiina, ja tiedät, miten yhteys testataan, webhook-osoite luodaan uudelleen, oletus vaihdetaan ja määritys poistetaan.

Miksi yksi tilitason maksupalvelu?

Cabintale perustuu ajatukseen, että otat maksut käyttöön kerran tiliä kohti, et kohdetta kohti. Useimmat isännät käyttävät yhtä maksupalvelua kaikkeen, ja tässä määrittämäsi maksupalvelu on oletus jokaiselle kohteelle, jolle otat maksut käyttöön. Jos joskus tarvitset erilliset maksupalvelut maata tai brändiä kohti, katalogiin ilmestyy lisää tarjoajia (kuten ČSOB), kun lisäämme niitä. Toistaiseksi aktiivisia vaihtoehtoja on yksi.

Vaihe 1: Avaa Asetukset

Sivupalkki → Asetukset. Sivulla on nyt Maksupalvelut-osio Tilin ja Sulje tili -osion välissä.

Näet kaksi korttia:

• Stripe: violetti kuvake, Määritä-painike, valmis määritettäväksi
• ČSOB: himmennetty ja merkitty Tulossa pian. Tšekkiläisten kauppiaiden maksupalvelu, ei vielä käytettävissä

Jos olet jo aiemmin määrittänyt maksupalvelusi, kortilla on vihreä reunus + valintamerkki ja painikkeessa lukee Asetukset tekstin Määritä sijaan.

Vaihe 2: Avaa maksupalvelun ikkuna

Napsauta Stripe-kortilla Määritä (tai Asetukset, jos jo määritetty). Ikkuna aukeaa, ja siinä on:

• Maksupalvelun logo ja lyhyt kuvaus
• Linkki dokumentaatio-oppaaseemme (toistaiseksi paikkamerkki, osoittaa dokumentaatioomme)
• Testitila / Tuotantotila -valinta ylhäällä
• Kolme syöttökenttää alla: Salainen avain, Julkinen avain, Webhookin allekirjoitusavain
• Webhook-osoitteemme -osio koodilohkolla
• Alareuna: Testaa yhteys (vasemmalla) sekä Peruuta + Tallenna (oikealla). Kun muokkaat olemassa olevaa maksupalvelua, vasemmalle ilmestyy myös Poista määritys -painike.

Vaihe 3: Valitse tila ja liitä avaimet

Testitila on valittuna oletuksena. Aloita siitä, sillä se on turvallisempi, ja voit vaihtaa tuotantoon myöhemmin.

Kolmelle kentälle:

1. Salainen avain: alkaa sk_test_… (testi) tai sk_live_… (tuotanto). Stripe → Developers → API keys.
2. Julkinen avain: alkaa pk_test_… / pk_live_…. Samasta paikasta.
3. Webhookin allekirjoitusavain: alkaa whsec_…. Stripe → Developers → Webhooks → päätepisteesi → Signing secret. Sinun on ensin lisättävä webhook-päätepiste Stripeen osoittamaan osoitteeseen, jonka näytämme ikkunan alempana (katso vaihe 5).

Jos testaat paikallisesti Stripe CLI:llä, CLI tulostaa eri allekirjoitusavaimen. Käytä sitä testitilassa, ei Stripe Dashboardin avainta. Katso Stripen käyttöönotto.

Näytä/piilota-silmäpainikkeista. Salainen avain- ja Webhookin allekirjoitusavain -kentät on oletuksena peitetty. Napsauta niiden vieressä olevaa silmäkuvaketta nähdäksesi kirjoittamasi. Emme koskaan tallenna näitä tavalla, joka antaisi meidän lukea ne takaisin sinulle. Tallennuksen jälkeen ne säilyvät salattuina palvelimillamme, ja ikkuna näyttää tyhjät kentät seuraavan kerran avatessasi sen (vihjeellä "Jätä tyhjäksi, jos haluat säilyttää nykyisen arvon.").

Vaihe 4: Testaa yhteys

Avainten alla on Testaa yhteys -painike. Napsauta sitä, kun olet liittänyt kaikki kolme. Se kutsuu maksupalvelun rajapintaa salaisella avaimellasi ja kertoo tuloksen:

• Yhteys toimii: vihreä merkki, kaikki hyvin
• Yhteys epäonnistui: punainen merkki ja maksupalvelun virheviesti. Yleensä kirjoitusvirhe salaisessa avaimessa tai väärä tila (testi vs. tuotanto)

Testi ajetaan parhaillaan näkyvälle tilalle. Jos vaihdat Testistä Tuotantoon, kentät vaihtuvat ja voit testata kyseisen puolen itsenäisesti.

Vaihe 5: Yhdistä webhook-osoite

Testipainikkeen alla on Webhook-osoitteemme. Se on koodilohko, jossa on jotain tällaista:

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

Tämä osoite on yksilöllinen tilillesi. Maksupalvelu lähettää maksutapahtumat tänne, jotta voimme merkitä varaukset maksetuiksi reaaliajassa.

1. Napsauta Kopioi osoite
2. Siirry Stripe Dashboardiin → Developers → Webhooks → Add destination (Stripe kutsuu nykyään webhookeja "event destinations"-kohteiksi)
3. Select events: aseta laajuudeksi Your account, hae sitten ja valitse: checkout.session.completed, checkout.session.expired, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded. Napsauta Continue.
4. Choose destination type: valitse Webhook endpoint. Napsauta Continue.
5. Configure destination: liitä kopioitu osoite kenttään Endpoint URL, anna sille nimi (esim. Cabintale production) ja napsauta Create destination.
6. Kohteen sivulla näytä Signing secret (whsec_…) ja kopioi se takaisin Cabintalen ikkunan Webhookin allekirjoitusavain -kenttään.

Luo uudelleen -painike vaihtaa tilisi webhook-osoitteen tunnisteen. Käytä sitä, jos epäilet osoitteen vuotaneen. Vaihdon jälkeen sinun on päivitettävä päätepisteen osoite Stripe Dashboardissa vastaamaan uutta. Vanha osoite lakkaa toimimasta heti.

Vanhemmissa Stripe-tileissä voi yhä näkyä yhden näytön Add endpoint -lomake kolmivaiheisen kohdeopastuksen sijaan. Samat kentät, sama tulos.

Vaihe 6: Tallenna

Napsauta Tallenna. Ikkuna sulkeutuu ja:

• Korttisi saa vihreän reunuksen + valintamerkin (se on tilin oletus)
• Painikkeen teksti vaihtui muodosta Määritä muotoon Asetukset
• Ilmoitus vahvistaa "Maksupalvelu tallennettu. Testataan yhteyttä…", ja oikea testi ajetaan taustalla varmistukseksi

Jos näet 422-virheen, avaimet eivät läpäisseet validointia. Yleisin syy: pakollinen kenttä jäi tyhjäksi tai liitit välilyöntejä. Tarkista ja tallenna uudelleen.

Määrityksen jälkeen: muokkaus, tallennettujen avainten näkymä

Avaa ikkuna uudelleen napsauttamalla Stripe-kortin Asetukset-painiketta. Ikkuna näyttää nyt erilaisen asettelun:

• Tilan valinta ylhäällä
• Reunustettu paneeli, jossa lukee "Tämän tilan avaimet on tallennettu, ja ne on piilotettu turvallisuussyistä." ja kaksi painiketta:
  • Testaa yhteys: ajaa heti testin maksupalvelua vasten, tulos näkyy paneelissa
  • Anna uudet avaimet: näyttää syöttökentät, jotta voit korvata avaimet

Jos napsautat Anna uudet avaimet, lomake palaa. Kirjoita uudet arvot ja napsauta Tallenna. Tai napsauta Peruuta ja säilytä nykyiset avaimet peruuttaaksesi.

Tämä näkymä on tilakohtainen: Testi voi olla täytetty (paneeli näkyy), kun Tuotanto on yhä tyhjä (kentät näkyvät), ja päinvastoin. Tilavalinnan vaihto vaihtaa, kumpi paneeli on näkyvissä.

Vaihtaminen Testin ja Tuotannon välillä

Yleisin eteneminen:

1. Määritä Testitila, liitä testiavaimet ja testaa varaukset alusta loppuun
2. Kun olet valmis siirtymään tuotantoon, avaa ikkuna ja vaihda Tuotantotilaan
3. Liitä tuotantoavaimesi (ja luo erillinen webhook-päätepiste Stripen tuotantohallintapaneelissa samalle osoitteelle)
4. Ikkunassa on nyt molemmat tilat täytettyinä
5. Siirtyäksesi oikeasti tuotantoon aseta Tuotanto aktiiviseksi tilaksi ja Tallenna

Voit vaihdella Testin ja Tuotannon välillä milloin haluat. Molemmat avainjoukot pysyvät tallessa. Aktiivinen tila määrää, mitä avaimia Cabintale käyttää uusille Checkout-istunnoille.

Webhookit vaihdon aikana. Kun vaihdat testistä tuotantoon, edellisessä tilassa luotujen istuntojen käynnissä olevat webhookit vahvistuvat yhä moitteettomasti, sillä Cabintale kokeilee molempien tilojen allekirjoitusavaimia jokaisella toimituksella. Jos siis vaihdat kesken päivän ja testitilan webhook saapuu kymmenen sekuntia myöhemmin, se käsitellään silti oikein.

Useita maksupalveluita (tulevaisuudessa)

Tällä hetkellä katalogissa on aktiivisena vain Stripe. ČSOB on paikkamerkki tulevalle tšekkiläisten kauppiaiden maksupalvelulle. Kun lisää tarjoajia julkaistaan, katalogiin ilmestyy lisää kortteja. Oletuksen valinta määritettyjen joukosta tapahtuu napsauttamalla kortin runkoa. Kun molemmat tarjoajat on määritetty, Stripe-kortin rungon napsautus asettaa Stripen oletukseksi, mistä kertoo vihreä reunus + valintamerkki.

Maksupalvelun poistaminen

Ikkunan alareunan vasemmalla puolella on Poista määritys. Ikkuna pyytää vahvistuksen: "Tähän maksupalveluun liittyvät odottavat tai valmiit tapahtumat näytetään edelleen historiatiedoissa."

Kaksi lopputulosta:

• Jos mikään odottava tai onnistunut tapahtuma ei viittaa maksupalveluun → se poistetaan (pehmeästi poistettu, vanhat kuitit toimivat yhä)
• Jos odottavia tai onnistuneita tapahtumia on → 409-virhe näytetään ikkunassa. Et voi poistaa maksupalvelua, joka on yhä kesken vieraan kanssa. Odota, että nuo maksut valmistuvat, tai peruuta ne ensin varauksen tietosivulta.

Ongelmanratkaisu

Aiheeseen liittyvät oppaat

• Stripen käyttöönotto (Stripe-hallintapaneelin puoli) — Stripen käyttöönotto
• Maksujen vastaanotto kohteessa — Maksujen vastaanotto kohteessa
• Tilin asetukset — Tilin asetukset