Handleidingen

Betalingen en facturen accepteren

In essentie beginnen betalingen met een openstaand bedrag dat bij een klant moet worden geind. Het is mogelijk om alle betalingslogica onafhankelijk op te bouwen en te onderhouden: mandaten beheren, ze up-to-date houden, tokens opslaan, betaallinks genereren, betaalmethoden bijhouden en beslissen welke opties aan welke klant worden getoond. Dit wordt echter al snel complex en moeilijk schaalbaar.

In plaats daarvan kan deze volledige verantwoordelijkheid worden gedelegeerd aan Twikey door openstaande bedragen in te dienen via het factuurendpoint. Ondanks de naam is het factuurendpoint niet beperkt tot traditionele facturen - het verwerkt elk type betaling: abonnementskosten, eenmalige kosten, boetes, donaties of elk ander openstaand bedrag. Door een betaling in te dienen bij Twikey, zorgt Twikey voor alles wat met betalingsincasso te maken heeft:

• De juiste betaalmethoden aanbieden aan de klant
• Klanten converteren naar automatische betaling wanneer een mandaat mogelijk is
• Mandaten, tokens en betaallinks beheren
• Verschillende betalingsflows afhandelen op basis van de situatie van de klant

Betaalmethoden en PSP-configuratie worden beheerd in het Twikey-dashboard. Bij het aanmaken van een betaling is het niet nodig om te weten of de klant een mandaat/token heeft, welke betaalmethode van toepassing is, of er een mandaat/token ondertekend moet worden. Dit betekent dat een enkele integratie alle betalingsflows afdekt.

Elke betalingsflow begint met een aanroep naar het factuurendpoint: POST /creditor/invoice. Bij grote aantallen kunnen deze zelfs in 1 enkele aanroep worden verstuurd via de batch-insert.

Vanaf dat punt bepaalt Twikey de juiste acties op basis van de klantcontext, beschikbare mandaten/tokens en configuratie. De onderstaande secties beschrijven de mogelijke flows die kunnen volgen, en hoe deze via de betalingsfeed kunnen worden gevolgd en afgehandeld.

Betalingen en facturen voor een klant met een mandaat/token

Wanneer de klant al een actief mandaat/token heeft, is de flow eenvoudig:

Na het aanmaken van de betaling initieert Twikey automatisch een transactie volgens de mandaat-/tokengegevens. Er is geen aanvullende klantinteractie nodig. Er wordt een webhook verstuurd wanneer de betalingsstatus wijzigt, waarna de details kunnen worden opgehaald via de betalingsfeed.

De betaalpagina weerspiegelt deze status ook. Beschikbare betaalmethoden worden verborgen en de klant wordt geinformeerd dat er al een automatische betaling in gang is en dat er geen verdere acties nodig zijn.

Betalingen en facturen voor een klant zonder mandaat/token

Wanneer er geen mandaat/token is om automatisch een transactie te initieren, worden de verschillende ingeschakelde betaalmethoden voor de betaling aan de klant getoond. Afhankelijk van welke betaalmethode wordt gekozen, verschilt de flow aan de kant van Twikey, maar eindigt deze altijd met een betalingsevent in de betalingsfeed. Zodra de klant klaar is, wordt een webhook verstuurd.

Beschikbare betaalmethoden

Idealiter ondertekent de klant een mandaat/token voor toekomstige betalingen. Op deze manier worden betalingen automatisch uitgevoerd, wat het aantal te late betalingen vermindert. Nadat de klant heeft ondertekend, initieert Twikey automatisch de betaling aan de bank-/PSP-zijde.

De afhandeling van eenmalige betalingen is altijd hetzelfde, ongeacht welke PSP is verbonden met Twikey.

Hoewel niet aanbevolen als primaire betaalmethode, kan overschrijvingsinformatie beschikbaar worden gemaakt op de betaalpagina. Merk op dat een succesvolle match alleen optreedt als de betalingsreferentie en het bedrag correct door de klant worden opgegeven.

Betalingsfeed

Zodra een betaling is aangemaakt, wordt Twikey de enige bron van waarheid voor alles wat met die betaling gebeurt.

