Recurring CreditCard API
Met de REST API voor Terugkerende CreditCard kunt u makkelijk een automatisch terugkerende betaalmachtiging voor de consument aanmaken.
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 doorgestuurd naar een eerste CreditCard transactie om de machtiging te bevestigen.
- Het afronden van deze eerste CreditCard transactie bevestigt automatisch de Terugkerende Machtiging.
- 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/creditcard/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 CreditCard contract geconfigureerd zijn op dit outlet. |
12345 |
currencyCode |
Valutacode volgens ISO 4217 Standaardwaarde is: EUR The opgegeven valutacode moet ondersteund zijn in uw CreditCard contract. |
EUR |
initialAmount* | Het bedrag van de eerste verificatiebetaling in centen. | 5000 |
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 wordt teruggestuurd nadat diegene de eerste CreditCard transactie heeft uitgevoerd. 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 | Mandate request successfully created |
mandateRequestID | ID van het aangemaakte verzoek |
launchURL | URL om uw consument naartoe te verwijzen |
Voorbeeld rauwe respons
{"status":0,"message":"Mandate request successfully created","mandateRequestID":12345,"launchURL":"http://pay.digiwallet.nl/consumer/creditcard-mandate/launch/50/1d84e48f-9afa-11e8-85c4-b8ca3a793886/0"}
U kunt nu de mandateRequestID
in uw database opslaan en uw consument doorverwijzen naar de launchURL
.
Als er een probleem optreed met de eerste transactie, dan wordt de consument eerst teruggebracht naar het machtigingsoverzicht.
Vanaf hier kan diegene ervoor kiezen om het opnieuw te proberen (het verzoek gaat dan weer naar een Accepted status) of het verzoek te weigeren.
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":{"initialAmount":["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:
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/creditcard/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 | 1 |
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."]}}
Check Methode Controleer machtiging
Om de status van een machtiging te controleren, roep de volgende API aan via HTTP GET
.
https://api.digiwallet.nl/creditcard/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 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 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/creditcard/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 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 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, maakt een CreditCard transactie en voert die direct uit.
De reportURL parameter van het oorspronkelijke machtigingsverzoek wordt ook doorgegeven aan de CreditCard transactie. De parameters voorzien in deze callback zijn hetzelfde als in de reguliere (Eenmalige CreditCard API).
Om een actieve machtiging te facturen, roep de volgende API aan via HTTP POST
.
https://api.digiwallet.nl/creditcard/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 CreditCard transactie, e.g.: 12345 |
transactionStatus |
Status van de aangemaakte CreditCard transactie, 1 van:
|
acquirerResponseCode | Externe status code, e.g. 00 |
acquirerMessage | Textuele representatie van de status code, e.g. "Payment accepted" |
Voorbeeld rauwe respons
{"status":0,"message":"Mandate successfully charged","transactionID":12345,"transactionStatus":"Success","acquirerResponseCode":"00","acquirerMessage":"Payment accepted"}
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."]}}