Betaling in verzoek

Auteur: Joeri Diederen Haagsma | Joeri Bekker Status: Definitief

Het doel van de interactie

Het registeren van een online betaling die plaatsvindt in de aanvraagfase van de klantreis.

Use cases

• Betaling is verplicht voor het indienen van een aanvraag

  • Verzoek wordt opgeslagen na validatie van de betaalprovider

• Betaling is optioneel voor het indienen van een aanvraag

  • Buiten scope, vereist ZAC dat een update op een object kan verwerken

Het architectuuroverzicht

Component	Functie
Optioneel: Authenticatiecomponent	De eindgebruiker valideren
Inputcomponent, zoals Open Formulieren	Het verzoek registreren
Internetkassa, zoals Ingenico	Online betalingen verwerken
Objecten- en Objecttypen API	Het publiceren, valideren en opslaan van verzoekenHet opstellen van een notificatie voor de Notificaties API
Zaaktypecatalogus API	Voor het ophalen van documenttypen
Documenten API	Het opslaan van bijlagen
Notificaties API	Voor het routeren van notificaties naar afnemers
Zaakafhandelcomponent	Het ontvangen van een notificatie, het ophalen en of kopiëren van formulierdata, het starten van een proces en het aanmaken van een zaak
Optioneel: Financieel systeem	Het boekhoudkundig verwerken van de betaling

Het interactiepatroon

sequenceDiagram
title: Betaling tijdens aanvraag
actor klant AS Klant

participant formulier AS Aanvraagcomponent

participant betaalprovider AS Betaalprovider

participant objectenapi AS Objectregistratie

participant ON AS Notificatie component

klant->> formulier: Aanvraag

formulier ->> betaalprovider: Transactie

alt Directe feedback van Betaalprovider
    betaalprovider ->> formulier: Feedback
    formulier ->> objectenapi: POST Verzoek met betaaldetails

else Geen directe feedback van Betaalprovider
    formulier ->> objectenapi: POST Verzoek (zonder betaaldetails)
    betaalprovider ->> formulier: Feedback
    formulier ->> objectenapi: PATCH Verzoek met betaaldetails
end

objectenapi ->> ON: POST notificatie

Autorisaties

Naar betaalprovider

Bij het integreren met een internetkassa wordt er gebruik gemaakt van een PSPID (Payment Service Provider Identifier). Hiervoor moet de beheerder een handler aanmaken in de beheerinterface van het aanvraagcomponent. De configuratie omvat onder andere het instellen van de SHA-512 hash-algoritme en het definiëren van de feedback-URL in de internetkassa-backoffice.

Naar objecten API

De registrator wordt vooraf met een API-sleutel geautoriseerd om objecten van dat objecttype aan te maken.

De gegevensstructuur

Het aanvraagcomponent slaat betaalgegevens op in het Verzoekobject. Deze betaalgegevens moeten in de internetkassa worden geselecteerd, zodat ze teruggkoppeld worden aan de callback url van het aanvraagcomponent.

Gegevensstructuur

Het verzoekobject bestaat uit verschillende gegevensgroepen. Deze gegevens worden gevalideerd door een JSON-schema.

Een voorbeeldschema van een verzoek richting het zaaksysteem eSuite vind je hier:

De verschillende gegevensgroepen zijn;

Generieke verzoekgegevens

De structuur van deze gegevens is altijd hetzelfde. Denk aan gegevensgroepen zoals de Bron van een verzoek, de Locatie, Betrokkenen, Betaling, of gegevens die een afhandelcomponent nodig heeft om een proces te starten. etc.

• Deze gegevens zijn idealiter standaard aanwezig, want ze garanderen dat verplichte velden aanwezig zijn. Als dat niet zo is, kan de eSuite wellicht geen zaak starten op basis van een formulier.

Specifieke verzoekgegevens

Dit zijn gegevens die nodig zijn voor het behandelen een specifiek Verzoek. Deze gegevens zijn afhankelijk van het gekozen product en vormen het contract tussen aanvraag- en behandeling. Afstemming tussen de registrator en verwerker is noodzakelijk als deze structuur van deze gegeven wijzigt. Deze gegevens verschillen per verzoektype, mogelijk per gemeente.

• Dit gedeelte bevat gegevens die noodzakelijk zijn voor geautomatiseerde verwerking.

Overige gegevens

Dit zijn verzoekgegevens die niet gestructureerd hoeven te worden, en als label:value pair in het Verzoekobject worden opgeslagen. Denk aan vraag-antwoordcombinaties om tot een Specifiek Verzoekgegeven te komen. Voorbeeld: inkomsten per categorie vragen (overig), om tot een totaalbedrag te komen (specifiek).

• Deze gegevens worden in het object geplaatst als additionalproperties

Best practices

Financiële verwerking van de transactie

De transactie moet boekhoudkundig op de juiste plek in de organisatie verwerkt worden. De complexiteit hiervan hangt van van de grootte van de organisatie.

ZAC relateert betaling met grootboek

In Rotterdam zorgt het zaakafhandelcomponent met een aanvullend bericht richting een journaalpostadapter voor de relatie tussen de betaling en de organisatorische afdeling die hoort bij de zaak die eruit volgt.

Meerdere rekeningnummers

In Den Haag is er een rekeningnummer per directie, waardoor routering bij voorbaat richting de juiste administratie plaatsvindt. Geaccepteerd wordt dat individuele betalingen niet herleidbaar zijn naar zaken. Wel wordt een uniek formulierID meegegeven aan de betaalprovider, waardoor de betaling achteraf te linken is aan de klant.

Vergezicht

Het aanvraagcomponent kan in de PDC zoeken naar het product om leges op te halen. Idealiter volgt ook een primaire afdeling, waardoor de relatie met de afdeling in het aanvraagcomponent al te maken is. Gewenst is om een specifiek kenmerk mee te geven aan de betaalprovider, zodat dit ook verwerkt kan worden in de transactiekenmerken die ook de klant leest op zijn of haar rekening.