In plaats van individuele betalingen te bevragen, dient de betalingsfeed te worden geconsumeerd. Deze feed is eventgebaseerd en vertegenwoordigt een chronologische stroom van events die beschrijven wat er met alle betalingen is gebeurd sinds de laatste lezing. Dit omvat alle stappen: als een betaling via domiciliering is geind maar sindsdien is teruggedraaid, zijn zowel het payment- als het payment_failure-event aanwezig in de feed.

Niet alleen zijn alle betalingsevents beschikbaar, maar er kan ook meer gedetailleerde informatie worden geextraheerd indien nodig voor de integratie:

• Welke bank of PSP (gateway) is gebruikt voor de betaling
• Welk mandaat/token is gebruikt
• Een uniforme foutcode
• De exacte codes ontvangen van de gateway
• De volgende automatische opvolgstap die Twikey zal uitvoeren
• Waar in het automatische opvolgproces de betaling zich bevindt

Bulkbetalingen en facturen

In plaats van betalingen een voor een aan te maken, kunnen meerdere betalingen in bulk worden ingediend. Bulkbetalingen maken het mogelijk om meerdere openstaande bedragen in een enkele API-aanroep in te dienen, in plaats van een verzoek per betaling. Dit is vooral nuttig voor batchgebaseerde facturering of periodieke exports. Na indiening bij POST /creditor/invoice/bulk verwerkt Twikey de batch asynchroon. Elke betaling wordt individueel behandeld en volgt dezelfde betalingslogica en validatieflow als een regulier betalingsverzoek.

Factuurdocumenten hosten Bij het indienen van betalingen in bulk is het niet nodig om factuur-PDF's te uploaden.

In plaats daarvan kan het factuurdocument extern worden gehost, waarbij alleen de document-URL wordt opgenomen in de bulkpayload. Tijdens de bulktaak haalt Twikey het document automatisch op en slaat het op, zodat de volledige PDF niet in de API-aanroep hoeft te worden verzonden. Het gekopieerde document wordt vervolgens consistent gebruikt in alle communicatie- en betalingsflows die betrekking hebben op de betaling.

Een bulktaak volgen

Zodra de verwerking is voltooid, stuurt Twikey een webhook die aangeeft dat de batch-import is afgerond. Op dat moment kan de definitieve status van de bulktaak worden opgehaald via het bulkstatusendpoint. Hiermee kan worden geverifieerd:

• Of alle betalingen succesvol zijn geimporteerd
• Wanneer het hosten van factuur-PDF's online kan worden gestopt

Acties op een betaling of factuur

Zodra een betaling is aangemaakt, zijn er aanvullende acties die kunnen worden getriggerd. Deze acties vallen in twee duidelijke categorieen: communicatie en betalingsacties. Al deze acties gebruiken dezelfde endpointstructuur: POST /creditor/invoice/{{id}}/{{action}}

Communicatieacties

Communicatieacties worden gebruikt om de klant opnieuw te benaderen en terug te leiden naar betaling.

Afhankelijk van de situatie zijn de opties:

• Een herinnering sturen per e-mail of SMS
• Een fysieke brief versturen via een van de postpartners
• De factuur opnieuw versturen via Peppol

Ongeacht het kanaal linkt elke communicatie altijd terug naar de oorspronkelijke betaalpagina van de factuur. Dit garandeert dat:

• De klant altijd de huidige status van de factuur ziet
• Dubbele betalingen worden vermeden
• De beschikbaarheid van betaalmethoden consistent blijft
• Er geen nieuwe betalingsverzoeken of links hoeven te worden gegenereerd

Betalingsacties Betalingsacties worden doorgaans gebruikt nadat de initiele incassopoging, opvolging en gerelateerde communicatie niet tot een succesvolle betaling hebben geleid. Ze maken interventie op een bestaande betaling mogelijk zonder een nieuw betalingsverzoek aan te maken. Er zijn twee mogelijke benaderingen:

Een automatische betaling opnieuw proberen Als de klant al een bestaand mandaat of token heeft, kan Twikey worden geinstrueerd om een nieuwe automatische betaling te proberen met dat mandaat/token.

Een betalingsplan starten Als alternatief kan een betalingsplan worden gestart. Bij het aanmaken van een betalingsplan wordt het volgende verwacht:

