B Blengi docs

Je workspace beheren

Abonnement en facturering

De facturering wordt verzorgd door Stripe via Laravel Cashier. Elke werkruimte valt onder één abonnement tegelijk. Op deze pagina lees je welke abonnementen er zijn, hoe het gebruik wordt gemeten en wat er gebeurt als je een limiet bereikt.

Abonnementen

Abonnementen worden beheerd door platformbeheerders (zie Abonnementen & Stripe-synchronisatie ) en zijn zichtbaar voor klanten onder Instellingen › Abonnement en facturering (/settings/billing ; /app/billing leidt daar nog steeds naartoe). Een abonnement heeft:

VeldWat het doet
nameWeergavenaam (Free, Pro, Enterprise).
slugVaste identificatiecode — verandert nooit meer nadat het is aangemaakt, zelfs niet als de naam verandert.
monthly_conversationsQuota voor nieuwe gesprekken per kalendermaand. 0 betekent onbeperkt.
monthly_messagesOptioneel. Quota per bericht, geteld over alle bezoekersbezoeken deze kalendermaand. Laat leeg voor geen extra limiet; alleen het aantal gesprekken bepaalt de capaciteit van de werkruimte.
max_tokens_per_responseOptioneel. Beperkt het aantal max_tokens van de LLM voor elk antwoord in dit abonnement. Laat het leeg om de standaardwaarde van 800 te gebruiken. Handig om de gratis versie kort te houden en de betaalde versies uitgebreid.
price_centsPrijs van het abonnement in cent (wordt één keer per interval in rekening gebracht). 0 betekent gratis / aangepast (slaat de gateway-synchronisatie over).
intervalFactureringsfrequentie — month of year. Standaard is month. Stripe-prijzen, PayPal-factureringscycli en Razorpay-periodes zijn allemaal afgeleid van deze kolom.
features.remove_brandingVerbergt de ‘Powered by’-voettekst in de widget.

WhatsApp. Een abonnement bevat het WhatsApp-kanaal als het WhatsApp-kanaal is aangevinkt in de abonnementseditor, eventueel met een maandelijks maximum voor WhatsApp AI-antwoorden (leeg = onbeperkt). Boven het maximum komen WhatsApp-chats in de inbox van het team terecht. Meta’s eigen berichtkosten worden door het bedrijf aan Meta betaald. Zie WhatsApp-kanaal .

Maandelijkse + jaarlijkse varianten

Om een jaarlijkse korting aan te bieden, maak je hetzelfde abonnement twee keer aan — één met interval=month en één met interval=year — en stel je de jaarprijs in op minder dan 12× de maandprijs. De marketingprijspagina detecteert beide varianten en toont een schakelaar voor Maandelijks/Jaarlijks. Elke gateway synchroniseert volgens zijn eigen ritme:

  • Stripe — recurring.interval = month|year op de prijs.
  • PayPal — billing_cycles[].frequency.interval_unit = MONTH|YEAR.
  • Razorpay — period = monthly|yearly op het abonnement.

Werkruimten abonneren zich nog steeds op één abonnementsregel tegelijk (één workspaces.plan_id ), en overschakelen van maandelijks naar jaarlijks is een normale abonnementswijziging — de betalingsgateway berekent ofwel het bedrag pro rata (Stripe / PayPal) of begint de nieuwe cyclus bij de volgende factureringsdatum, afhankelijk van de instellingen van de werkruimte.

AI-limieten

De twee optionele instelknoppen voor limieten (monthly_messages en max_tokens_per_response ) vind je onder "AI-limieten" in het abonnementsformulier. Ze worden tijdens de uitvoering toegepast:

  • Elk bericht van een bezoeker registreert een message-rij in usage_events. MeteredBilling::canSendMessage() telt ze op voor de huidige kalendermaand en onderbreekt de SSE-stream met een message_quota_exceeded-foutmelding zodra het totaal monthly_messages bereikt.
  • MessageStreamController leest maxTokensFor() één keer per beurt (goedkoop — één rij uit het plan van de werkruimte, bij een verzoek dat de controller toch al aan het laden is) en voert deze door zowel de tool-resolutielus als de uiteindelijke streaming-aanroep.

Stripe-synchronisatie

Als een beheerder een betaald abonnement aanmaakt of bijwerkt, zorgt de StripeProductSync -service ervoor dat er een bijpassend Stripe-product + prijs bestaat. Klanten hebben nooit rechtstreeks met Stripe te maken tot het afrekenen — ze kiezen een abonnement in de Blengi-UI en worden via Cashier doorgestuurd naar Stripe Checkout .

Bij prijswijzigingen wordt de oude Stripe-prijs gearchiveerd en wordt er een nieuwe aangemaakt (Stripe-prijzen zijn onveranderlijk). Bestaande abonnementen blijven onder de oude prijs vallen; nieuwe abonnementen gebruiken de nieuwe prijs. Dit is hetzelfde gedrag dat elke Stripe-native SaaS gebruikt.

