E-Mandates API

Met de REST API voor E-Mandates kunt u heel makkelijk wettelijk bindende en automatisch terugkerende incasso machtigingen maken voor consumenten.

De terugkerende machtiging flow in het kort:

  1. Maak een nieuwe machtiging en stuur de consument er naar toe.. (Aanmaak Methode)
  2. De consument leest de machtiging door en accepteert deze.
  3. De consument wordt naar u teruggestuurd en u kunt de afronding van de Terugkerende Machtiging controleren. (Check Methode)
  4. Opvolgende terugkerende betalingen worden automatisch door DigiWallet uitgevoerd middels een schema dat u kiest. Of, in geval van een doorlopende machtiging, controleert u wanneer de machtiging gefactureerd moet worden via de (Charge Methode)
  5. U kunt de machtiging op elk gegeven moment stopzetten. (Stop Methode)

Standaard staat Incasso niet aan voor uw account.
Voor meer informatie en voorwaarden neem contact op met sales@targetmedia.eu.

HTTP Bearer Authenticatie

Deze API vereist HTTP Bearer authenticatie. (Lees meer...) Dit betekent dat uw verzoeken aan deze API een extra HTTP header met uw organisatie's API sleutel nodig hebben om geaccepteerd te worden.

U kunt uw organisatie's API sleutel vinden in uw Organisatie Dashboard.

Een voorbeeld van de HTTP header is als volgt:

Authorization: Bearer 12a34bc5de67f8g9012345678

RESTful API

Dit is een RESTful API. Dit betekent dat de API het RESTful formaat voor webservices volgt (Lees meer...)

Het respons formaat van deze API's is in (JSON). Een typische respons is een JSON-geëncodeerde array met een status integer om aan te geven of de aanroep gelukt is of niet, en een message string met een beschrijving van wat er is gebeurd.

Naast deze standaard elementen kan een API natuurlijk API-specifieke informatie teruggeven. e.g. transactionID integer voor het maken van een transactie. Of een nested errors array waarin gedetailleerde validatiefouten staan.

De HTTP response codes van de RESTful API's volgen de onderstaande logica:

HTTP Status Code Gebruikt in reactie op
200 (Success) Een succesvol verwerkt verzoek dat ook informatie teruggeeft
201 (Created) Een succesvol verwerkt aanmaak verzoek
202 (Accepted) Een succesvol geaccepteerd job verzoek
400 (Bad Request) Foutieve input parameters / validatiefouten
401 (Unauthorized) Foutieve inloggegevens
404 (Not Found) Object kon niet gevonden worden
405 (Method Not Allowed) Methode is niet ondersteund in deze API
500 (Internal Server Error) Er is een probleem opgetereden in DigiWallet's servers

Aanmaak Methode Maak nieuw machtigingsverzoek

Om een nieuw machtigingsverzoek te maken, roep de onderstaande API aan middels HTTP POST.

https://api.digiwallet.nl/emandates/mandate-request

Met de volgende parameters (* = verplicht):

Variabele Toelichting Voorbeeld
outletID* Het ID van de outlet waarop u de machtiging wilt registreren.
Er moet een Incasso contract zijn geconfigureerd op dit outlet.
12345
recurAmount* Het bedrag van de opvolgende automatische terugkerende betalingen in centen.
Moet leeg worden gelaten als de recurFrequency op "manual" is ingesteld.
5000
recurPayments De hoeveelheid opvolgende automatisch terugkerende betalingen die DigiWallet moet uitvoeren voordat de Terugkerende Machtiging automatisch word stopgezet.
Dit veld leeglaten betekent dat de Terugkerende Machtiging geen specifieke levensduur heeft en blijft lopen totdat hij op een andere manier stop word gezet.
5
recurFrequency* De frequentie waarop de opvolgende automatisch terugkerende betalingen moeten worden uitgevoerd.
Dit betekent dat er één betaling wordt uitgevoerd per (deze instelling).
De beschikbare opties zijn:

  • year: Jaarlijks
  • month: Maandelijks
  • week: Wekelijks
  • day: Dagelijks
  • manual: Doorlopend*