• Het aantal termijnen
• Welk mandaat of token wordt gebruikt
• Het initiele bedrag dat wordt geind
• Het bedrag van elke volgende termijn

Twikey zorgt vervolgens voor:

• Het plannen van de termijnen
• Het uitvoeren van elke betaling op het mandaat of token
• Het rapporteren van voortgang en resultaten via de betalingsfeed

Regelitems

Regelitems zijn alleen vereist wanneer Twikey een PDF- of UBL-document moet genereren, bijvoorbeeld voor levering via Peppol. Als documentgeneratie niet nodig is, kan deze sectie worden overgeslagen.

Bij het aanleveren van regelitems moeten deze worden opgenomen als onderdeel van de factuurdata. Twikey past de strikte Peppol-regels toe bij het verwerken van factuurregels. Dit garandeert dat gegenereerde UBL-documenten geldig zijn en succesvol kunnen worden afgeleverd. Deze regels worden ook afgedwongen wanneer facturen niet via Peppol worden verstuurd, wat consistent gedrag garandeert over alle integraties.

Als de UBL-specificatie in de toekomst wijzigt, zorgt Twikey intern voor die updates. Zolang de integratie de hieronder beschreven regelitemregels volgt, zijn er geen wijzigingen nodig. Voor details over btw en afronding kan de supportpagina worden geraadpleegd, die diepgaander uitlegt hoe juridische problemen kunnen worden vermeden.

Creditnota's vs terugbetalingen

Afhankelijk van het doel moet ofwel een creditnota worden aangemaakt, ofwel een terugbetaling op een betaling worden uitgevoerd, of beide, aangezien het uitgeven van een terugbetaling in Twikey anders werkt dan het uitgeven van een creditnota.

Terugbetalingen Terugbetalingen worden gebruikt wanneer geld moet worden terugbetaald aan de klant. Bij het aanmaken van een terugbetaling gebruikt Twikey automatisch de oorspronkelijke betaalmethode en voert waar mogelijk de terugbetaling uit op hetzelfde mandaat, token of PSP dat voor de betaling is gebruikt. Terugbetalingen zijn puur betalingsbewerkingen. Ze genereren geen boekhoudkundige documenten en beinvloeden geen factuurtotalen of -statussen buiten de monetaire omkeering.

Creditnota's Creditnota's worden gebruikt om een factuur te corrigeren of te verminderen, ongeacht of er direct geld terugvloeit. Typische use cases voor creditnota's zijn:

• Een creditnota genereren als PDF of UBL (bijvoorbeeld voor Peppol) en deze naar de klant sturen
• Het bedrag van een onbetaalde factuur verlagen

Het aanmaken van een creditnota gebruikt hetzelfde endpoint en dezelfde parameters als het aanmaken van een factuur. Het enige verschil is dat het bedrag negatief is. Een creditnota kan worden gekoppeld aan een bestaande factuur door relatedInvoiceNumber in de request body op te nemen. Dit betekent dat creditnota's natuurlijk passen in de bestaande factuur- en betalingsflows zonder een aparte integratie te vereisen.

Creditnotagedrag op basis van factuurstatus

Afhankelijk van de status van de gekoppelde factuur gedraagt Twikey zich anders bij het aanmaken van een creditnota.

Geboekte of verlopen facturen

• Het creditnotabedrag wordt afgetrokken van de factuur
• Gedeeltelijke creditnota's verlagen het resterende betaalbare bedrag
• De creditnota zelf wordt onmiddellijk als betaald gemarkeerd
• Elk resterend saldo op de factuur kan nog steeds worden geind
• Als het totaal van alle gekoppelde creditnota's het volledige factuurbedrag bereikt, wordt de factuur als betaald gemarkeerd

Betaalde facturen

• Het creditnotabedrag wordt niet afgetrokken van de factuur
• De creditnota blijft in een geboekte status
• Er wordt geen terugbetaling automatisch getriggerd
• Als er in dit geval geld moet worden terugbetaald, moet een terugbetaling apart worden aangemaakt

Mandaten en tokens

