Wat is een API voor dubbel boekhouden voor marktplaatsen?
Een API voor dubbel boekhouden legt geldstromen op een marktplaats vast als sluitende, onveranderbare journaalposten, zodat u altijd precies weet wie waar recht op heeft en waarom.
Een marktplaats kan er in de orders-tabel financieel gezond uitzien en het toch bij het verkeerde eind hebben wat betreft de liquiditeit. De bestelling staat op "betaald". Het dashboard van de verkoper toont een saldo. Niets in die tabel bewijst echter hoeveel kasgeld het platform in bezit heeft, hoeveel het aan elke verkoper verschuldigd is, welk deel van de betaling commissie-inkomsten zijn, of hoeveel btw er inmiddels betaald moet worden. Een API voor dubbel boekhouden (double-entry ledger API) is er om deze financiële consequenties correct vast te leggen, transactie voor sluitende transactie.
Eenvoudig gezegd: een API voor dubbel boekhouden is een programmeerbaar boekhoudsysteem. Uw applicatie stuurt een financiële gebeurtenis, zoals een ontvangen betaling of een goedgekeurde uitbetaling, naar de API en het grootboek legt deze gebeurtenis vast als een journaalpost met gelijke debet- en creditbedragen op de betreffende grootboekrekeningen. Het verplaatst zelf geen geld. Het legt de waarheid vast over geld dat elders is bewogen.
Wat "dubbel boekhouden" hier betekent
Een grootboek is het overzicht van wijzigingen op rekeningen, geen tabel die enkel het meest actuele saldo toont. Een goed werkend grootboek rust op drie samenhangende concepten:
- Rekening (account): een benoemde financiële post, zoals te vorderen van betalingsverwerker, te betalen aan verkoper, commissie-inkomsten of te betalen btw.
- Transactie (journaalpost): één atomaire financiële gebeurtenis die meerdere in balans zijnde regels bevat.
- Boeking (entry): een enkele debet- of creditregel binnen die transactie.
De fundamentele regel die elk ontwerp bijeenhoudt is simpel: het totale debet is gelijk aan het totale credit, voor elke transactie en in elke valuta. Grootboek-API's weigeren doorgaans een uitkomst die niet in evenwicht is voordat deze wordt opgeslagen. De documentatie van Modern Treasury definieert een grootboektransactie als een gebeurtenis met twee of meer rekeningen met ten minste één debet- en één creditpost van gelijke totalen, en behandelt een geboekte transactie als onveranderbaar (immutable).
Dubbel boekhouden betekent niet dat er exact twee regels zijn. Een en dezelfde marktplaatsverkoop vereist vaak één debetpost en meerdere creditposten. Dat is precies het punt dat mensen het vaakst verkeerd interpreteren.
Waarom marktplaatsen een grootboek nodig hebben en geen simpele betalingstabel
Een marktplaats onderhoudt tegelijkertijd verschillende financiële relaties. Een koper betaalt. Een betalingsverwerker verrekent de gelden. Het platform beheert de fondsen mogelijk tijdelijk. De verkoper verdient een deel. Het platform houdt een commissie in. Er ontstaat belastingplicht. Mogelijk wordt er een reservering aangehouden. Later verplaatst een uitbetaling het geld, en maken terugboekingen (refunds) of storings (chargebacks) delen hiervan ongedaan.
Een payments-tabel kan u de commerciële status van een bestelling vertellen. Deze kan u echter niet betrouwbaar vertellen:
- hoeveel vordering of kasgeld er bij de betalingsverwerker staat
- hoeveel er aan elke verkoper verschuldigd is
- welke omzet toebehoort aan het platform
- hoeveel btw er verschuldigd is en in welk land
- wat er is gereserveerd voor terugbetalingen of geschillen
- of een uitbetaling de juiste schuld aan de verkoper heeft verlaagd
- of de afdrachten van de betalingsverwerker overeenkomen met wat het platform verwachtte
Nordlets gids over API's voor dubbel boekhouden voor marktplaatsboekhouding trekt een duidelijke grens: applicatietabellen beschrijven de status van het product, terwijl het grootboek de financiële gevolgen van die status vastlegt. Ook wordt een herhaling waard punt gemaakt: rapporten van betalingsverwerkers zijn invoer voor de afstemming (reconciliation), en vormen geen volledige dubbele boekhouding.
Een voorbeeld van een marktplaatsverkoop
Stel dat een koper € 100 betaalt, de verkoper recht heeft op € 85 en de commissie van het platform € 15 bedraagt. Laten we btw en verwerkingskosten voor de duidelijke leesbaarheid buiten beschouwing laten.
| Rekening | Debet | Credit | Reden |
|---|---|---|---|
| Te vorderen van betalingsverwerker | € 100 | Verwerker is de geïnde betaling verschuldigd aan het platform | |
| Te betalen aan verkoper | € 85 | Platform is geld verschuldigd aan de verkoper | |
| Commissie-inkomsten | € 15 | Platform heeft commissie verdiend | |
| Totaal | € 100 | € 100 | In balans |
De belangrijke classificatie hier is dat de € 85 die aan de verkoper verschuldigd is een schuld (liability) vormt, en geen omzet van het platform. Volgens het IFRS-raamwerk is een schuld een actuele verplichting om een economische hulpbron over te dragen. Een marktplaats dient de volledige verkoopopbrengst van de verkoper niet als eigen inkomen te rapporteren enkel omdat de koper via het platform heeft betaald. Uw rol als tussenpersoon (agent), principaal of geacht leverancier verandert de behandeling, maar het mechanisme van het grootboek blijft hetzelfde.
Wanneer de verkoper in aanmerking komt voor uitbetaling, wordt er geen nieuwe omzet geboekt. U lost de schuld in:
| Rekening | Debet | Credit |
|---|---|---|
| Te betalen aan verkoper | € 85 | |
| Bank of uitbetalingsclearing | € 85 | |
| Totaal | € 85 | € 85 |
Als de betalingsverwerker vóór de uitbetaling een vergoeding van € 3 inhoudt, verandert de kasstroom in een journaalpost van drie regels: € 97 naar bankkas, € 3 naar verwerkingskosten, en € 100 van te vorderen van betalingsverwerker. Elke wijziging in positie heeft een bron en een bestemming.
Hoe de API werkt, stap voor stap
1. Uw applicatie detecteert een zakelijke gebeurtenis. Een betaling wordt geïnd, een bestelling wordt geleverd, een uitbetaling wordt goedgekeurd, een terugbetaling wordt gedaan, een chargeback wordt gestart of een settlement wordt ontvangen. Uw database beheert nog steeds de operationele status. Het grootboek legt het monetaire effect vast.
2. U stuurt een gestructureerd verzoek. Dit bevat doorgaans het gebeurtenistype, bedrag en valuta, bestellings- of betalings-ID, kopers- en verkopersidentificaties, commissie, belastinggegevens, de betrokken rekeningen, ingangs- en boekingsdata, een idempotency-sleutel en metagegevens die terugverwijzen naar verwerker- en productrecords. Het openbare API-voorbeeld van Nordlet toont een conceptueel verkoopverzoek met een verkoper-ID, verkooptype, bedrag, valuta, plus btw-land en -tarief.
3. De API valideert. Deze controleert of debet en credit in balans zijn, de rekeningen bestaan en boekbaar zijn, de valuta wordt ondersteund, het bedrag correct met kleine eenheden (minor-unit handling) wordt verwerkt, de idempotency-sleutel niet opnieuw wordt gebruikt voor een ander resultaat, de periode open staat en de vereiste metagegevens aanwezig zijn. Een mislukte controle laat geen gedeeltelijke journaalpost achter.
4. Het boekt atomair. De volledige transactie wordt als één geheel weggeschreven. Het mag nooit zo zijn dat de debetpost wel wordt geregistreerd terwijl de bijbehorende creditpost mislukt. Voor een marktplaats kan een gedeeltelijke splitsing leiden tot een schijnbaar verkopersaldo zonder bijbehorend kasgeld, of tot het boeken van commissie zonder de verplichting aan de verkoper.
5. Saldi en rapporten worden afgeleid uit het grootboek. Na de boeking kunt u de rekeningbalansen, openstaande en beschikbare verkopersaldi, de proefbalans (trial balance), de grootboekmutaties, btw-overzichten en de historie per een datum in het verleden inlezen. Het verkopersaldo moet herberekend kunnen worden vanuit de boekingen, en mag niet blind worden vertrouwd vanuit een muteerbaar veld.
6. Webhooks informeren uw product. Gebeurtenissen zoals sale_invoice.paid, een geboekt journaal, een beschikbare uitbetaling of een afstemmingsverschil worden naar u verzonden. Verwerk deze idempotent. Een webhook is een melding, geen toestemming om de financiële gebeurtenis een tweede keer toe te passen. De API-conventies behandelen scopes, idempotency-sleutels, foutstructuren en het ondertekenen van webhooks in detail.
Verkopersaldi zijn geen enkel getal
De meeste marktplaatsen komen in de problemen doordat ze een verkopersaldo als één enkel getal behandelen. Geld hoort in verschillende statussen te staan:
| Status | Betekenis |
|---|---|
| In afwachting (Pending) | Verkoper heeft mogelijk recht op het geld, maar aan vrijgavevoorwaarden is nog niet voldaan |
| Beschikbaar (Available) | Komt in aanmerking voor uitbetaling |
| Gereserveerd (Reserved) | Achtergehouden tegen terugbetalingen, retouren of geschillen |
| Uitbetaald (Paid out) | Verplichting voldaan via een overboeking |
| Negatief | Terugbetalingen, chargebacks of kosten overtreffen de beschikbare middelen |
Modellen van betalingsverwerkers weerspiegelen dit. Het model met afzonderlijke afboekingen en overboekingen van Stripe stelt een platform in staat om de eigen rekening te belasten, en vervolgens delen over te maken naar gekoppelde rekeningen, waarbij kosten, terugbetalingen en chargebacks op het saldo van het platform landen. Het marktplaatsmodel van Adyen onderscheidt gebruikersaldi-rekeningen, die fondsen aanhouden tot de uitbetaling, van een aansprakelijkheidssaldo-rekening die negatieve saldi van terugbetalingen of chargebacks kan opvangen. Dit zijn nuttige inputgegevens voor uw grootboek, maar ze vormen niet uw volledige boekhoudmodel.
Uitbetalingen en verkopersverdiensten vinden op verschillende momenten plaats
Een verkoper kan op maandag verdienen en de volgende maandag uitbetaald krijgen. Tussen die momenten in wordt een bestelling vervuld, wordt een reserve aangehouden, wordt een uitbetalingsbatch samengesteld, rekent een betalingsverwerker af onder aftrek van kosten en arriveert er een bankstorting. Een grootboek moet elk stadium apart bewaren in plaats van de bestelling te overschrijven met een definitieve status van "betaald". Hierdoor kunt u tijdsverschillen verklaren tussen bestelactiviteit, aanspraak van de verkoper, afrekening, start van de uitbetaling en bankontvangst.
Terugboekingen en chargebacks: terugdraaien, niet overschrijven
Terugboekingen (refunds) en chargebacks zijn nieuwe gebeurtenissen die zijn gekoppeld aan de oorspronkelijke betaling. In een onveranderbaar grootboek corrigeert u met een tegenboeking (reversing entry) gevolgd door een gecorrigeerde boeking, zodat het origineel zichtbaar blijft voor controle. Modern Treasury behandelt geboekte transacties als onveranderbaar en ondersteunt idempotency-sleutels om dubbele objecten bij een hernieuwde poging te voorkomen.
Een terugbetaling verlaagt doorgaans het kasgeld of de vordering op de koper, draait de schuld aan de verkoper terug, kan afhankelijk van het beleid een deel van de commissie terugdraaien, past de belasting aan en kan een teruggavenreserve verbruiken. Een chargeback verlaagt het kasgeld of de vordering op de betalingsverwerker, kan een bedrag heropenen dat door de verkoper of het platform verschuldigd is, legt geschilkosten en verwerkingskosten vast, en verplaatst fondsen via een reserveringsrekening.
Afstemming (reconciliation): het grootboek verbinden met echt geld
Een grootboek kan intern in balans zijn en het toch mishebben over de buitenwereld. Bij afstemming worden interne administraties vergeleken met extern bewijs: afrekenrapporten van betalingsverwerkers, bankafschriften, uitbetalingsbestanden en dossiers over terugbetalingen en geschillen.
Een werkbare cyclus ziet er als volgt uit:
- Importeer de settlement- of bankbatch.
- Match elke regel met een bestelling, betaling, terugbetaling, vergoeding, uitbetaling of geschil.
- Vergelijk het verwachte brutobedrag, de inhoudingen, reserves en nettobedragen.
- Boek bevestigde bewegingen naar het grootboek.
- Stuur niet-gematchte items naar een speciale tussenrekening (suspense account).
- Onderzoek uitzonderingen.
- Sluit de periode af.
Het materiaal van Nordlet over afstemming beschrijft precies dit: het importeren van settlement-batches, het matchen van betalings- en terugboekingsregels, en het doorsturen van niet-gematchte ontvangsten naar een tussenrekening in plaats van te gissen naar een factuur. Twee controles zijn van belang en geen van beide vervangt de andere: dubbele boekhouding vraagt of elk journaal in balans is, en afstemming vraagt of het overeenkomt met de betalingsverwerker, de bank en de zakelijke gebeurtenis.
Ontwerpdetails die bepalen of u dit goed aanpakt
Idempotency. Koppel de sleutel aan een stabiele gebeurtenis, zoals payment_captured:pi_123. Een nieuwe poging retourneert het oorspronkelijke resultaat in plaats van een tweede journaalpost.
Atomaire werking (atomicity). Alle regels van één gebeurtenis worden samen geboekt, of geen enkele.
Onveranderbaarheid (immutability) en tegenboeking. De geboekte historie is niet te bewerken via gewone updates. Correcties creëren gekoppelde regels die het oorspronkelijke bedrag, de datum, de classificatie, de reden en de auteur behouden.
Nauwkeurig geld. Geen binaire drijvende komma (floating point). Gebruik gehele getallen voor kleine eenheden (minor units) of exacte decimalen, een expliciete valuta en een deterministische afrondingsregel voor splitsingen. Als u € 100 splitst over verkopers en kosten zonder zo'n regel, breekt een zwervende cent uw balans.
Ingangs- versus boekingsdata. Het moment waarop de koper betaalde, de verkoper verdiende, de bank afrekende en de boeking plaatsvond, zijn verschillende data. Door deze door elkaar te halen worden perioderapportages en belastingtijdstippen onbetrouwbaar.
Meerdere valuta's (multi-currency). Debet en credit moeten binnen een valuta in balans zijn. Omzetting vereist een expliciete koersgebeurtenis met rekeningen voor de vergoeding, afronding en eventuele koerswinst of -verlies. Het accepteren van een currency-veld maakt een grootboek nog geen valutamotor.
Wat een grootboek-API niet voor u doet
Het bepaalt niet uw rekeningschema (chart of accounts). U moet nog steeds zelf bepalen of u optreedt als principaal of agent, wanneer commissie is verdiend, welke partij de kosten van de betalingsverwerker draagt, hoe terugbetalingen de commissie beïnvloeden en hoe de btw wordt berekend en gerapporteerd. Nordlets eigen advies is om eerst de geldstromen in kaart te brengen, het rekeningschema op te stellen, dit door een accountant te laten beoordelen en pas daarna één volledige stroom van bestelling tot uitbetaling en afstemming te implementeren voordat u opschaalt.
Het lost belastingvraagstukken niet op. Btw is afhankelijk van de locatie van koper en verkoper, het producttype, de registratiestatus en de regels voor geachte leveranciers; de EU-btwgids zet uiteen wat de engine afleidt en wat deze markeert voor een menselijke medewerker. De btw-dekking van Nordlet is gericht op de EU en EER, en strekt zich dus niet uit tot Amerikaanse omzetbelasting of Latijns-Amerikaanse e-invoicing. Ook lost het geen operationele onduidelijkheden op, zoals de vraag of een retourtermijn is verstreken, of een uitbetaling moet worden geblokkeerd of dat een betaling frauduleus is. Dat zijn uw beslissingen. Het grootboek legt het financiële resultaat daarvan vast.
Waar Nordlet past
Nordlet is een boekhoud-API gebouwd voor platforms en marktplaatsen, met een onveranderbaar dubbel grootboek, uitbetalingen, EU-btw-afhandeling, REST-endpoints, getypte SDK's en webhooks die via één enkele interface bereikbaar zijn. De onderscheidende keuze is ingebedde boekhouding in uw eigen product in plaats van een betalingsomgeving van een derde partij. Ten tijde van dit schrijven bevindt het product zich in vroege toegang met een sandbox voor ontwerppartners, dus beschouw dit als een sterk voorbeeld van de categorie en evalueer de productvolwassenheid, uptime en jurisdictionele dekking voor uw eigen situatie voordat u toezeggingen doet.
Voor marktplaats- en platformontwikkelaars is het nuttige denkmodel de scheiding tussen geldbeweging en financiële waarheid. Uw betalingsverwerker verplaatst het geld. Een API voor dubbel boekhouden legt vast wie wat tegoed heeft, wat u heeft verdiend, welke belasting en reserves u aanhoudt en of de buitenwereld aansluit bij uw boeken.
FAQ
Is een API voor dubbel boekhouden hetzelfde als een betalingsverwerker?
Nee. Een verwerker autoriseert, int, verrekent en betaalt soms fondsen uit. Een grootboek-API legt de boekhoudkundige gevolgen van die gebeurtenissen vast. De meeste marktplaatsen gebruiken beide: een verwerker zoals Stripe of Adyen voor de geldstromen en een grootboek voor de administratie.
Kan ik gewoon het dashboard van mijn betalingsverwerker gebruiken als grootboek?
Dat kunt u proberen, maar dat zal vroeg of tard door de mand vallen bij een audit. De rapportage van een verwerker toont afboekingen, vergoedingen, overboekingen en settlements, maar geeft meestal geen weerergave van uw volledige verplichtingen aan verkopers, belastingschulden, kosten die buiten de verwerker om gaan of boekhoudkundige correcties. Beschouw dit als invoer voor de afstemming.
Betekent een sluitend grootboek dat mijn administratie klopt?
Alleen dat uw boekingen voldoen aan de debet-creditregel. Een perfect sluitende transactie kan nog steeds op de verkeerde rekening, aan de verkeerde verkoper of met de verkeerde btw-behandeling zijn geboekt. Balans is noodzakelijk, maar niet voldoende. Afstemming vangt de rest op.
Als het grootboek onveranderbaar is, hoe corrigeer ik dan fouten?
U boekt een tegenboeking (reversing entry) en vervolgens een gecorrigeerde boeking. Het origineel blijft zichtbaar, en dat is precies de bedoeling. Onveranderbaarheid beschermt de audittrail, het sluit uw fouten niet in.
Maakt een boekhoud-API mij automatisch compliant?
Nee. Het dwingt een boekhoudkundige structuur af en levert bruikbare administratieve overzichten op. Wettelijke compliance is nog steeds afhankelijk van uw rechtsgebied, contractuele rol, fiscale behandeling, betalingsregelgeving, KYC- en AML-processen en rapportageverplichtingen.