* Een machtiging met een doorlopende frequency wordt niet automatisch gefactureerd door DigiWallet. In plaats daarvan kan het handmatig gefactureerd worden door een separate API aanroep, kijk voor meer informatie naar het hoofdstuk (Charge Methode)
month
recurFrequencyUnit* Het moment waarop de opvolgende automatisch terugkerende betalingen moeten worden uitgevoerd.
Dit is gerelateerd aan de recurFrequency.
Moet leeg worden gelaten als de recurFrequency op "manual" of "day" is ingesteld.
Voor meer gedetailleerde informatie, lees het hoofdstuk over (Terugkeer-Frequentie)
25
recurDelay* De gratis periode tussen de eerste transactie en de opvolgende automatisch terugkerende betalingen.
Dit is gerelateerd aan de recurFrequency.
Bijvoorbeeld, wanneer de recurFrequency staat op month dit voegt een 1 maand vertraging toe voor de eerste terugkerende betaling.
Dit veld op 0 zetten betekent dat er geen gratis periode wordt gehandhaafd.
Gebruik dit wanneer de consument zich te dichtbij uw standaard facturatie dag abonneert, of wanneer u een promotie wilt doen.
1
description* Beschrijving voor op de consument's bankafschrift. Abonnement op Mijn Tijdschrift
returnURL* De locatie waar uw consument naartoe terug wordt gestuurd na het bevestigen van de E-Mandate.
Een GET parameter zal worden toegevoegd aan deze verwijzing: mandateRequestID
Voorbeeld: https://www.myshop.nl/thankYouPage?mandateRequestID=30626804185492
https://www.myshop.nl/thankYouPage
cancelURL De locatie waar uw consument naartoe wordt teruggestuurd wanneer diegene de machtiging weigert.
Een GET parameter zal worden toegevoegd aan deze verwijzing: mandateRequestID
Voorbeeld: https://www.myshop.nl/cancelPage?mandateRequestID=30626804185492
Als u dit veld leeg laat zal de returnURL hiervoor in de plaats worden gebruikt.
https://www.myshop.nl/cancelPage
reportURL Het server script dat aangeroepen wordt wanneer de status van het machtigingsverzoek wijzigt of wanneer betalingen onder de machtiging worden uitgevoerd.
Dit verzoek wordt uitgevoerd via HTTP POST.
Gebruik verzoeken aan dit script als een hint om de relevante Check Methode aan te roepen.
De parameters voorzien wanneer een machtigingsverzoek van status verandert zijn:

  • eventType: De reden waarom deze aanroep wordt uitgevoerd, de opties zijn:
    • mandateRequestCreated Het verzoek is aangemaakt
    • mandateRequestAccepted De consument heeft het verzoek geaccepteerd en gaat de E-Mandate bevestigen bij de bank
    • mandateRequestDeclined De consument heeft het verzoek geweigerd
    • mandateRequestFailed Het bevestigingsproces van de E-Mandate is mislukt bij de bank
    • mandateRequestPending De consument heeft de E-Mandate bevestigd bij de bank, maar afronding is uitgesteld omdat het een zakelijke bankrekening betreft. Zie: (Meervoudige Ondertekening)
    • mandateRequestFinalized Het verzoek is afgerond en er is een actieve machtiging gemaakt
    • mandateRequestExpired Het verzoek is verlopen na een periode van inactiviteit
  • mandateRequestID: Het ID van het machtigingsverzoek waar deze aanroep over gaat.
  • eventDateTime: De datum en tijd waarop dit gebeurd is, formaat: YYYY-MM-DD HH:MM:SS.

De parameters voorzien in het verozek wanneer een machtiging wordt aangemaakt (dit gebeurt wanneer het verzoek afgerond word) of stopgezet:

  • eventType: De reden waarom deze aanroep wordt uitgevoerd, de opties zijn:
    • mandateCreated Het verzoek is afgerond en de machtiging is aangemaakt
    • mandateTerminated De machtiging is stopgezet
  • mandateID: Het ID van de machtiging waar dit verzoek over gaat.
  • mandateRequestID: Het ID van het oorspronkelijke machtigingsverzoek waar dit verzoek over gaat.
  • eventDateTime: De datum en tijd waarop dit gebeurd is, formaat: YYYY-MM-DD HH:MM:SS.
De parameters voorzien bij de automatische terugkerende betalingen zijn hetzelfde als in de reguliere (Eenmalige Incasso API).

Gebruik alstublieft de relevante Check Methode, beiden voor het machtigingsverzoek alswel de opvolgende betalingen, om de authenticiteit van de reportURL callback te bevestigen.
https://www.myshop.nl/reportMandate
consumerIP* IP adres van de consument. 213.76.8.33
consumerEmail E-Mail adres van de consument
Wanneer voorzien, zal worden gebruikt om bevestigingen naar de consument te sturen over het accepteren van de machtiging en het uitvoeren van terugkerende betalingen.
test@example.com
test Of u de test-modus wilt gebruiken of niet.
Bij het gebruiken van de testverbinding wordt er geen echt geld afgeschreven.
Merk op dat als uw outlet in test-modus is gezet via het DigiWallet Dashboard, deze parameter automatisch op 1 komt te staan.