Zoals beschreven in de sectie over betalingen: wanneer een klant een mandaat of token heeft, worden facturen automatisch geind zonder klantinteractie. Klanten kunnen ook mandaten rechtstreeks vanaf de betaalpagina ondertekenen. Het ondertekenen en beheren van mandaten kan echter ook direct worden geimplementeerd, wat meer controle biedt of integratie in bestaande processen mogelijk maakt. Bij het rechtstreeks werken met transacties wordt verwacht dat het mandaat wordt beheerd.

Een mandaat is een machtiging voor domiciliering (SEPA CORE, SEPA B2B of BACS), terwijl een token opgeslagen kaartgegevens vertegenwoordigt voor terugkerende betalingen. Ondanks de juridische en functionele verschillen tussen deze schema's, verenigt Twikey ze: ze worden op dezelfde manier aangemaakt en gebruikt. Betalingsflows, transactieflows en mandaatacties werken identiek ongeacht het onderliggende type, waardoor alle schema's worden gelijkgetrokken en de integratie wordt vereenvoudigd tot een enkele aanpak.

Elk mandaat of token begint met een van twee endpoints: POST /creditor/invite waarbij Twikey de volledige ondertekeningservaring afhandelt, of POST /creditor/sign waarbij het ondertekeningsproces extern wordt gestuurd. Zodra aangemaakt, zijn alle wijzigingen aan mandaten en tokens, inclusief nieuwe handtekeningen, wijzigingen en annuleringen, beschikbaar via de mandaatfeed.

Het /invite- vs /sign-endpoint

Er zijn twee manieren om een mandaat of token aan te maken, elk met een ander niveau van controle over de ondertekeningservaring.

Het invite-endpoint Het POST /creditor/invite-endpoint maakt een voorbereid (niet-ondertekend) mandaat aan en retourneert een onderteken-URL. Wanneer de klant deze URL bezoekt, handelt Twikey de volledige ondertekeningservaring af: het valideren van de klantgegevens, het presenteren van algemene voorwaarden, en het aanbieden van de ondertekenmethoden die op het template zijn geconfigureerd.

Het sign-endpoint Het POST /creditor/sign-endpoint omzeilt alle Twikey-schermen. Dit is bedoeld voor integraties waarbij de ondertekeningservaring volledig is ingebed in de applicatie van de merchant. Aangezien de schermen van Twikey niet worden getoond, wordt de te gebruiken method verwacht samen met methode-specifieke data. Bijvoorbeeld, een natte handtekening vereist het handtekeningbeeld, en voor eMachtiging is het BIC nodig zodat het bankselectiescherm kan worden overgeslagen. De algemene voorwaarden van Twikey dienen ook te worden opgenomen in de eigen voorwaarden van de merchant, aangezien de acceptatieschermen van Twikey niet aan de klant worden getoond. Hierdoor zijn links die gegenereerd worden via het sign-endpoint bedoeld om onmiddellijk te worden gebruikt in plaats van naar de klant te worden verstuurd.

Een bestaand mandaat importeren Het gebruik van het sign-endpoint met method=import is een speciaal geval: het gaat ervan uit dat het mandaat al volledig extern is ondertekend en simpelweg wordt geimporteerd in Twikey. Dit is beschikbaar op elk template, ongeacht de geconfigureerde ondertekenmethoden.

Wanneer welk endpoint gebruiken Het invite-endpoint is de eenvoudigste integratie: Twikey zorgt voor de ondertekenings-UX, validatie en acceptatie van de voorwaarden. Het sign-endpoint biedt volledige vrijheid om de ondertekeningservaring in een eigen flow in te bouwen, maar brengt de verantwoordelijkheid met zich mee voor het afhandelen van methode-specifieke data, het verzamelen van klantgegevens en de acceptatie van de voorwaarden.

Ondertekeningsflows voor klanten

Onafhankelijk van welk endpoint wordt gebruikt, zijn er twee patronen voor hoe de ondertekeningservaring aan de klant wordt aangeboden.

Twikey stuurt de uitnodiging Wanneer Twikey de uitnodiging stuurt, wordt de ondertekeningslink per e-mail direct aan de klant bezorgd. Dit is geschikt voor post-sale conversies naar automatische betalingen of bulkconversiecampagnes. De klant ontvangt de e-mail, klikt op de link en voltooit het ondertekeningsproces.