Abonneren

Via Instellingen › Werkruimte › Abonnement en facturering (/settings/billing ) kan de eigenaar van de werkruimte — de enige rol die deze pagina kan openen — het volgende doen:

  1. Een abonnement kiezen uit de vergelijkingstabel.
  2. Word doorgestuurd naar Stripe Checkout.
  3. Betalen; Stripe stuurt je terug naar /settings/billing met een succesmelding.
  4. De Stripe-webhook werkt de plan_id van de werkruimte bij en maakt een plan_subscription-rij aan.

De opgeslagen kaart wordt beheerd via het Stripe-klantenportaal. De knop Abonnement beheren op /settings/billing opent dit portaal.

Consistentie tussen openbare prijsmatrix en app

De openbare /pricing -vergelijkingstabel en de /settings/billing -abonnementskaarten in de app moeten dezelfde tien rijen met functies weergeven, zodat potentiële klanten geen beperktere aanbieding te zien krijgen dan wat klanten in het product krijgen: Gepubliceerde agents, Maandelijkse gesprekken, AI berichten per maand, werkruimte-leden, werkruimtes per eigenaar, kennisbronnen, workflows, integraties, API-toegang, branding verwijderd. De tests/Feature/Marketing/PricingMatrixParityTest -regressietest zorgt ervoor dat de CI-test mislukt als een rij afwijkt van de openbare matrix.

Quota’s

Het gratis abonnement beperkt het aantal nieuwe gesprekken per maand. De handhaving gebeurt via het hot path — elke /v1/widget/init-aanroep vraagt MeteredBilling::canStartConversation() of de werkruimte onder de limiet van het abonnement zit. Zo niet:

{
    "error": {
        "code": "plan_limit_reached",
        "message": "This workspace has reached its monthly conversation limit. Upgrade to continue."
    }
}

Wordt 429 geretourneerd. De loader van de widget verbergt de launcher op een nette manier wanneer hij dit ziet — bezoekers zien geen foutmelding.

Bestaande gesprekken en menselijke overnames worden niet geblokkeerd. Alleen nieuwe init-aanroepen. Dus een bezoeker die midden in een gesprek zit wanneer je de limiet bereikt, kan zijn of haar thread afmaken.

Boven de limiet: stoppen of blijven beantwoorden

Bij 80 % en bij 100 % van het maandelijkse aantal gesprekken van een abonnement krijgen de eigenaren en beheerders van de werkruimte een e-mail (één keer per drempel per maand). Wat er bij 100 % gebeurt, stel je in onder Instellingen › Facturering:

  • De chat stoppen (standaard): nieuwe bezoekers kunnen pas de volgende maand een gesprek starten; er wordt niets extra in rekening gebracht.
  • Blijf beantwoorden: de chat blijft werken, en elk begonnen blok van 100 extra gesprekken wordt in rekening gebracht op de volgende factuur (op de 1e, als een post op de volgende factuur van het Stripe-abonnement). Alleen bij een betaald abonnement via Stripe; een werkruimte die dit verliest, gaat weer over op ‘stopzetten’.

Een bureau stelt dit per klant in op de klantpagina; de extra gesprekken van zijn klanten komen op de eigen maandelijkse factuur van het bureau.

Overstappen naar een bureau

Een werkruimte die zelf aan Blengi betaalt, kan klant worden van een reseller-bureau, dat de werkruimte vervolgens bedient en factureert. De AI-medewerker, kennis, gesprekken, leads en installatie blijven precies zoals ze zijn; alleen wie de werkruimte bedient en factureert, verandert.

  1. Onder Instellingen › Abonnement en facturering kiest een eigenaar of beheerder het bureau uit de partnerlijst, of voert de code in die het bureau hem of haar heeft gegeven, en gaat ermee akkoord dat het bureau de verwerker van de gegevens van de werkruimte wordt.
  2. De eigenaren van het bureau krijgen een e-mail en nemen de werkruimte over met het abonnement dat ze ervoor hebben gekozen, of ze weigeren het.
  3. Het eigen Stripe-abonnement van de werkruimte wordt aan het einde van de betaalde periode opgezegd, zodat er nergens dubbel voor wordt betaald. Op die dag (vroeg in de ochtend, Amsterdamse tijd) wordt de werkruimte de actieve klant van het bureau; zonder betaalde periode (een proefperiode of het gratis abonnement) gebeurt de overstap meteen.

Tot die dag kan de overstap op dezelfde pagina worden geannuleerd: het abonnement loopt gewoon door zoals voorheen (een abonnement dat je zelf al had opgezegd, blijft opgezegd). Als het bureau vóór die dag stopt met het aannemen van klanten, wordt de overstap op dezelfde manier geannuleerd. Terwijl de overstap op die dag wacht, kan het eigen abonnement hier niet worden hervat of gewijzigd; als je het verlengt via het Stripe-portaal, wordt de overstap geannuleerd, zodat er nergens dubbel wordt betaald. Een abonnement dat via PayPal of Razorpay wordt betaald, wordt eerst opgezegd; een overstap van een bureau terug naar Blengi, of naar een ander bureau, verloopt via het platformteam.