Vergeet deze optie niet uit te zetten als de site live gaat. Standaard staat testmode uit.
"1" of "0"

U krijgt dan een JSON-geëncodeerde array terug met de volgende inhoud:

Key Waarde
status 0
message E-Mandate request successfully created
message Mandate request successfully created
mandateRequestID ID van het aangemaakte verzoek
launchURL URL om uw consument naartoe te verwijzen

Voorbeeld rauwe respons

{"status":0,"message":"E-Mandate request successfully created","mandateRequestID":12345,"launchURL":"http://pay.digiwallet.nl/consumer/directdebit-mandate/launch-emandate/50/1d84e48f-9afa-11e8-85c4-b8ca3a793886/0"}

U kunt nu de mandateRequestID in uw database opslaan en uw consument doorverwijzen naar de launchURL.

In het geval van één of meer fouten krijgt u een JSON-geëncodeerde array respons met de volgende inhoud:

Key Waarde
status 1
message Validation failed
errors Nested JSON-geëncodeerde array met validatiefouten

Voorbeeld

Key Waarde
recurAmount Amount too low, the minimum is set to: 49 - 25 given.
description Description cannot be blank.

Voorbeeld rauwe respons

{"status":1,"message":"Validation failed","errors":{"recurAmount":["Amount too low, the minimum is set to: 49 - 25 given."],"description":["Description cannot be blank."]}}

Controleer in geval van fouten of de parameters goed zijn overgenomen uit de documentatie. Als dit het geval lijkt te zijn, neem dan contact op met DigiWallet. Vermeldt de aanroep en de foutmelding.

Terugkeer-Frequentie Betaalschema

Omdat DigiWallet de terugkerende betalingen automatisch voor u uitvoert leggen we hier uit hoe dat precies werkt.

Over de recurFrequencyUnit parameter:

  • Wanneer recurFrequency is ingesteld op year: dan is de recurFrequencyUnit parameter de dag van het jaar (1-365). ***
  • Wanneer recurFrequency is ingesteld op month: dan is de recurFrequencyUnit parameter de dag van de maand (1-31). *
  • Wanneer recurFrequency is ingesteld op week: dan is de recurFrequencyUnit parameter de dag van de week (1-7). **
  • Wanneer recurFrequency is ingesteld op day: dan is de recurFrequencyUnit parameter leeg, want deze is dan niet nodig.
  • Wanneer recurFrequency is ingesteld op manual: dan is de recurFrequencyUnit parameter leeg, want deze is dan niet nodig.
* Als voor een maandfrequentie u een dag opgeeft die voor die maand niet bestaat dan wordt uw betaling uitgevoerd op de laatste dag van die maand. Ze spoelen dus niet over in de volgende maand.

Enige opvolgende betalingen daarna worden weer normaal uitgevoerd.

** Voor een weekfrequentie kunt u de dag van de week opgeven. Zie hieronder de numerieke invoer voor specifieke dagen van de week:

*** Merk op dat omdat er een wettelijke verwerkingswachttijd bestaat van twee werkdagen voor SEPA Incasso, we de incasso twee werkdagen voor uw gekozen verwerkingsdatum bij de bank aanleveren. Vertragingen in de verwerking bij de bank alswel speciale feestdagen kunnen ervoor zorgen dat de transactie iets eerder of later afgeschreven wordt, houd dus rekening in uw schema met enige flexibiliteit.

recurFrequencyUnit Weekdag
1 Zondag
2 Maandag
3 Dinsdag
4 Woensdag
5 Donderdag
6 Vrijdag
7 Zaterdag
**** U heeft gelijk dat een schrikkeljaar-verschuiving in de jaarfrequentie niet ondersteund is. Zoekt u toevallig een baan?

Check Methode Controleer machtigingsverzoek

Om de status van een machtigingsverzoek te controleren, roep de volgende API aan via HTTP GET.

https://api.digiwallet.nl/emandates/mandate-request/<outletID>/<mandateRequestID>[/<test>]

De query string parameters kunt u invullen als volgt (* = vereist):