De klant doorverwijzen In plaats van Twikey de uitnodiging te laten sturen, wordt de onderteken-URL teruggegeven in het API-antwoord en kan deze worden gebruikt om de klant direct door te verwijzen. Dit is ideaal voor ingebouwde onboardingflows in websites of wanneer communicatie via een extern systeem wordt verstuurd.

Ondertekening via eerste betaling

In scenario's zoals checkoutflows, abonnementsactiveringen of elke situatie waarin onboarding en incasso tegelijkertijd plaatsvinden, kan het ondertekenen van een mandaat worden gecombineerd met het innen van een eerste betaling in een enkele stap. Door transactionAmount en transactionMessage op te nemen bij het aanmaken van het mandaat, ondertekent en betaalt de klant in een flow. Aangezien ondertekening via eerste betaling altijd gekoppeld moet zijn aan een daadwerkelijke aankoop, is de geldigheid van de resulterende handtekening aanzienlijk sterker. Dit vereist echter een ondertekenmethode die initiatie via eerste betaling ondersteunt, waarbij een echte betaling wordt gedaan via een PSP (die het IBAN of de kaartgegevens vastlegt) of via betalingsinitiatie (Twikey-pay-by-bank). Aangezien er een betaling bij betrokken is, worden twee webhook-events verstuurd: type=payment voor de transactie en type=contract voor het ondertekende mandaat.

B2B-validatie

B2B SEPA domicilieringsmandaten verschillen van CORE-mandaten doordat ze niet alleen de handtekening van de klant vereisen, maar ook registratie bij de bank van de klant. Hoe dit wordt afgehandeld, hangt af van de bank:

Verbonden banken Voor banken waarmee Twikey een directe verbinding heeft, is het volledige ondertekenings- en registratieproces digitaal en geautomatiseerd. Er zijn geen handmatige stappen nodig. De klant ondertekent het mandaat en de bankregistratie wordt op de achtergrond afgehandeld.

Niet-verbonden banken Voor banken zonder directe verbinding kan de B2B-validatieflow worden geactiveerd. Nadat de klant het mandaat heeft ondertekend, zorgt Twikey voor de registratie bij de bank: herinneringen worden gestuurd als het mandaat nog niet is geactiveerd, en Twikey test periodiek of de registratie is voltooid. Zodra de registratie is bevestigd, wordt het mandaat volledig ondertekend en wordt een AcceptedBank-event verstuurd via webhook. Als de registratie niet wordt bevestigd na de herhaalpogingen, blijft het mandaat niet-ondertekend.

Het B2B-validatiegedrag wordt per profiel geconfigureerd in het Twikey-dashboard.

Mandaatfeed

Zodra mandaten of tokens zijn aangemaakt, wordt Twikey de enige bron van waarheid voor alles wat ermee gebeurt. In plaats van individuele mandaten te bevragen, zijn alle wijzigingen beschikbaar via de mandaatfeed. Deze mandaatfeed is statusgebaseerd: deze retourneert de laatste status van elk mandaat dat is gewijzigd sinds de laatste lezing. Dit omvat nieuw ondertekende mandaten, wijzigingen (zoals adres- of IBAN-wijzigingen) en annuleringen. Voor elke mandaatupdate biedt de feed details zoals ondertekenarinformatie, de gebruikte ondertekenmethode, redenen voor wijzigingen en annuleringsredenen. De feed wordt verwacht te worden geconsumeerd totdat er geen updates meer resteren, om te garanderen dat alle wijzigingen worden verwerkt.

Standaard retourneert de mandaatfeed alle beschikbare attributen. Om het antwoord te beperken tot alleen de benodigde velden, kunnen include-parameters worden gebruikt. Beschikbare opties zijn: mandate, person, signature, plan, tracker, cancelled_mandate, paidamount en payment.

Elke vermelding in de feed correspondeert met een van drie berichttypen:

• Ondertekend mandaat: de berichttekst begint met Mndt, met de volledige mandaatdetails.
• Wijziging: de berichttekst begint met het AmdmntRsn-object met een Rsn-veld dat de reden van de update beschrijft.
• Annulering: het bericht begint met CxlRsn met een Rsn-veld dat de annuleringsreden beschrijft.