Wat telt als een gesprek

Elke afzonderlijke gespreksregel telt als 1, geactiveerd door IncrementUsageJob wanneer de eerste beurt van het gesprek is voltooid. Playground-gesprekken (is_playground=true ) tellen niet mee, zodat de eigenaren van de agenten vrij kunnen testen.

Hervatte gesprekken tellen niet nog een keer mee — alleen de oorspronkelijke start verhoogt de teller.

Branding verwijderen

Bij abonnementen met features.remove_branding = true wordt de voettekst „Powered by Blengi“ in de widget verborgen. Bij het gratis abonnement is de branding standaard ingeschakeld; bij betaalde abonnementen meestal uitgeschakeld. Het Plan-model maakt dit beschikbaar via $plan->removesBranding(), dat bij het opstarten wordt aangeroepen.

Facturen

Stripe stuurt facturen naar het geregistreerde factuur-e-mailadres. De volledige geschiedenis is beschikbaar in het Stripe-klantenportaal (Kaart beheren → Facturen). Cashier stelt ook $workspace->invoices() aan de serverzijde beschikbaar als je ze in de app wilt weergeven.

Automatische belasting (Stripe Tax)

Blengi kan Stripe Tax de btw/omzetbelasting automatisch laten berekenen op basis van het factuuradres van elke klant. De makkelijkste manier is via het Stripe-statuspaneel op /settings/system (Stripe-kaart): Voer een statuscontrole uit → Schakel Stripe Tax in → voer je bedrijfsadres (hoofdkantoor) in → sla op. Hierdoor worden het herkomstadres + de standaardwaarde exclusief belasting via de Tax Settings API naar Stripe gestuurd en wordt de vlag voor automatische belasting in de app in één stap omgezet — je hebt geen Stripe-dashboard nodig. Het enige dat in het dashboard blijft staan, zijn de belastingregistraties (in welke landen je belasting int) — een wettelijke keuze die Stripe van de handelaar eist (Instellingen → Belasting → Registraties). Stripe Tax is een betaalde Stripe-functie, die wordt gefactureerd per transactie waarbij belasting wordt berekend.

Alternatief op basis van de omgevingsvariabele (gelijkwaardig; de DB-vlag van het paneel zet de functie alleen AAN, dus een bestaande omgevingsvariabele blijft gewoon werken):

CASHIER_AUTO_TAX=true     # .env (default off)
php artisan config:clear

Vanaf dat moment bevat elk nieuw abonnement, elke eenmalige factuur en elke Stripe Checkout-sessie automatic_tax; Checkout verzamelt ook het factuuradres van de klant en biedt automatisch een veld voor het btw-nummer van het bedrijf aan. De eenmalige add-on betalen via factuur maakt zijn factuur rechtstreeks (niet via Cashier), dus kiest deze voor automatic_tax op dezelfde vlag — een add-on-factuur rekent nu belasting en EU-omgekeerde BTW-aanslag op dezelfde manier als een abonnementsfactuur, in plaats van belastingvrij te verzenden.

Let op: nooit met terugwerkende kracht — bestaande actieve abonnementen blijven zonder btw gefactureerd totdat ze afzonderlijk in Stripe worden bijgewerkt. Prijzen worden standaard als exclusief btw behandeld (btw wordt bij het afrekenen erbij opgeteld); als je klanten prijzen inclusief btw, stel dan het belastinggedrag van je Stripe-prijzen in op "inclusief" in het dashboard voordat je dit inschakelt. PayPal / Razorpay worden hierdoor niet beïnvloed — Stripe Tax geldt alleen voor Stripe.

Levenscyclus: annuleren, hervatten, wisselen

De bedieningselementen voor klanten staan op /settings/billing:

  • Abonnement opzeggen . Stripe plant de opzegging in aan het einde van de huidige periode (je behoudt tot dan toegang). PayPal zegt het abonnement onmiddellijk op (bij PayPal is ‘CANCELLED’ een definitieve status). Razorpay plant de opzegging in aan het einde van de cyclus.
  • Abonnement hervatten . Alleen bij Stripe, en alleen als de opzegging nog niet van kracht is (nog steeds binnen de onGracePeriod van Cashier). Een 'CANCELLED'-status bij PayPal kan niet worden hervat; je moet je opnieuw abonneren. Razorpay ondersteunt evenmin het hervatten van een opgezegd abonnement.
  • Van abonnement wisselen (upgraden / downgraden) . Stripe voert een wisseling ter plekke uit, met pro rata berekening op de volgende factuur. PayPal en Razorpay hebben geen nette in-place-wissel, dus als je op een ander abonnement klikt, wordt het huidige abonnement opgezegd en ga je opnieuw naar de kassa. De orphan-cleanup-tak van CheckoutController zorgt ervoor dat je nooit voor beide abonnementen tegelijk betaalt.

