Providerhandleidingen
Mollie: instellen en beheren
Bied Mollie-checkout aan met terugbetalingen, statussynchronisatie en ondersteuning voor terugkerende betalingen.
Op deze pagina
Werkwijze bij de provider
Bied Mollie-checkout aan met terugbetalingen, statussynchronisatie en ondersteuning voor terugkerende betalingen. De uitbreiding bewaart de koppeling tussen Agovena-klanten en Mollie-klant- of mandaatreferenties. De beschikbare betaalmethoden verschijnen in de gehoste checkout van Mollie.
Productiestatus
De uitbreiding is productierijp voor de huidige Agovena-integratiescope. Ze is geverifieerd tegen de Mollie-testomgeving voor betaalde, mislukte, geannuleerde en verlopen betalingen, statussynchronisatie, volledige en gedeeltelijke refunds, recurring mandate-afhandeling, idempotency, veilige providerfouten en provider-discovered betaalmethoden. Configureer een publieke HTTPS-APP_URL; Agovena stuurt dan de productie-webhook /webhooks/payments/mollie naar Mollie. Lokale developmenthosts worden bewust weggelaten omdat Mollie die niet kan bereiken.
Agovena Core ^0.0.1. Het manifest noemt geen extra pakketafhankelijkheid. Een provideraccount en toegang tot de externe dienst staan los van de pakketinstallatie.
Het pakket instellen
Vul api_key in. De Admin-instellingen halen de betaalmethoden op die voor het Mollie-account beschikbaar zijn. Selecteer welke methoden in de Agovena-checkout verschijnen. Bij een nieuwe configuratie worden alle gevonden methoden standaard geselecteerd en er moet altijd minstens één methode actief blijven. Mollie levert hiervoor de officiële SVG-URL’s. Begin met een testsleutel. Dit manifest heeft geen aparte sandboxschakelaar: de API-sleutel bepaalt de omgeving. Core bevat mollie/mollie-api-php. Voer de migraties van de uitbreiding uit voordat je opgeslagen mandaatkoppelingen gebruikt.
Een Mollie API-key aanmaken
- Open het Mollie Dashboard en ga naar Developers > API keys.
- Klik op Create API key.
- Geef de key een herkenbare omschrijving, bijvoorbeeld
Agovena testofAgovena production. - Kies Standard API key. Gebruik voor Agovena niet Advanced access token; die optie is bedoeld voor andere integraties met fijnmazige permissions.
- Kies Test tijdens de testfase. Kies pas Live wanneer je productieomgeving klaar is. Gebruik nooit een test-key met live betalingen of andersom.
- Kies het payment profile dat bij deze winkel hoort en maak de key aan.
- Kopieer de volledige key direct naar de beschermde Agovena Extension settings. Publiceer de key niet en zet hem nooit in screenshots, commits, issue trackers of chat.
Mollie configureren in Admin
- Open Admin > Extensions en activeer Mollie.
- Vul de
test_...-sleutel in tijdens het testen of delive_...-sleutel voor productie. - Sla de sleutel op in de beschermde Extension settings. Agovena toont een opgeslagen sleutel niet opnieuw.
- Controleer de verbindingsstatus en selecteer de betaalmethoden die in de checkout mogen verschijnen.
- Gebruik Refresh payment methods nadat je de actieve methoden in je Mollie-profiel hebt gewijzigd.
De screenshot toont een gemaskeerde sleutel en de nieuwe creditcard-icon zonder witte achtergrond. De Webhook URL wordt door Agovena gebruikt voor provider-callbacks. Mollie gebruikt geen apart webhook signing secret in deze integratie.
Bij provisioned services met recurring billing kan de klant bij checkout kiezen tussen handmatig en automatisch hernieuwen. Bij handmatig hernieuwen wordt vooraf een invoice aangemaakt. Automatisch hernieuwen gebruikt het herbruikbare Mollie-mandaat wanneer de eerste betaling dat heeft ingesteld.
Providerspecifieke grenzen
De adapter gebruikt https://shop.example.com/webhooks/payments/mollie als webhookUrl, met de ingestelde applicatiehostnaam. Anders dan bij Stripe bestaat hier geen veld voor een webhookgeheim. Verificatie gebeurt door de genoemde betaling met de ingestelde API-sleutel op te halen. Dat sluit aan bij de betaalwebhook van Mollie. Vervang die controle niet door een status die de browser meestuurt.
Test de openbare bereikbaarheid van het endpoint en controleer dat een geldige testbetaling alleen de bijbehorende Agovena-poging wijzigt. Willekeurige ID’s mogen geen betaalbevestiging veroorzaken. Test annulering en een gedeeltelijke terugbetaling afzonderlijk. Controleer voor abonnementen dat een eerste betaling een bruikbaar mandaat oplevert en dat dit bij de juiste klant hoort. Houd test- en liveklantkoppelingen gescheiden wanneer je van omgeving wisselt. 2
Configuratiecontract
| Veld | Type | Verplicht | Geheim | Standaard |
|---|---|---|---|---|
api_key |
string |
Ja | Ja | Leeg |
enabled_methods |
payment_methods |
Nee | Nee | Alle door de provider gevonden methoden |
Dit zijn de velden uit het manifest. Een optioneel veld kan voor een API-handeling toch noodzakelijk zijn, zoals hierboven beschreven. Bewaar geheime waarden alleen in beschermde instellingen, nooit in productbeschrijvingen, URL’s of gedeelde voorbeelden. 1
Werking en foutafhandeling
Een Mollie-melding bevat een betaal-ID, geen vertrouwde betaalstatus. De adapter haalt de betaling op via de geauthenticeerde API voordat de status wordt vertaald. Een onbekende of onbereikbare betaling wordt niet als betaald aangemerkt. Terugkerende incasso mislukt bij ontbrekende autorisatie. Transportproblemen kunnen een onbekende uitkomst opleveren. Controleer die voordat je opnieuw probeert. Annulering is alleen mogelijk als Mollie de betaling annuleerbaar noemt.