De statuskolom in de onderstaande tabel weerspiegelt de werkelijke mandaatstatussen zoals geretourneerd door het mandaatdetailendpoint.

Tussenliggende statussen In tegenstelling tot de betalingsfeed, die eventgebaseerd is en alle tussenliggende events bevat, weerspiegelt de mandaatfeed alleen de huidige status. Als een mandaat meerdere statuswijzigingen heeft doorlopen tussen twee feed-lezingen, wordt alleen de definitieve status geretourneerd. Om alle tussenliggende statussen vast te leggen, kan de webhook (type=contract) worden gebruikt om direct op de hoogte te worden gebracht wanneer er een update plaatsvindt. Door de feed direct na ontvangst van een webhook op te halen, kan elke status worden vastgelegd voordat deze weer wijzigt.

Geretourneerde overeenkomsttypes Standaard retourneert de feed CORE- en B2B-mandaten. Om andere types zoals creditcardtokens op te nemen, kan de X-TYPES-header worden gebruikt om aan te geven welke types moeten worden opgenomen.

Acties op een mandaat

Zodra een mandaat of token is aangemaakt, zijn er aanvullende acties beschikbaar via het POST /creditor/mandate/{mndtId}/action-endpoint. Deze acties vallen in drie categorieen.

Communicatieacties Deze acties worden gebruikt om niet-ondertekende mandaten naar voltooiing te begeleiden.

• method = invite: de ondertekeningsuitnodiging opnieuw per e-mail versturen
• method = reminder: een herinnering sturen naar de klant om het mandaat te ondertekenen

Klant-selfservice Voor ondertekende mandaten kan de klant toegang krijgen om de eigen mandaatgegevens te beheren.

• method = access: biedt een link naar het klantportaal voor het specifieke mandaat. Via het portaal kan de klant het IBAN bijwerken, wijzigbare attributen aanpassen en mandaatgegevens beheren.

B2B-validatie-overrides Voor B2B-mandaten kan het validatiegedrag dat op het profiel is geconfigureerd per mandaat worden overschreven.

• method = automaticCheck: automatische validatie aan zetten voor dit specifieke mandaat, waarmee de profielstandaard wordt overschreven
• method = manualCheck: automatische validatie uit zetten voor dit specifieke mandaat, waarmee de profielstandaard wordt overschreven

Mandaatlevenscyclus

Mandaatgegevens bijwerken Zodra een mandaat is ondertekend, kunnen details zoals adres, IBAN, mobiel nummer, e-mail, bedrijfsnaam, taal en eventuele custom attributen die op het template zijn gedefinieerd, worden bijgewerkt via POST /creditor/mandate/update. Updates aan een mandaat worden weerspiegeld in de mandaatfeed.

Mandaten annuleren Mandaten kunnen worden geannuleerd via DELETE /creditor/mandate. Zelfs wanneer een annulering buiten Twikey wordt ontvangen, is het aan te raden deze terug te communiceren zodat alle systemen gesynchroniseerd blijven.

Automatisch opruimen van niet-ondertekende mandaten Niet-ondertekende mandaten of tokens vervallen automatisch na 12 maanden, of na 6 maanden zodra de ondertekeningslink is geopend. Als een nieuw mandaat op hetzelfde profiel voor dezelfde klant wordt aangemaakt en het nieuwe mandaat wordt ondertekend, worden oudere niet-ondertekende mandaten voor die klant automatisch verwijderd, waardoor de omgeving vrij blijft van achtergebleven niet-ondertekende mandaten en tokens.

Betaallinks

Betaallinks zijn bedoeld voor eenmalige betalingen zonder mandaat of token en kunnen worden aangemaakt via POST /creditor/payment/link. Waar het factuurendpoint werkt als een "verstuur en vergeet"-implementatie die de methodeselectie, opvolging, mandaatconversie en communicatie afhandelt, laten betaallinks die controle over aan de integratie.