E-mail bij wijziging van het abonnement

Als het abonnement van een werkruimte daadwerkelijk verandert, krijgt de eigenaar een bevestigingsmail met de tekst "Je abonnement is gewijzigd naar {nieuw abonnement}" (PlanChangedMail ). Dit is nodig omdat Stripe bij een gewone wissel niets verstuurt : een downgrade is een pro rata -tegoed (geen betaling, dus geen ontvangstmail) en er wordt geen factuur op het moment van de wissel (dus geen factuurmail) — en Stripe verstuurt helemaal geen "abonnement gewijzigd"-mail. Zonder dit hoort een klant die een downgrade doet dus helemaal niets.

De e-mail wordt verstuurd vanuit de bevestigde bron van waarheid — de customer.subscription.updated -webhook (WebhookController::syncWorkspacePlan ), op het moment dat de plan_id van de werkruimte overschakelt naar een ander abonnement — dus het geldt voor in-app-wisselingen, upgrades, downgrades en wijzigingen die rechtstreeks in het Stripe-dashboard worden aangebracht. Hij wordt niet verstuurd bij de eerste aanmelding (customer.subscription.created ) of bij de vele no-op updated -gebeurtenissen die Stripe verstuurt voor verlengingen, kaart- updates en statuswijzigingen (het abonnement is niet veranderd, dus geen e-mail). De verzending gebeurt op basis van ‘best effort’ en wordt in de wachtrij geplaatst: een mislukte e-mailverzending zorgt er nooit voor dat de webhook mislukt.

De proefperiode van 14 dagen

Een nieuw account begint met het Growth-proefabonnement: 14 dagen op het Growth-niveau, zonder kaart. Dat zijn 3 AI- medewerkers, je eigen huisstijl in plaats van "Powered by", de Growth-limieten voor kennisbronnen, teamleden en integraties, API-toegang en alle talen die de AI-medewerker spreekt. Eén limiet geldt specifiek voor de proefperiode: maximaal 300 gesprekken gedurende de hele proefperiode, ook als deze over het einde van een maand heen loopt. Bij 300 start de AI-medewerker geen nieuwe gesprekken meer totdat er een abonnement is gekozen.

Dezelfde proefperiode geldt zowel voor iemand die zich via de website aanmeldt als voor een potentiële klant die zijn demo activeert. Het abonnement kun je bewerken in Beheer › Abonnementen, net als elk ander abonnement (hernoem het, pas de limiet of de looptijd aan); het staat nooit op de prijspagina of tussen de abonnementen waaruit een klant kan kiezen. Een proefaccount heeft één werkruimte.

DagE-mail naar de eigenaar
3, 10 en 13Wat de AI-medewerker heeft gedaan sinds de proefperiode begon: gesprekken met bezoekers, nieuwe leads, de vragen die hij nog niet kon beantwoorden (met een link om de antwoorden toe te voegen), en hoeveel van de 300 gesprekken er zijn gebruikt. Elk bericht eindigt met Kies een abonnement; op dag 13 staat dat de proefperiode morgen afloopt.
7 dagen voor het eindeDe herinnering dat het abonnement afloopt, net als bij elk abonnement dat afloopt.
14De proefperiode loopt af en de werkruimte wordt vergrendeld totdat er een abonnement is gekozen; de onderstaande opruimactie neemt het over.

php artisan trials:progress-mails verstuurt de voortgangs- e-mails elke ochtend om 09:00 uur (Amsterdamse tijd), één per werkruimte. Als er een ochtend wordt overgeslagen, wordt dit de volgende dag ingehaald, nooit later. Een abonnement dat door een platformbeheerder is toegekend, krijgt geen voortgangs-e-mails. Zolang de onderstaande introductieprijs geldt, wordt deze ook in elke voortgangsmelding vermeld.

Introductieprijs

Een werkruimte die tijdens de proefperiode, of uiterlijk 7 dagen na het einde van de proefperiode, een abonnement kiest, krijgt de introductieprijs automatisch bij het afrekenen: Growth voor € 49 per maand in plaats van € 99, voor de eerste drie maanden. Stripe geeft de korting weer op de facturen van maand 1 t/m 3 en rekent vanaf maand 4 de normale prijs, zonder dat iemand daar iets voor hoeft te doen. Dit geldt zowel voor betalen met creditcard als voor betalen via factuur, één keer per werkruimte. Een abonnement dat een beheerder toekent, gaat nooit door de kassa, dus krijgt het nooit die prijs. Tijdens de proefperiode staat de prijs boven de abonnementen op de factureringspagina.