Variabele Toelichting Voorbeeld
outletID* Het ID van de outlet waarop het machtigingsverzoek was geregistreerd. 39995534
mandateRequestID* Het ID van het oorspronkelijke machtigingsverzoek. 12345678
test Als u de transactie in test-modus hebt gestart, roep de Check API dan ook aan in test-modus. Als u dit niet doet zal uw transactie niet gevonden worden.

Merk op dat als uw outlet in test-modus is gezet via het DigiWallet Dashboard, deze parameter automatisch op 1 komt te staan.

Vergeet deze optie niet uit te zetten als de site live gaat. Standaard staat testmode uit.
1

U krijgt dan een JSON-geëncodeerde array terug met de volgende inhoud:

Key Waarde
status 0
message Mandate request successfully checked
mandateRequestStatus Huidige status van het machtigingsverzoek, opties zijn als volgt:
mandateID Dit veld is alleen aanwezig wanneer de mandateRequestStatus ingesteld is op Finalized
Bijvoorbeeld: 54321

Voorbeeld rauwe respons

{"status":0,"message":"Mandate request successfully checked","mandateRequestStatus":"Finalized","mandateID":54321}


In het geval van één of meer fouten krijgt u een JSON-geëncodeerde array respons met de volgende inhoud:

Key Waarde
status 1
message Validation failed
errors Nested JSON-geëncodeerde array met validatiefouten

Voorbeeld

Key Waarde
mandateRequestID There is no mandate request for this ID.

Voorbeeld rauwe respons

{"status":1,"message":"Validation failed","errors":{"mandateRequestID":["There is no mandate request for this ID."]}}

Controleer in geval van fouten of de parameters goed zijn overgenomen uit de documentatie. Als dit het geval lijkt te zijn, neem dan contact op met DigiWallet. Vermeldt de aanroep en de foutmelding.

Meervoudige Ondertekening Zakelijke bankrekeningen

Zakelijke bankrekeningen zijn onderhevig aan een meervoudig ondertekeningsproces. Dit betekent dat nadat de consumer de E-Mandate geaccepteerd heeft, zij hem nog een keer separaat moet bevestigen door in te loggen op diens online bankieromgeving.

De Pending status komt alleen terug in deze specifieke casus. De E-Mandate blijft in deze status tot de consument het meervoudige ondertekeningsproces heeft afgerond. DigiWallet controleert periodiek of deze status al bijgewerkt is en stuurt automatisch een reportURL callback uit wanneer de E-Mandate is bevestigd.

Als de E-Mandate in een Pending staat blijft voor meer dan 7 dagen verloopt hij automatisch naar een Expired staat.

Check Methode Controleer machtiging

Om de status van een machtiging te controleren, roep de volgende API aan via HTTP GET.

https://api.digiwallet.nl/emandates/mandate/<outletID>/<mandateID>[/<test>]

De query string parameters kunt u invullen als volgt (* = vereist):

Variabele Toelichting Voorbeeld
outletID* Het ID van de outlet waarop het oorspronkelijke machtigingsverzoek was geregistreerd. 39995534
mandateID* Het ID van de machtiging die is ontstaan uit een machtigingsverzoek. 12345678
test Als u de machtiging in test-modus heeft gestart, roep de Check API dan ook in test-modus aan. Anders zal uw machtiging niet worden gevonden.

Merk op dat als uw outlet in test-modus is gezet via het DigiWallet Dashboard, deze parameter automatisch op 1 komt te staan.

Vergeet deze optie niet uit te zetten als de site live gaat. Standaard staat testmode uit.
1

U krijgt dan een JSON-geëncodeerde array terug met de volgende inhoud:

Key Waarde
status 0
message Mandate successfully checked
mandateStatus Huidige status van de machtiging, opties zijn als volgt:
  • Active
  • Terminated

Voorbeeld rauwe respons

{"status":0,"message":"Mandate successfully checked","mandateStatus":"Active"}


In het geval van één of meer fouten krijgt u een JSON-geëncodeerde array respons met de volgende inhoud:

Key Waarde
status 1
message Validation failed
errors Nested JSON-geëncodeerde array met validatiefouten

Voorbeeld

Key Waarde
mandateID There is no mandate for this ID.

Voorbeeld rauwe respons

{"status":1,"message":"Validation failed","errors":{"mandateID":["There is no mandate for this ID."]}}

Controleer in geval van fouten of de parameters goed zijn overgenomen uit de documentatie. Als dit het geval lijkt te zijn, neem dan contact op met DigiWallet. Vermeldt de aanroep en de foutmelding.

Stop Methode Stop actieve machtiging

Om een actieve machtiging stop te zetten, roep de volgende API aan via HTTP DELETE.

