Stripe: instellen en beheren

Status en werkwijze

De Stripe-extension is production-ready voor de huidige Agovena-contracten. De extension ondersteunt Stripe test mode en live mode, provider-discovery van Checkout-methoden, country-aware filtering, ondertekende webhooks, idempotente verwerking, statusreconciliation, volledige en gedeeltelijke terugbetalingen en ondersteunde off-session charges.

Agovena verzamelt geen ruwe kaartgegevens. Stripe Checkout blijft de hosted payment surface. Een return URL is alleen een gebruikerssignaal. Alleen een geverifieerde Stripe-webhook of een provider-statussync mag een betaling als betaald bevestigen.

Vereisten

• Agovena Core ^0.0.1.
• Een Stripe-account met de gewenste betaalmethodes geactiveerd.
• Voor lokale tests: Stripe CLI en een lokale Agovena-installatie.
• Voor live gebruik: een publiek HTTPS-domein, correcte serverklok en een live Stripe-webhook endpoint.
• De Core dependency set bevat stripe/stripe-php.

Production-ready betekent hier dat de packagecode, contracten, failure handling en testdekking voor het huidige integratieoppervlak zijn afgerond. Een echte live providercontrole blijft een operationele stap die je met je eigen Stripe-account uitvoert.

Het pakket instellen

Een Stripe API-key aanmaken

1. Open het Stripe Dashboard en ga naar Developers > API keys.
2. Gebruik voor een eenvoudige serverintegratie de knop Geheime sleutel maken onder Standaardsleutels. Agovena heeft een server-side secret key nodig en kan niet met een publishable pk_... key werken.

3. Geef de key een herkenbare naam, bijvoorbeeld Agovena test of Agovena production.
4. Gebruik je organisatiebeleid voor least privilege? Kies dan Beperkte sleutel maken en geef alleen de permissions die je actuele Stripe-integratie nodig heeft. Stripe kan deze lijst per account of Dashboard-versie anders tonen. Schakel niet blind alle permissions in.

5. Kopieer de secret key alleen naar de beschermde Agovena Extension settings. Publiceer de key nooit in screenshots, commits, issue trackers of chat.
6. Gebruik tijdens het testen een sk_test_...-sleutel. Maak voor productie een aparte sk_live_...-sleutel en gebruik die nooit met test-events.

Agovena configureren

1. Open Admin > Extensions en activeer Stripe.
2. Gebruik eerst een sk_test_...-sleutel tijdens de testfase.
3. Gebruik voor de webhook een signing secret die begint met whsec_.
4. Sla beide waarden op in de beschermde Extension settings. Agovena bewaart geheime instellingen encrypted en toont opgeslagen waarden niet opnieuw.
5. Laat enabled_methods leeg om alle door Stripe beschikbare methodes te gebruiken, of selecteer alleen de methodes die je wilt aanbieden.
6. Controleer de connection health. De melding benoemt of de ingestelde key test mode of live mode gebruikt.

Gebruik altijd een sk_test_...-key met een test webhook secret en een sk_live_...-key met de signing secret van het live Dashboard-endpoint. Agovena weigert een geverifieerde webhook wanneer de Stripe-waarde livemode niet overeenkomt met de ingestelde key mode.

Gebruik echte waarden alleen in de beschermde Admin Extension settings. Gevoelige providercredentials worden bewust niet via generieke environment overrides gelezen, zodat een environment variable encrypted opgeslagen settings niet kan omzeilen. Commit ze nooit, zet ze niet in screenshots en plak ze niet in issue trackers of chat.

Payment methods en landfiltering

Agovena haalt de actieve Payment Method Configuration via Stripe op en cached de discovery. Een expliciete Refresh payment methods haalt providerinformatie opnieuw op. De checkout gebruikt alleen methodes die door Stripe worden gemeld en die voor het billing country van de klant beschikbaar zijn.

Voorbeelden van de gedeelde country-regels:

