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:
- Maak een nieuwe machtiging en stuur de consument er naar toe.. (Aanmaak Methode)
- De consument leest de machtiging door en accepteert deze.
- De consument wordt naar u teruggestuurd en u kunt de afronding van de Terugkerende Machtiging controleren. (Check Methode)
- 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)
- U kunt de machtiging op elk gegeven moment stopzetten. (Stop Methode)
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:
* 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:
De parameters voorzien in het verozek wanneer een machtiging wordt aangemaakt (dit gebeurt wanneer het verzoek afgerond word) of stopgezet:
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
|
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."]}}
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.
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 |
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
|
Voorbeeld rauwe respons
{"status":1,"message":"Validation failed","errors":{"mandateRequestID":["There is no mandate request for this ID."]}}
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:
|
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
|
Voorbeeld rauwe respons
{"status":1,"message":"Validation failed","errors":{"mandateID":["There is no mandate for this ID."]}}
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:
|
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
|
Voorbeeld rauwe respons
{"status":1,"message":"Validation failed","errors":{"mandateID":["There is no mandate for this ID."]}}
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:
|
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
|
Voorbeeld rauwe respons
{"status":1,"message":"Validation failed","errors":{"mandateID":["There is no mandate for this ID."]}}