De prijs is een kortingsbon in Beheer › Kortingsbonnen, gemarkeerd als Introductieprijs. Daar maakt een platformbeheerder ook andere kortingsbonnen: een percentage of een vast bedrag korting, voor een aantal maanden, voor sommige abonnementen of alle betaalde abonnementen, en met een maximum aantal keren dat je ‘m kunt gebruiken. Een kortingsbon wordt in Stripe aangemaakt zodra deze voor het eerst bij het afrekenen wordt gebruikt en kan daarna niet meer worden gewijzigd; schakel hem uit en maak een nieuwe aan met een andere waarde. Meerdere kortingsbonnen kunnen worden gemarkeerd als ‘introductieprijs’; bij het afrekenen wordt de eerste gebruikt die bij het gekozen abonnement past. Een kortingsbedrag is in de valuta waarin de installatie de kosten in rekening brengt.

De jaaraanbieding in maand 3

In de laatste maand van de introductieprijs krijgt de eigenaar een e-mail: wanneer de prijs afloopt, wat het abonnement vanaf dan kost, en hetzelfde abonnement dat jaarlijks wordt betaald met twee maanden gratis. De jaarprijs is de eigen jaarprijs van het abonnement (Beheer › Abonnementen), anders tien keer de maandprijs. Als je ‘Overstappen naar jaarabonnement’ klikt , gaat de factureringspagina open, waarop de aanbieding te zien is met een knop, zolang de werkruimte nog kan overstappen: het Stripe- abonnement wordt meteen omgezet naar de jaarprijs, de rest van de maand wordt gecrediteerd en de introductiekorting stopt. Een abonnement dat via PayPal of Razorpay wordt betaald, of in een andere valuta, komt niet in aanmerking voor de aanbieding. php artisan billing:annual-offer-mails verstuurt de e-mail elke ochtend om 09:15 uur (Amsterdamse tijd), één keer per abonnement.

Proefaccounts die nooit betalen

Een proefperiode die afloopt zonder aankoop vergrendelt de werkruimte: elke pagina behalve Abonnement en Facturering stuurt de eigenaar door om een abonnement te kiezen. Een vergrendeld account blijft niet voor altijd zo:

WanneerWat gebeurt er
De proefperiode eindigt, er is niets betaaldDe werkruimte wordt vergrendeld, net als voorheen.
30 dagen vergrendeldDe eigenaar krijgt: We ruimen je account over 14 dagen op, met een knop om een abonnement te kiezen en een link om het account te behouden. Als je het account behoudt, begint de klok opnieuw te lopen: de werkruimte blijft vergrendeld en de e-mail komt 30 dagen later weer binnen.
14 dagen na die e-mail, zonder antwoordDe werkruimte wordt verwijderd, samen met de AI-medewerkers, kennis, gesprekken en bestanden, en dat geldt ook voor de gebruikers die geen andere werkruimte hebben. De vectoren gaan als eerste; één auditvermelding legt dit vast, zonder persoonlijke gegevens.

Wordt nooit automatisch verwijderd: een werkruimte waarvoor betaald is of waarvoor een poging tot betaling is gedaan (een creditcard, PayPal- of Razorpay-abonnement, betaling via factuur, een add-on, een levenslange deal), een werkruimte met een abonnement dat door een platformbeheerder is toegekend, een werkruimte die eigendom is van of toebehoort aan een platformbeheerder, en een werkruimte die is gemarkeerd met ‘Nooit verwijderen ’. De extra werkruimtes van een bedrijfseigenaar hebben het abonnement van de eigenaar als een actief abonnement, dus die worden nooit vergrendeld en nooit verwijderd. Zolang er geen partnerwerkruimtes bestaan, blijven ze behouden volgens het toegekende abonnement.

Een werkruimte waar nooit voor is betaald maar die ook geen proefperiode heeft (het gratis abonnement van de eerste aanmeldingen) wordt nooit vergrendeld, dus de nachtelijke run laat deze met rust. Deze staat ook op de opruimlijst, en alleen een platformbeheerder verwijdert hem daar.

Beheer › Opruimen (/admin/cleanup , platformbeheerders ) is de proefrun: elke vergrendelde werkruimte, de bijbehorende AI-medewerkers en gesprekken, wanneer de proefperiode afliep, de volgende stap en de datum daarvan, en de gebruikers die daarbij horen. Vink rijen aan om ze Nu te verwijderen (dit is de goedkeuring) of om ze te markeren als Nooit verwijderen . Er wordt niets automatisch verzonden of verwijderd totdat een platformbeheerder de automatische opruiming daar inschakelt; vanaf dat moment draait php artisan trials:cleanup elke nacht om 03:50 (--dry-run geeft aan wat er zou gebeuren en verandert niets).

Afstemming na het afrekenen

De SubscriptionReconciler-service is het vangnet voor de aflevering van webhooks. Na een succesvolle afrekening wordt de klant doorgestuurd naar /settings/billing?checkout=success (Stripe voegt ook session_id={CHECKOUT_SESSION_ID} toe) en haalt de controller de actuele abonnementsstatus rechtstreeks op uit de gateway, waarbij workspace.plan_id in-band wordt omgezet. De pagina toont het juiste abonnement, zelfs als:

  • Het Stripe-webhook-eindpunt nog niet is geregistreerd in het Stripe-dashboard van de klant (komt vaak voor bij een nieuwe installatie).
  • De webhook wordt geactiveerd, maar ons eindpunt is even offline / de handtekening klopt niet / het wordt geweigerd door een upstream WAF.
  • De webhook komt uiteindelijk wel aan, maar dat duurt meer dan 30 seconden, waarin de klant de factureringspagina vernieuwt en in paniek raakt.