Betaallinks verwijzen de klant rechtstreeks door naar de PSP, waarbij de Twikey-betaalpagina volledig wordt omzeild. Als het betaalmethodeselectiescherm aan de PSP-zijde ook overgeslagen moet worden, kan dit door de method-parameter op te nemen in de creatieaanroep. Dit maakt betaallinks de juiste keuze wanneer een eigen checkout, landingspagina of communicatieflow al bestaat en de automatische orchestratie van het factuurendpoint niet nodig is.

Betalingsflows voor klanten

Onafhankelijk van hoe de betaallink is aangemaakt, zijn er twee patronen voor het bezorgen van de betaallink aan de klant.

Twikey stuurt de uitnodiging Wanneer een e-mailadres is opgegeven en sendInvite is ingesteld, levert Twikey de betaallink direct aan de klant. Dit is geschikt voor losstaande betalingsverzoeken waarbij geen extra landingspagina of communicatieflow nodig is.

De klant doorverwijzen In plaats van Twikey de uitnodiging te laten sturen, wordt de betaallink-URL teruggegeven in het API-antwoord en kan deze worden ingebed in eigen flows, communicatie of pagina's. Dit is ideaal voor checkoutflows in websites of wanneer communicatie via een extern systeem wordt afgehandeld.

Een betaallink koppelen aan een bestaande betaling

Een betaallink kan worden gekoppeld aan een of meer bestaande onbetaalde transacties door txref mee te geven bij het aanmaken van de link. Zodra de betaallink is betaald, worden alle gekoppelde transacties ook als betaald gemarkeerd. Dit is nuttig voor het consolideren van meerdere openstaande bedragen in een enkele betalingsactie tijdens een aangepaste opvolging van onbetaalde transacties.

Het is ook mogelijk om een betaallink aan te maken op een bestaande factuur door de invoice-parameter met het factuurnummer op te geven. Hierdoor kan de betaling voor een bestaande factuur direct via de PSP worden geind in plaats van via de door Twikey gehoste betaalpagina die door het factuurendpoint wordt gebruikt.

Betaallinkfeed

De betaallinkfeed werkt op hetzelfde statusgebaseerde model als de mandaatfeed: elke aanroep naar GET /creditor/payment/link/feed retourneert vermeldingen die zijn gewijzigd sinds de laatste ophaling. Elke vermelding vertegenwoordigt de huidige status van een betaallink, niet een individueel event.

Standaard worden alleen betaalde updates geretourneerd. Het meegeven van all=true neemt alle statuswijzigingen op. Extra details kunnen worden opgenomen door include-parameters toe te voegen: customer, meta, time en refunds. Deze worden standaard niet opgenomen om het antwoord compact te houden.

Webhooks voor betaallinks valideren

Voor checkout-integraties is het belangrijk om te verifieren dat een webhook daadwerkelijk afkomstig is van Twikey. Het valideren van de webhook kan worden gedaan door de x-signature-header te valideren. Dit is hetzelfde validatiemechanisme dat voor alle Twikey-webhooks wordt gebruikt. Zie de webhookreferentie voor volledige details.

Een betaallink terugbetalen

Een betaalde betaallink kan volledig of gedeeltelijk worden terugbetaald via POST /creditor/payment/link/{id}/refund. Ondersteuning voor terugbetalingen hangt af van de PSP die is geactiveerd in het Twikey-portaal. De terugbetalingsstatus wordt weerspiegeld in de betaallinkfeed wanneer de juiste include ook is toegevoegd.

Transacties

In tegenstelling tot de betalingsflow waarbij facturen automatisch worden beheerd en geind, werken transacties rechtstreeks op mandaten of tokens. Een transactie wordt altijd aangemaakt op een specifiek mandaat, niet op een klant. Hierdoor wordt het koppelen van transacties aan het juiste mandaat of token afgehandeld door de integratie, niet door Twikey.

Zoals bij mandaten en betaallinks biedt het rechtstreeks werken met transacties meer controle over het incassoproces, maar brengt het ook meer verantwoordelijkheid met zich mee bij het correct beheren van de flow.

Transacties worden aangemaakt via POST /creditor/transaction, met vermelding van de mandaatreferentie, het bedrag en een bericht (dat op het bankafschrift van de klant verschijnt). Twikey verzamelt openstaande transacties in batches en dient ze in bij de bank of PSP voor verwerking. Zodra feedback is ontvangen, wordt een type=payment-webhook verstuurd en kunnen de resultaten worden opgehaald via de transactiefeed. Wanneer een transactie mislukt, start het geconfigureerde aanmaningsproces automatisch.