https://api.digiwallet.nl/emandates/mandate/<outletID>/<mandateID>[/<test>]

De query string parameters kunt u invullen als volgt (* = vereist):

Variabele Toelichting Voorbeeld
outletID* Het ID van de outlet waarop het oorspronkelijke machtigingsverzoek was geregistreerd. 39995534
mandateID* Het ID van de machtiging die is ontstaan uit een machtigingsverzoek. 12345678
test Als u de machtiging in test-modus heeft gestart, roep de Terminate API dan ook in test-modus aan. Anders zal uw machtiging niet worden gevonden.

Merk op dat als uw outlet in test-modus is gezet via het DigiWallet Dashboard, deze parameter automatisch op 1 komt te staan.

Vergeet deze optie niet uit te zetten als de site live gaat. Standaard staat testmode uit.
1

U krijgt dan een JSON-geëncodeerde array terug met de volgende inhoud:

Key Waarde
status 0
message Mandate successfully terminated
mandateStatus Nieuwe status van de machtiging, opties zijn als volgt:
  • Terminated

Voorbeeld rauwe respons

{"status":0,"message":"Mandate successfully terminated","mandateStatus":"Terminated"}


In het geval van één of meer fouten krijgt u een JSON-geëncodeerde array respons met de volgende inhoud:

Key Waarde
status 1
message Validation failed
errors Nested JSON-geëncodeerde array met validatiefouten

Voorbeeld

Key Waarde
mandateID There is no mandate for this ID.

Voorbeeld rauwe respons

{"status":1,"message":"Validation failed","errors":{"mandateID":["There is no mandate for this ID."]}}

Controleer in geval van fouten of de parameters goed zijn overgenomen uit de documentatie. Als dit het geval lijkt te zijn, neem dan contact op met DigiWallet. Vermeldt de aanroep en de foutmelding.

Charge Methode Factureer een doorlopende machtiging

Alleen handmatige frequency machtigingen kunnen worden gefactureerd via de Charge Method. Een afschrijving uitvoeren neemt de informatie uit de machtiging en maakt een DirectDebit transactie.

De reportURL parameter van het oorspronkelijke machtigingsverzoek wordt ook doorgegeven aan de DirectDebit transactie. De parameters voorzien in deze callback zijn hetzelfde als in de reguliere (Eenmalige Incasso API).

Merk op dat vanwege de aard van SEPA DirectDebit transacties de standaard verwerkingstijd van 2 werkdagen van toepassing is.

Om een actieve machtiging te facturen, roep de volgende API aan via HTTP POST.

https://api.digiwallet.nl/emandates/mandate/charge

Met de volgende parameters (* = verplicht):

Variabele Toelichting Voorbeeld
outletID* Het ID van de outlet waarop het oorspronkelijke machtigingsverzoek was geregistreerd. 39995534
mandateID* Het ID van de machtiging die is ontstaan uit een machtigingsverzoek. 12345678
chargeAmount* Het bedrag in centen om af te schrijven. 500
test Als u de machtiging in test-modus heeft gestart, roep de Charge API dan ook in test-modus aan. Anders zal uw machtiging niet worden gevonden.

Merk op dat als uw outlet in test-modus is gezet via het DigiWallet Dashboard, deze parameter automatisch op 1 komt te staan.

Vergeet deze optie niet uit te zetten als de site live gaat. Standaard staat testmode uit.
1

U krijgt dan een JSON-geëncodeerde array terug met de volgende inhoud:

Key Waarde
status 0
message Mandate successfully charged
transactionID ID van de aangemaakte DirectDebit transactie, e.g.: 12345
transactionStatus Status van de aangemaakte DirectDebit transactie, is altijd:
  • Open

Voorbeeld rauwe respons

{"status":0,"message":"Mandate successfully charged","transactionID":12345,"transactionStatus":"Open"}


In het geval van één of meer fouten krijgt u een JSON-geëncodeerde array respons met de volgende inhoud:

Key Waarde
status 1
message Validation failed
errors Nested JSON-geëncodeerde array met validatiefouten

Voorbeeld

Key Waarde
mandateID There is no mandate for this ID.

Voorbeeld rauwe respons

{"status":1,"message":"Validation failed","errors":{"mandateID":["There is no mandate for this ID."]}}

Controleer in geval van fouten of de parameters goed zijn overgenomen uit de documentatie. Als dit het geval lijkt te zijn, neem dan contact op met DigiWallet. Vermeldt de aanroep en de foutmelding.