De reconciler is idempotent — je kunt hem veilig bij elke paginalading aanroepen. De webhook doet nog steeds hetzelfde, wanneer hij ook binnenkomt; de twee paden komen samen op dezelfde rij in plan_subscriptions.

Betalen via factuur (bankoverschrijving)

Voor B2B-kopers in de EU waarvan de boekhoudafdelingen facturen betalen in plaats van met een kaart, kan de kassa naast de kaartprocedure ook een ‘Betalen via factuur ’-optie aanbieden. Het maakt gebruik van de send_invoice -abonnementen van Stripe Billing (Cashier’s createAndSendInvoice ): Stripe genereert de factuur, stuurt deze per e-mail met instructies voor de bankoverschrijving, berekent de btw, volgt de betaling, verstuurt herinneringen en voert aanmaningen uit bij niet-betaling. Geen intern facturatiesysteem nodig.

  1. Eenmalige stap in het Stripe-dashboard: Instellingen → Facturering → Facturen → betaalmethoden — schakel Bankoverschrijving in. Dit kun je niet via de API instellen. Prijzen in EUR zijn verplicht voor SEPA-overschrijvingen (zie Valuta hierboven).
  2. Schakel dit in Blengi in: /settings/system → Stripe kaart → selectievakje „Betalen via factuur“ + aantal dagen tot de vervaldatum (standaard 30).

Werkwijze: de koper kiest een abonnement → selecteert Betalen via factuur in de keuze voor betaalmethoden → vult bedrijfsnaam, adres en een optioneel EU-btw-nummer in (opgeslagen als Stripe-klantbelasting-id) → Stripe stuurt de factuur per e-mail. Het abonnement wordt pas geactiveerd als de factuur is betaald — het abonnement bestaat wel meteen op Stripe (status active), maar workspace.plan_id activeert pas de invoice.payment_succeeded webhook, nooit eerder. De success-URL-reconciler negeert bewust send_invoice abonnementen, zodat een speciaal vervaardigd ?checkout=success-bezoek geen onbetaald abonnement zelf kan activeren. Bij niet-betaling start Stripe’s aanmaningsprocedure; de uiteindelijke customer.subscription.deleted zet de werkruimte terug naar Free. Een onbetaalde verlenging doorloopt ook de onderstaande betalingsstappen, zodra een platformbeheerder deze heeft ingeschakeld (zie Wanneer een verlengingsfactuur onbetaald blijft).

Op de factureringspagina zie je een banner ‘openstaande factuur’ met een opvallende knop Factuur bekijken die doorverwijst naar de gehoste Stripe-factuur (inclusief bankgegevens) totdat de betaling binnenkomt. Verlengingsfacturen volgen automatisch hetzelfde ritme van send_invoice.

Openstaande facturen worden ook weergegeven. De factuurgeschiedenis (en de bannerlink) roepen $workspace->invoices(true) op — het formulier ‘inclusief openstaande facturen’. De standaardweergave van Cashier invoices() toont alleen betaalde facturen, waardoor voorheen de enige OPEN factuur van een koper die via factuur betaalt volledig verborgen bleef: zowel de rij in de geschiedenis als de gehoste link voor de bankoverschrijving verdwenen totdat de factuur was betaald. Door true door te geven, wordt de openstaande factuur weer zichtbaar, zodat de koper altijd een klikbare weg naar de IBAN-instructies heeft.

De factuur wordt bij het afrekenen meteen afgerond en per e-mail verstuurd: Stripe zou anders de eerste factuur van het abonnement ongeveer 60 minuten als concept bewaren, voordat deze automatisch wordt afgerond en verzonden. Bij het afrekenen wordt de factuur afgerond en expliciet verzonden (best-effort — bij een storing bij Stripe zorgt de uitstelperiode voor automatische afronding er nog steeds voor dat de factuur binnen een uur wordt verzonden).

De factuur wordt gemaild naar het e-mailadres van de Stripe-klant — standaard het adres van de eigenaar van de werkruimte (Workspace::stripeEmail() ). Stripe-klanten die zijn aangemaakt voordat dit contract bestond, hebben mogelijk geen e-mailadres; het facturatieproces vult het e-mailadres van de eigenaar automatisch bij, maar overschrijft nooit een e-mailadres dat al bij de klant is ingesteld (dit kan een opzettelijk gewijzigde boekhoudinbox zijn in het Stripe-dashboard).

Instructies voor bankoverschrijvingen (IBAN) op de factuur

