Payment gateway integreren: gids voor developers en finance

De webshop draait, de abonnementen lopen en de klanten betalen met iDEAL, kaart of incasso. Maar achter de schermen kopieert iemand elke week betaalgegevens uit het ene systeem naar het andere, en de salarisbetaling liep vorige maand vast op een datum in het verkeerde formaat.

Een payment gateway integreren gaat niet alleen over een betaalknop op je site. Het gaat over hoe betaalgegevens, bankbestanden, statusmeldingen en je boekhouding op elkaar aansluiten. In deze gids lees je hoe je de juiste partner kiest, je SEPA-gegevens voorbereidt, API-calls en webhooks gebruikt en afwijzingen, afletteren en beveiliging regelt.

Waarom handwerk in betalingen misgaat

Kernpunt: één verkeerd geplaatst decimaalteken of een datum als DD/MM/JJJJ in plaats van JJJJ-MM-DD kan een hele salarisrun laten afwijzen. Eén tikfout in een IBAN kost uren uitzoekwerk.

Veel mkb-bedrijven beginnen met een gehoste gateway: de provider regelt de betaalpagina en het grootste deel van de PCI-compliance. Dat is een goede start. Maar betalingen die je zelf doet (leveranciers, salarissen) en incasso’s lopen vaak via je eigen bank, met SEPA-bestanden. Daar zit het handwerk.

De automatische oplossing

Combineer je payment gateway met een vaste manier om SEPA-bestanden te maken. Met GenerateSEPA zet je Excel-, CSV- of JSON-bestanden om naar het SEPA XML-formaat dat banken vragen, met controle van elk IBAN vooraf.

De juiste payment service provider kiezen

Kijk verder dan het transactietarief

• Vaste maandkosten en kosten per transactie.
• Kosten van chargebacks en geschillen bij kaartbetalingen.
• Uitbetalingstermijn: hoe snel staat het geld op je rekening?
• Betaalmethoden: iDEAL voor Nederland, Bancontact voor België, kaarten, SEPA-incasso, en de overgang van iDEAL naar Wero.
• Toezicht: staat de provider onder toezicht van De Nederlandsche Bank of een andere Europese toezichthouder?

Vuistregel: maak een eenvoudige spreadsheet. Reken je verwachte kosten door op je eigen volume en vergeet een schatting voor chargebacks niet.

De developer-ervaring telt

Goede documentatie, een volwaardige sandbox, duidelijke foutcodes en betrouwbare webhooks besparen weken ontwikkeltijd. Stel je voor: je moet elke week 50 SEPA-overboekingen voor salarissen versturen. Een goede API laat je die als één batch aanbieden en geeft per regel een status terug.

SEPA en internationale mogelijkheden

Groei je naar andere landen, kijk dan of de provider meerdere valuta en lokale betaalmethoden ondersteunt. Lees meer in internationale betalingen ontvangen.

Je gegevens voorbereiden voor SEPA-betalingen

De belangrijkste SEPA-gegevens

Gegeven	Waarvoor
IBAN	Rekening van ontvanger of betaler
Naam	Moet overeenkomen met de rekeninghouder (naamcontrole sinds oktober 2025)
Bedrag	Getal met punt als decimaalteken in de XML
Uitvoerings- of incassodatum	Werkdag, binnen de deadline van je bank
Omschrijving of betalingskenmerk	Voor afletteren bij ontvanger en bij jou
Incassant-ID	Alleen bij incasso: identificeert jou als incassant
Machtigingskenmerk en -datum	Alleen bij incasso

Een fout in een van deze velden leidt meestal tot een directe afwijzing. Valideer IBAN’s daarom vóór het bestand wordt gemaakt, met de IBAN-validator.

Kernpunt: de meeste mislukte eerste batches komen door simpele invoerfouten. Automatische IBAN-controle vóór het maken van het bestand haalt ze weg.

Van CSV naar SEPA XML

Je moet je kolommen vertalen naar de juiste XML-velden. Dat kan met een eigen script, maar dat betekent veel testen en debuggen. Met een visuele koppeling leg je het één keer vast. Een uitgebreidere uitleg staat in Excel naar SEPA XML.

Bekende datakopzorgen

• Wisselende datumformaten uit verschillende systemen.
• Bedragen met een komma als decimaalteken.
• Speciale tekens in namen die de bank niet accepteert.
• Oude exportformaten die niet aansluiten op SEPA XML.

Automatiseren met API-calls en webhooks

Een API-call naar de gateway

Meestal stuur je een POST naar een endpoint, met de batch als bijlage of als JSON:

