Stripe in Justflows Shop: afrekenen, wallets, abonnementen en chargebacks

Tot nu toe gebruikte een Justflows-shop die online betalingen wilde ontvangen Mollie. Stripe stond wel in de lijst met betaalproviders, maar kon nog geen betaling verwerken. Met Shop 0.3.2 verandert dat: Stripe is een volwaardige betaalgateway, van de eerste kaartbetaling tot abonnementen, terugbetalingen en chargebacks.

We hebben het in negen stappen gebouwd, elk met een eigen GitHub-issue, en ze komen samen in deze release. Dit krijg je als winkelier.

Elke shop kiest in de Stripe-instellingen een van drie manieren van afrekenen:

Welke je ook kiest, de bestelling krijgt de exacte regelbedragen uit Shop mee, en een bestelling wordt pas als betaald gemarkeerd als Stripe dat bevestigt met een ondertekende webhook. Alleen een terugkeer naar je site is nooit genoeg. Handmatig vastleggen (manual capture) en je eigen omschrijving op het bankafschrift worden ondersteund, en een geweigerde kaart geeft een toegankelijke foutmelding.

Betaallinks werken ook met Stripe. Een eenmalige betaallink voor een bekende klant kan als Stripe Payment Link worden aangemaakt, en openstaande bestellingen, zoals geaccepteerde offertes, kunnen met Stripe of Mollie worden betaald.

De Payment Element-checkout kan de Express Checkout-knoppen van Stripe tonen voor Apple Pay, Google Pay en Link. Die gebruiken dezelfde betaling, bestelgegevens en webhooks als een kaartbetaling. Je zet Express Checkout en Link per test- of livemodus aan of uit, en registreert het domein van je site vanuit de instellingen bij je Stripe-test- en liveaccount.

Shop houdt geen eigen lijst met Stripe-betaalmethoden bij. De instellingenpagina leest welke methoden op je Stripe-account beschikbaar zijn, voor de huidige test- of livemodus, en de methoden die Stripe je laat wijzigen zet je daar direct aan of uit. Shop schrijft die keuze terug naar Stripe.

Actieve methoden verschijnen in de checkout als aparte keuzes met hun eigen logo: kaarten, iDEAL, Bancontact, EPS, Przelewy24, SEPA-incasso, Klarna, Afterpay/Clearpay, Affirm en andere methoden die je in Stripe aanzet. Shop biedt een methode alleen aan als die past bij de valuta van de bestelling en het factuurland, en Stripe doet de laatste controle voor het apparaat en het account.

Sommige methoden hebben een paar dagen nodig voor de bevestiging. Zolang een betaling in behandeling is, blijven de bestelling en de voorraad gereserveerd. Mislukt de betaling, dan mislukt de bestelling op de gewone manier en komt de voorraad weer vrij. Bij SEPA-incasso toont de checkout de machtigingstekst en legt de bestelling het machtigingskenmerk vast.

Betaalt een ingelogde klant voor het eerst met Stripe, dan maakt Shop de Stripe-klant aan met naam, e-mailadres en factuuradres. In de checkout kan de klant ervoor kiezen de kaart te bewaren, en in het account kan de klant betaalmethoden toevoegen of verwijderen. De klant ziet het kaartmerk, de laatste vier cijfers en de vervaldatum, en medewerkers zien hetzelfde bij Klanten. Kaartnummers komen nooit bij Justflows.

Verlengingen van abonnementen worden van die opgeslagen methoden afgeschreven. Vraagt een bank de klant om een verlenging te bevestigen, dan stuurt Shop de herstelmail die het al gebruikt voor mislukte verlengingen. Een export van persoonsgegevens vermeldt dat de klant aan Stripe gekoppeld is zonder provider-id's te tonen, en het verwijderen van de gebruiker verwijdert ook de opgeslagen methoden en de koppeling.

Elke site kiest wie de abonnementen beheert:

Ook in Billing-modus worden de facturen van Stripe gewone verlengingsbestellingen in Shop, zodat rapporten, facturen en e-mails op één plek blijven. De keuze geldt voor nieuwe abonnementen. Bestaande abonnementen houden de modus waarmee ze begonnen, zodat er nooit twee planningen voor dezelfde periode afschrijven.

Sla je de Stripe-instellingen op, dan maakt of werkt Shop het webhook-endpoint in je Stripe-account bij, vastgezet op één API-versie en alleen geabonneerd op de events die Shop gebruikt. Je hoeft geen ondertekeningsgeheim te kopiëren: Shop bewaart het in de versleutelde geheimenopslag voor plugins en accepteert tijdens een rotatie zowel het oude als het nieuwe geheim.

Elk event van Stripe wordt één keer verwerkt, ook als Stripe het twee keer stuurt. Mislukte leveringen staan in de betalingsoverzichten van Shop met een knop om ze opnieuw af te spelen, en Diagnostiek meldt ze. Bij opnieuw afspelen leest Shop het event eerst opnieuw bij Stripe, zodat een laat of verkeerd geordend event een nieuwere status niet kan terugdraaien.

Daaronder zit een Stripe-client die op één API-versie is vastgezet. Elk verzoek dat iets aanmaakt krijgt een idempotency-sleutel, korte netwerkfouten worden een beperkt aantal keren opnieuw geprobeerd, en is het antwoord van Stripe onduidelijk, dan stemt Shop het later af in plaats van te gokken. Beperkte API-sleutels (restricted keys) werken.

Een klant van wie de kaart wordt geweigerd, of die een betaling afbreekt en het opnieuw probeert, houdt dezelfde bestelling. Shop werkt die bestelling bij met de nieuwe poging in plaats van een dubbele aan te maken, en de voorraad die ervoor gereserveerd was blijft beschikbaar voor die winkelwagen. Is de betaling gelukt, dan wordt de winkelwagen geleegd, zodat de volgende aankoop schoon begint.

Stripe-ondersteuning zit in Shop 0.3.2, nu beschikbaar in de marketplace. Begin met testsleutels: de instellingen houden test- en livegegevens gescheiden en laten zien welke modus actief is. Mollie blijft werken zoals altijd, en je kunt beide aanbieden.

Het werk staat in de issues #232 tot en met #240. De documentatie van Shop beschrijft de installatie, en vragen of problemen kun je kwijt op support.justflows.com.