Transactiefeed

De transactiefeed werkt op hetzelfde statusgebaseerde model als de mandaatfeed: elke aanroep naar GET /creditor/transaction retourneert de huidige status van elke transactie die is gewijzigd sinds de laatste ophaling. Elke aanroep verschuift de positie, dus de feed wordt verwacht te worden geconsumeerd totdat deze leeg is. Om alle tussenliggende statussen vast te leggen, kan de betalings-webhook (type=payment) worden gebruikt om een feed-ophaling te triggeren zodra er een wijziging optreedt.

De final-vlag Elke vermelding bevat ook een final-vlag:

• final=true geeft aan dat er geen automatische acties meer worden uitgevoerd op deze transactie. Dit geldt voor transacties die betaald en afgewikkeld zijn, of waarbij alle automatische opvolgstappen zijn uitgeput nadat de transactie is mislukt.
• final=false geeft aan dat Twikey nog automatische opvolging uitvoert en dat verdere statuswijzigingen worden verwacht.

Opmerking: een PAID + final=true transactie kan nog steeds door de bank worden teruggedraaid op een later moment (bijv. een chargeback of reversal). In de praktijk komt een domicilieringstransactie bijna altijd eerst terug als PAID + final=true, aangezien dit is hoe banken communiceren over domicilieringen: de hele batch wordt als betaald gemarkeerd, en op volgende dagen communiceert de bank over individuele onbetaalde transacties.

Automatische opvolging Wanneer een transactie mislukt, voert Twikey automatische opvolgstappen uit zoals het opnieuw aanbieden van de betaling, het sturen van notificaties naar de klant en het voorstellen van alternatieve betaalmethoden. De feed weerspiegelt het resultaat van deze stappen naarmate ze worden voltooid. Een transactie kan overgaan van ERROR terug naar PAID als een opvolgstap slaagt, of in ERROR blijven met final=true zodra alle stappen zijn uitgeput.

Include-parameters Standaard retourneert de feed een compact antwoord. Extra details kunnen worden opgehaald door include-parameters toe te voegen:

• collection - het collection-batch-ID
• lastupdate - tijdstempel van de meest recente statuswijziging
• action - alle automatische opvolgacties die zijn ondernomen bij een mislukte transactie
• action_payment - zoals action maar bevat alleen de acties die zijn ondernomen sinds de laatste keer dat de feed werd aangeroepen
• link - een betaallink voor de klant
• stage - het huidige stadium van de transactie
• seq - het volgnummer binnen de feed

Bulktransacties

In plaats van transacties een voor een aan te maken, kunnen tot 5.000 transacties in een enkel verzoek worden ingediend via POST /creditor/transaction/bulk. Na indiening verwerkt Twikey de batch asynchroon. Een type=bulk-webhook wordt verstuurd zodra de verwerking is voltooid, en de batchstatus kan worden gecontroleerd met het geretourneerde batch-ID.

Een transactie terugbetalen

Een terugbetaling kan worden geinitieerd op elke betaalde transactie via POST /creditor/transaction/{id}/refund. Hoe de terugbetaling wordt verwerkt, hangt af van hoe de oorspronkelijke transactie is geind.

Voor domicilieringstransacties wordt de terugbetaling toegevoegd aan een credit transfer-bestand. Dit bestand moet worden gedownload, geupload naar de bank en ondertekend voordat de terugbetaling wordt uitgevoerd. Het bedrag wordt standaard terugbetaald naar het IBAN op het oorspronkelijke mandaat.

Voor transacties die via een PSP zijn geind, of het nu gaat om domiciliering via een PSP of terugkerende creditcard, stuurt Twikey de terugbetaling direct door naar de PSP voor verwerking.

Meer handleidingen

De volgende handleidingen worden voorbereid:

• Subscriptions
• Credit transfers
• Reservations
• Customer identification
• IBAN-name checks
• Collections

In de tussentijd behandelt de API-referentie alle beschikbare endpoints.