curl -X POST https://api.jouwgateway.example/v1/sepa_batches \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]"

Kernpunt: een geslaagde call geeft meestal 201 of 202 terug, met een uniek batch-ID. Sla dat ID op: je hebt het nodig om de status te volgen en af te letteren.

Webhooks in plaats van pollen

1. Maak een endpoint in je applicatie, bijvoorbeeld https://jouwapp.example/webhooks/betalingen.
2. Registreer het endpoint in het dashboard van de provider.
3. Verwerk de meldingen: je ontvangt JSON bij elke gebeurtenis, zoals transaction.succeeded of batch.processed.

Controleer altijd de handtekening van een webhook voordat je hem verwerkt, en maak de verwerking idempotent: dezelfde melding twee keer mag geen dubbele boeking opleveren.

Moet je de SEPA-bestanden zelf maken voordat ze naar de gateway of bank gaan, dan doe je dat via de SEPA-API. Codevoorbeelden staan in de handleidingen voor Python, PHP en Node.

Fouten, afletteren en beveiliging

Afwijzingen begrijpen en slim opnieuw proberen

Een afwijzing komt met een redencode. Sommige zijn tijdelijk (onvoldoende saldo), andere definitief (rekening opgeheven). Probeer alleen opnieuw bij tijdelijke oorzaken en volg de regels van het schema. Het overzicht van R-berichten helpt bij het indelen. Controleer bestanden vooraf met een SEPA-bestandsvalidatie.

Automatisch afletteren

Geef elke betaling een uniek kenmerk (EndToEndId) dat terugkomt in de webhook of het bankafschrift. Dan kan je systeem:

1. de bijbehorende factuur of klant opzoeken;
2. de factuur op “betaald” zetten;
3. de volgende stap starten, zoals het verzenden van een bestelling.

Beveiliging van je koppeling

Principe van minimale rechten: geef een API-sleutel alleen de rechten die hij nodig heeft. Een sleutel voor het aanbieden van batches hoeft geen terugbetalingen te kunnen doen.

• Gebruik TLS 1.2 of hoger voor alle verkeer.
• Bewaar sleutels in een secrets manager, niet in de code.
• Roteer sleutels regelmatig en direct bij vertrek van een medewerker.
• Log elke call, maar nooit volledige kaart- of rekeninggegevens.

Checklist voor je integratie

Stap	Wat je doet	Wanneer
1	Kosten en betaalmethoden van providers vergelijken	Vooraf
2	Sandbox inrichten met testsleutels	Start ontwikkeling
3	Gegevensvelden koppelen en IBAN’s valideren	Vóór de eerste batch
4	Webhooks met handtekeningcontrole bouwen	Tijdens ontwikkeling
5	Afwijzingen en terugboekingen testen	Vóór livegang
6	Automatisch afletteren op uniek kenmerk	Vóór livegang
7	Sleutels en rechten beperken	Doorlopend

Wil je SEPA-bestanden maken zonder eigen XML-code te schrijven? Test je conversies en API-calls met een proefperiode van GenerateSEPA: 7 dagen gratis.

---

Veelgestelde vragen

Wat is het verschil tussen een payment gateway en een payment service provider?

De payment gateway is de technische verbinding die betaalgegevens veilig van je website of app naar het betaalnetwerk stuurt. Een payment service provider (PSP) levert meestal het hele pakket: gateway, verwerking, uitbetaling en rapportage, onder toezicht van een toezichthouder zoals De Nederlandsche Bank.

Hoe test ik een payment gateway zonder echt geld?

Gebruik de sandbox- of testomgeving van de provider, met testsleutels en testkaarten of test-IBAN's. Test daarin ook afwijzingen, terugboekingen en webhooks. Voor SEPA-bestanden kun je een proefversie van een converter gebruiken om bestanden en API-calls te testen zonder betaling.

Ben ik PCI DSS-compliant als ik een gehoste betaalpagina gebruik?

Een gehoste betaalpagina neemt het grootste deel van de PCI DSS-verplichtingen over, omdat kaartgegevens nooit op je eigen server komen. Je moet meestal wel jaarlijks een zelfbeoordelingsvragenlijst (SAQ) invullen om aan te tonen dat je aan de resterende eisen voldoet.

Kan ik een payment gateway koppelen aan een oud ERP-systeem?

Ja, meestal via een tussenlaag. Die haalt de betaalgegevens uit het ERP, zet ze om naar het formaat dat gateway of bank vraagt, zoals SEPA XML, en schrijft de status terug. Zo hoef je het ERP zelf niet aan te passen.

---

Gerelateerde artikelen