Payment API integreren: van aanvraag tot bevestigde status

Modelleer opdracht en betaalpoging apart

Een opdracht legt vast wat je verkoopt, terwijl een betaalpoging een eigen technisch verloop heeft. Geef beide een stabiele referentie en bewaar hun relatie. Een onduidelijke opdracht mag niet automatisch tot een extra poging leiden. Leg ook vast welk account, welke winkel en welke omgeving worden gebruikt. Bij meerdere winkels moeten deze keuzes uit betrouwbare gegevens komen. De browser mag niet zelfstandig bepalen welke zakelijke verbinding hoort bij de aanvraag. Een expliciet gegevensmodel maakt deze afspraken zichtbaar voor iedereen die later een transactie moet onderzoeken.

Integratie en API

Volg het voorgeschreven bedragformaat

Iedere API bepaalt hoe een bedrag wordt aangeleverd. Neem die afspraak exact over en gebruik niet automatisch het formaat van een eerder geïntegreerde leverancier. OrsunPay documenteert decimale tekenreeksen voor bedragen. Controleer daarbij de valuta en de definitieve versie van de opdracht. Kortingen en wijzigingen moeten vóór de aanvraag zijn verwerkt. Volg een voorbeeldbedrag van bestelling tot resultaat en laat zien waar validatie plaatsvindt. Een nette checkoutweergave kan een fout in achterliggende conversie niet uitsluiten wanneer verschillende systemen anders met numerieke waarden omgaan.

Gehoste betaalpagina

Bereid een verloren antwoord voor

Een aanvraag kan zijn verwerkt terwijl het antwoord de aanvrager niet bereikt. Dan weet de toepassing nog niet of een betaling bestaat. Blind opnieuw aanmaken kan een dubbel proces opleveren. Gebruik de gedocumenteerde idempotentiestrategie en houd bij welke zakelijke aanvraag bij welke sleutel hoort. Maak onderscheid tussen dezelfde aanvraag herhalen en bewust een nieuwe betaalpoging starten. Deze keuze moet niet door iedere aanroepende toepassing afzonderlijk worden bedacht. Een gedeelde regel voorkomt dat een netwerkvertraging op verschillende plaatsen tegenstrijdige herstelacties veroorzaakt.

Controleer de afzender van gebeurtenissen

Een openbare webhook mag een bestelling niet wijzigen enkel omdat een bericht er geldig uitziet. Controleer de voorgeschreven ondertekening voordat je de inhoud verwerkt. OrsunPay gebruikt een gedocumenteerde HMAC-SHA256-controle over de oorspronkelijke bytes van de berichtinhoud. Opnieuw opbouwen of formatteren vóór die controle kan de uitkomst veranderen. Houd geheime sleutels uit browsercode en beperk vertrouwelijke gegevens in logs. Stripe en Mollie benadrukken in hun documentatie eveneens het belang van servergebeurtenissen voor een betrouwbare verwerking van het betaalresultaat.

Voer een zakelijke actie slechts eenmaal uit

Na de technische controle moet je toepassing bepalen welke statusovergang is toegestaan. Dezelfde bevestiging mag niet twee verzendingen of activeringen veroorzaken. Bewaar de verwerking zo dat een herhaald bericht herkenbaar blijft zonder dezelfde actie nogmaals uit te voeren. Neem ook late meldingen mee. De terugkeerpagina kan de klant informeren, maar is zelf geen betaalbewijs. Laat de beslissing over uitvoering voortkomen uit een geverifieerd serverresultaat en de regels van de opdracht. Daardoor blijft het proces correct als de klant helemaal niet terugkeert.

Ontwerp de overdracht naar support mee

Support heeft een zoekbare referentie en een begrijpelijke reden voor openstaande gevallen nodig. Beschrijf wanneer een interne verwerking mag worden herhaald en wanneer de PSP moet worden betrokken. OrsunPay verbindt jouw eigen accounts, maar vervangt geen accountvoorwaarden of acceptatiebeslissingen. Bevestig ook de publicatie van benodigde SDKs of pakketten voordat je daarop plant; code in een repository bewijst geen beschikbaar publiek pakket. Een overdracht is pas bruikbaar als een andere medewerker een voorbeeldincident met de beschikbare gegevens kan onderzoeken en aan de klant kan uitleggen.

• Simuleer een verloren antwoord na het aanmaken.
• Controleer ongeldige ondertekeningen en dubbele gebeurtenissen.
• Volg bedrag, valuta en winkelcontext door het proces.
• Leg de procedure bij onbekende uitkomsten vast.
• Laat support met dezelfde zakelijke referenties werken.

Bronnen

• Stripe-documentatie over webhooks
• Mollie-documentatie over betalingen