Stripe staat bankoverschrijving alleen toe als standaardbetaalmethode voor USD en GBP. Voor EUR (en alle andere valuta’s) moet dit per factuur via de API worden toegevoegd — dus stelt de kassa payment_settings.payment_method_types = [customer_balance, card] in met bank_transfer.type, afgeleid van de factuurvaluta (eur → eu_bank_transfer, gbp → gb_bank_transfer, usd → us_bank_transfer, enz.). Zonder dit wordt een factuur in EUR verzonden zonder IBAN en kan de bankoverschrijving niet worden betaald. De eu_bank_transfer IBAN wordt uitgegeven in het land van de koper als het een ondersteund land in de eurozone is (BE/DE/ES/FR/IE/NL), anders in het door de exploitant geconfigureerde bankland (STRIPE_BANK_TRANSFER_COUNTRY, standaard NL).

Dit gebeurt automatisch — de exploitant hoeft NIETS in te schakelen in het Stripe-dashboard voor EUR en hoeft zijn eigen bankrekening NIET op de factuur te zetten. Stripe levert het virtuele IBAN en verwerkt de overschrijving automatisch in het saldo van de klant, waardoor de factuur wordt betaald en invoice.payment_succeeded wordt geactiveerd → activering van het abonnement.

Veiligheidsmaatregelen voor openstaande facturen

  • Geen dubbele abonnementen: zolang een factuur onbetaald is, worden zowel de kaartbetaling als het wisselen van abonnement geblokkeerd met een actieerbare foutmelding — anders zou de koper uiteindelijk twee Stripe-abonnementen hebben die elke cyclus worden gefactureerd, of zou de onbetaalde factuur die de boekhouding al heeft ontvangen, opnieuw in rekening worden gebracht. De status ‘in behandeling’ wordt bijgehouden als een unpaid-rij in plan_subscriptions, die wordt bijgeschreven bij het afrekenen en door de abonnements-webhook, en wordt omgezet naar active door de webhook voor betaalde facturen. Zodra de eerste factuur is betaald, volgt een verlenging van hetzelfde abonnement volgens Stripe: active zolang de factuur open is, past_due zodra deze achterstallig is (voorheen zette elke verlenging de rij weer terug naar unpaid, alsof het een nieuwe aankoop was met een knop Factuur annuleren). Een overstap naar een ander abonnement wacht nog steeds als unpaid op zijn eigen factuur.
  • Annuleren en opnieuw proberen: de banner voor openstaande facturen heeft een knop Factuur annuleren (POST billing/checkout/invoice/cancel) die de openstaande factuur ongeldig maakt, het Stripe-abonnement opzegt en de markering verwijdert, zodat de koper opnieuw kan afrekenen — met een kaart of via een nieuwe factuur.
  • BTW-validatie: als Stripe een BTW-nummer afwijst, wordt het afrekenen afgebroken met een inline vat_id-foutmelding voordat er een abonnement is aangemaakt. Een EU-B2B-factuur die wordt uitgegeven zonder het btw-nummer van de koper zou btw in rekening brengen in plaats van deze via verlegging af te dragen . Tijdelijke storingen bij Stripe of het netwerk tijdens het opslaan van het btw-nummer blokkeren de factuur niet.
  • Webhook-herpogingen gaan door na storingen: als een webhook tijdens de verwerking een fout geeft (bij elke gateway), wordt de idempotentie-claim vrijgegeven, zodat de automatische herhaling van de gateway de gebeurtenis opnieuw verwerkt in plaats van te horen krijgen dat deze ‘al verwerkt’ is — een betaalde factuur kan nooit definitief verloren gaan door een tijdelijke 500-fout.

Als een verlengingsfactuur onbetaald blijft

Voor klanten die via factuur betalen, verloopt een onbetaalde verlenging volgens dezelfde stappen als de factuur van een bureau. Dag 0 is de dag waarop de verlengingsfactuur de vervaldatum heeft gepasseerd (Stripe markeert het abonnement als achterstallig). Vanaf dat moment, elke ochtend:

DagWat gebeurt er
0De eigenaren en beheerders krijgen een herinnering die verwijst naar ‘Abonnement en facturering’, waar de openstaande factuur en de bijbehorende bankgegevens staan.
7Een tweede herinnering met de data van de volgende stappen, en een banner bovenaan het dashboard.
14Er kunnen geen nieuwe AI-medewerkers worden toegevoegd; de bestaande blijven gewoon antwoorden.
25De mededeling: de chats stoppen over vijf dagen.
30De AI-medewerkers beginnen geen nieuwe gesprekken (er wordt niets verwijderd).
  • De chats stoppen nooit zonder de melding vijf dagen van tevoren, ook niet als de stappen te laat beginnen.
  • Zodra Stripe meldt dat de factuur is betaald, gaat alles meteen weer door en krijgen de eigenaren een e-mail waarin dat wordt vermeld.
  • Uitzonderingen: een werkruimte met een door het platform toegekend abonnement, een werkruimte die eigendom is van een platformbeheerder, een klant van een bureau (de eigen factuur van het bureau doorloopt deze stappen wel) en systeemwerkruimtes.