• iDEAL wordt alleen voor Nederland aangeboden.
• Bancontact wordt alleen voor België aangeboden.
• BLIK en Przelewy24 worden aan Polen gekoppeld.
• EPS wordt aan Oostenrijk gekoppeld.
• TWINT wordt aan Zwitserland gekoppeld.

De checkoutfilter is geen security boundary op zichzelf. De server valideert dezelfde methode opnieuw wanneer de order wordt geplaatst. Een gemanipuleerde request kan daardoor geen methode gebruiken die niet voor het billing country is toegestaan.

Een geselecteerde methode zoals stripe:bancontact wordt als payment_method_types aan de Stripe Checkout Session meegegeven. Als er geen specifieke methode wordt gekozen, gebruikt Agovena de actieve, provider-discovered selectie.

Webhook endpoint

Gebruik deze route:

POST https://shop.example.com/webhooks/payments/stripe

Gebruik in productie altijd je echte HTTPS-hostnaam. Stripe stuurt de raw request body en de Stripe-Signature header. Agovena valideert de signature met de officiële Stripe PHP SDK voordat de payload wordt verwerkt. De raw body mag vóór verificatie niet worden geparsed en opnieuw geëncodeerd.

Configureer minimaal deze event types:

Een refund wordt lokaal alleen als completed gemarkeerd wanneer Stripe status succeeded terugstuurt. pending blijft in reconciliation/manual review en failed of canceled faalt veilig.

Een geverifieerd event wordt idempotent opgeslagen op gateway en Stripe event ID. Herhaalde aflevering veroorzaakt geen tweede betaling, fulfillment of refund. Als een event nog geen bekende Agovena payment attempt kan vinden, wordt het gedeferd voor reconciliation in plaats van blind toegepast.

Bij een netwerk-timeout mag je niet meteen opnieuw belasten. Controleer eerst de bestaande PaymentAttempt en gebruik status synchronization of reconciliation. Onzekere refundresultaten blijven pending totdat de providerstatus is gecontroleerd.

Stripe CLI voor lokaal testen

Installeer de officiële CLI. Met Node.js 18 of nieuwer kan dat via npm:

npm install -g @stripe/cli

Log in via de officiële browserflow:

stripe login

Start de lokale Agovena-server op poort 8000 en forward Stripe test-events naar de echte Agovena-route:

stripe listen --forward-to http://127.0.0.1:8000/webhooks/payments/stripe

De CLI toont daarna een tijdelijke signing secret die met whsec_ begint. Zet die waarde tijdelijk in Admin > Extensions > Stripe > Webhook signing secret. Gebruik de CLI-secret niet voor een Dashboard-endpoint en deel hem nooit.

Je kunt voor signature- en mapper-smoke tests provider-events triggeren:

stripe trigger payment_intent.succeeded
stripe trigger payment_intent.payment_failed

Deze CLI-triggers hebben niet automatisch de metadata van een bestaande Agovena-order. Ze bewijzen dus alleen dat forwarding, signature verification en event mapping werken. Een echte orderstatus test je door een test Checkout vanuit Agovena te starten en daarna de doorgestuurde event delivery en de payment status te controleren.

Stop forwarding met Ctrl+C.

Live webhook configureren

Voor productie gebruik je een endpoint in Stripe Live mode. Stripe CLI is alleen bedoeld voor lokale test-events en vervangt het live Dashboard-endpoint niet.

1. Open Stripe Webhooks in Live mode

1. Open het Stripe Dashboard en schakel rechtsboven naar Live mode.
2. Ga naar Developers > Webhooks.
3. Kies Add destination of Add endpoint. De exacte knopnaam kan per Stripe Dashboard-versie verschillen.
4. Kies account-events wanneer Stripe om een eventbron vraagt.

2. Selecteer de Agovena-events

Selecteer minstens deze events:

• checkout.session.completed
• checkout.session.async_payment_succeeded
• checkout.session.async_payment_failed
• checkout.session.expired
• payment_intent.succeeded
• payment_intent.payment_failed
• payment_intent.canceled
• charge.refunded

De afbeelding toont de vier events in de groep Checkout. Als je Alle gebeurtenissen van Checkout selecteren gebruikt, moet je daarna nog naar de groepen voor Payment intents en Charges scrollen om de overige events apart te selecteren.

Klik daarna op Continue.

3. Vul de productie-endpoint in

Geef de bestemming een herkenbare naam, bijvoorbeeld Agovena payments, en gebruik je echte publieke HTTPS-hostnaam:

https://shop.example.com/webhooks/payments/stripe

Vervang shop.example.com door jouw domein. Gebruik geen localhost, een intern IP-adres of de lokale Stripe CLI-route in productie.

Klik op Create destination of de vergelijkbare knop om het endpoint aan te maken.

4. Kopieer de live signing secret

Open daarna de details van precies dit live endpoint en kies Reveal signing secret. Kopieer de waarde die met whsec_ begint.

• Gebruik de secret van dit live Dashboard-endpoint, niet die van een test-endpoint.
• De Stripe CLI toont voor lokale forwarding een andere tijdelijke secret.
• Zet een signing secret nooit in een screenshot, commit, issue of chatbericht.

5. Vul de waarden in Agovena in

1. Open Admin > Extensions > Stripe.
2. Vul de live sk_live_... API-key in bij Secret key.
3. Vul de live whsec_... signing secret in bij Webhook signing secret.
4. Klik op Save en controleer de connection health.
5. Gebruik Refresh payment methods wanneer je betaalmethodes in Stripe hebt gewijzigd.

Laat de velden na het opslaan leeg wanneer Agovena meldt dat er al een secret is opgeslagen. De bestaande secret blijft dan behouden. De afbeelding toont gemaskeerde velden en is geen voorbeeld waarin echte secrets zichtbaar mogen zijn.

6. Controleer de webhook-delivery

Open in Stripe het aangemaakte endpoint en controleer Events of Deliveries. Een geslaagde aflevering krijgt een HTTP 2xx-respons. Controleer bij fouten eerst:

• publiek HTTPS en geldige TLS;
• de exacte route /webhooks/payments/stripe;
• een live sk_live_... key met de live signing secret;
• serverklok en queueverwerking;
• Agovena- en webserverlogs zonder secrets of volledige gevoelige payloads.

Een test-endpoint en live-endpoint hebben verschillende secrets. Gebruik Stripe CLI forwarding voor lokale test-events, niet als vervanging voor het live Dashboard-endpoint.

Plan key- en webhook-secretrotatie in een gecontroleerd onderhoudsmoment. Agovena ondersteunt één actieve webhook secret per configuratie. Werk de secret in Stripe en Agovena gecoördineerd bij en controleer daarna opnieuw een delivery. Als een secret mogelijk gelekt is, roteer hem direct via Stripe en vervang hem in Agovena zonder de oude waarde te delen.

Operationele controle vóór ingebruikname

Controleer met test mode:

1. succesvolle Checkout en webhookbevestiging;
2. afgebroken Checkout zonder betaalde order;
3. mislukte PaymentIntent;
4. duplicate webhook delivery;
5. volledige en gedeeltelijke refund;
6. status synchronization na een gesimuleerde transport-timeout;
7. landfiltering, bijvoorbeeld geen iDEAL voor een Belgische billing address;
8. off-session renewal alleen met een ondersteunde opgeslagen authorization.

Controleer vóór live gebruik daarnaast:

• publiek HTTPS en geldige TLS-configuratie;
• serverklok via NTP;
• queue en scheduler volgens je deploymentmodel;
• logging zonder API-keys, webhook secrets, kaartgegevens of volledige gevoelige payloads;
• een gecontroleerde live webhook delivery in Stripe;
• een afgesproken reconciliation- en refundprocedure.

Configuratiecontract

Bronnen:

• Stripe extension manifest
• StripePaymentGateway.php
• Stripe CLI installeren
• Stripe CLI en lokale webhooks
• Stripe webhook best practices