Stripe-statuspaneel

De Stripe-kaart op /settings/system bevat een Stripe-statuspaneel dat de verbinding van begin tot eind controleert zonder de app te verlaten:

  • Geheime sleutel — geldig? Test- of live-modus?
  • Webhook — bestaat het automatisch aangemaakte eindpunt onder de huidige sleutel, verwijst het naar deze app, bevat het alle vereiste gebeurtenissen (incl. checkout.session.expired), en hebben we een ondertekeningsgeheim lokaal opgeslagen? Na een omschakeling van test- naar live-sleutel hoort het opgeslagen eindpunt nog bij de oude modus — de knop Webhook herstellen maakt het opnieuw aan onder de nieuwe sleutel en haalt automatisch de nieuwe ondertekeningssleutel op.
  • Stripe Tax — lokaal ingeschakeld, geactiveerd op Stripe, adres hoofdkantoor ingesteld, aantal registraties.

Alle controles zijn alleen-lezen en op basis van ‘best effort’: fouten worden weergegeven als oranje rijen met het Stripe-foutbericht, nooit als een uitzonderingspagina.

Aangepaste abonnementen

Abonnementen met price_cents = 0 zijn niet gratis in de zin van de klant — ze zijn alleen lokaal, worden nooit gesynchroniseerd met Stripe en worden gebruikt voor zelf samengestelde zakelijke deals of ter vervanging van het gratis abonnement. Beheerders maken ze op dezelfde manier aan; de Stripe-synchronisatie wordt gewoon overgeslagen.

Aankoop van add-ons

Bezoekers die een abonnement kiezen bij /settings/billing kunnen eventueel een eenmalige dienst (Professional AI Setup, enz.) toevoegen aan dezelfde Stripe Checkout-sessie. Geselecteerde add-ons worden verwerkt via het addon_slug-formulierveld op POST /billing/checkout.

Werking:

  • De controller zoekt de slug op aan de hand van plan_addons waar is_active=true staat; onbekende of inactieve slugs worden stilletjes genegeerd, zodat een verouderde link nooit de aankoop van het abonnement blokkeert.
  • Een Stripe-prijs voor de add-on wordt pas bij de eerste aankoop (StripeProductSync::ensurePriceForAddon) gegenereerd en in de cache van de add-on-rij opgeslagen.
  • De afrekensessie wordt rechtstreeks via de Stripe SDK aangemaakt met mode=subscription + twee regelitems (de prijs van het doorlopende abonnement + de eenmalige prijs van de add-on). De vloeiende newSubscription()->checkout()-helper van Cashier ondersteunt GEEN regelitems in gemengde modus.
  • Een workspace_addon_purchases-rij wordt vooraf aangemaakt met status=pending + de Stripe Checkout- sessie-id voordat de koper naar Stripe wordt doorgestuurd. De sessie-id is het idempotente anker dat de webhook gebruikt om de rij om te zetten naar paid op invoice.payment_succeeded.
  • Als de add-on faalt (Stripe-prijsverwerking, netwerkstoring, wat dan ook), MAG dit het abonnement NIET blokkeren — de add-on wordt verwijderd en de koper abonneert zich alleen op het abonnement. Het Stripe- team kan de add-on later opnieuw aanbieden via de Services-UI in de werkruimte (volgende fase 2-kaart).
  • PayPal en Razorpay ondersteunen geen gemengde regelitems; als je addon_slug doorgeeft via een niet-Stripe-gateway, krijg je een vriendelijke foutmelding die de koper naar Stripe verwijst.

Valuta van de add-on. De prijs van een add-on is één valuta-onafhankelijk getal; deze wordt weergegeven en in rekening gebracht in de valuta waarin de beheerder de add-on implementeert — de "standaard" valuta — op elk platform: de Services-cataloguskaart, de afrekening met een opgeslagen kaart, de gehoste Checkout (een koper zonder opgeslagen kaart) en het betalen-op-factuur-proces. De enige uitzondering is een werkruimte die bij het afrekenen bewust een andere valuta heeft gekozen (preferred_currency , wat standaard usd is voor elke werkruimte, dus — net als bij de valutaresolver — telt alleen een waarde die niet usd is als een bewuste keuze). De door de add-on zelf aangemaakte valuta wordt bewust niet gebruikt: bij een EUR-implementatie wordt EUR weergegeven en in rekening gebracht, zelfs als de SKU in USD is aangemaakt (de afwijking die een klant meldde), en de geregistreerde workspace_addon_purchases.currency komt altijd overeen met wat er in rekening is gebracht. De gehoste Checkout factureert een ad-hoc price_data -regelitem in die valuta in plaats van een opgeslagen Stripe-prijs per valuta. (De aparte gebundelde Checkout met plan + add-on gebruikt nog steeds de Stripe-prijs voor één valuta van de add-on.)

Zie Eenmalige add-ons voor het beheren van de add-on-catalogus.