Incasso API

Met deze HTTP API kunt u betalingen klaarzetten die geïncasseerd moeten worden via een SEPA incasso. Per betaling roept u de Start API aan met het bedrag dat geïncasseerd moet worden en van welke bankrekening.

U krijgt per incasso verzoek direct een eerste status terug op basis van een aantal controles, zoals op de bankrekening. De openstaande incasso opdrachten worden dagelijks aangeboden bij de bank. Op de opgegeven report URL ontvang je vervolgens updates over de status van de betaling. De akkoord bevestiging komt meestal binnen 7 dagen.


Standaard staat automatische incasso niet aan voor uw account.
Voor meer informatie en voorwaarden neem contact op met sales@targetmedia.eu.
U kunt iDEAL betalingen als machtiging gebruiken in plaats van een geschreven machtiging.
Gebruik hieronder het rekeningnummer en naam van de klant zoals deze door de check API van iDEAL wordt teruggegeven.

Start API Betaling starten


Voor het starten van de betaling roept u de Start API aan. Van de Start API krijgt u de betaallink om uw klant door te verwijzen en het transactienummer (voor in uw database).


Roep de volgende URL aan met GET of POST:

https://transaction.digiwallet.nl/directdebit/start


Met de volgende parameters (* = verplicht):

Variabele Toelichting Voorbeeld
ver* API versie, dit is versie 2 2
rtlo* Shop ID (ook wel subaccount of layoutcode) waarop de betaling geboekt moet worden 93393
country* Landcode volgens ISO 3166-1
Momenteel is incasso alleen in de Benelux te gebruiken, dus de mogelijke opties zijn NL, BE, LU.
NL
amount* Bedrag in eurocenten: Minimaal 100 , Maximaal 100000 1000
description* Omschrijving van de transactie: dit wordt op het bankafschrift van de klant vermeld. Gebruik alleen letters of cijfers, max. 32 tekens Webshop order #1234
reporturl* Report URL: wordt aangeroepen na betaling (van server naar server) door middel van een POST. Controleer hier of de betaling inderdaad is afgerond en verwerk de bestelling verder. Dit script wordt ook aangeroepen als de klant de browser per ongeluk zou sluiten. Als parameters worden meegestuurd:
  • trxid: bestelnummer
  • rtlo: shop ID (layoutcode)
  • status: Status van de betaling:
    • Success   de betaling is aangeboden en ook geaccepteerd door de bank.
    • Chargeback   de betaling is gestorneerd/teruggeboekt door de klant.
    • Rejected   de betaling is geweigerd door de bank.
  • amountpaid: bedrag van de betaling in eurocenten
  • checksum: md5 van trxidrtlostatussalt
    Voorbeeld (salt is e381277):
    $checksum = md5($_POST["trxid"].$_POST["rtlo"].$_POST["status"]."e381277");
Om te zekeren dat de status terugmelding van DigiWallet afkomt, dient u altijd de Check API aan te roepen. De output van de report URL zal niet zichtbaar zijn voor de klant. De klant wordt doorgestuurd naar de return URL.
https://www.myshop.nl /reportOrder
returnurl* Report URL: Als u een e-mailadres opgegeven heeft, zal de return URL gemaild worden na betaling. Met de return URL wordt het transactie nummer als parameter meegestuurd. Parameter: trxid
Voorbeeld: https://www.myshop.nl/thankYouPage?trxid=30626804185492
https://www.myshop.nl /thankYouPage
once Of deze betaling eenmalig is of niet
Dit toont de consument binnen hun online bankieromgeving dat de aankomende incasso eenmalig is en niet zal herhalen.
Merk op dat een eenmalige betaling altijd een unieke mandate moet hebben. Deze parameter is optioneel, de standaardwaarde is: 0
1 of 0
email E-mailadres van de klant. Indien ingevuld sturen we een bevestiging van de betaling per mail. test@example.com
salt* Salt: een willekeurige reeks getallen aan de hand waarvan de checksum berekend wordt die aan de report URL wordt meegegeven. Maximaal 32 tekens. e381277
cbank IBAN van de klant, voor de incasso NL20RABO02873663091
cname Naam van de klant. Maxmimumlengte is 35 karakters. K Raaijmakers
customer_invoice Soms vermelden klanten per ongeluk uw factuurnummer in plaats van het verplichte, gegenereerde transactienummer.
Als we het originele factuurnummer weten, dan helpt dit ons bij het uitzoeken.
3011001
mandate* Uniek identificatienummer voor de machtiging. Bijvoorbeeld het klantnummer van degene die u wilt incasseren 29991
mandatestart* De datum waarop de consument de incasso overeenkomst is aangegaan (JJJJ-MM-DD). Gebruik datum 2009-11-01 voor overeenkomsten die voor 1 februari 2014 zijn aangegaan 2018-12-19
duedate Datum waarop de incasso moet plaatsvinden (JJJJ-MM-DD). U kunt een datum in de toekomst aangeven als u de betaling in de toekomst wil laten incasseren. Tot die tijd zal de transactie op status 'Open' blijven staan.
Als het veld opengelaten wordt zal de datum van vandaag aangehouden worden. Als de verwerkingsdatum in het weekend of op een feestdag valt, zal de eerstvolgende werkdag de incasso aan de bank doorgegeven worden.
2019-01-02
securitylevel* Hiermee kunt u aangeven hoe streng de aangeboden incasso's gecontroleerd moeten worden om te voorkomen dat betalingen dubbel klaargezet kunnen worden. We adviseren het niveau zo hoog mogelijk in te stellen.

Voorbeeld 1: als u incasso gebruikt voor het 1x per maand afrekenen van abonnementsgeld, kies dan niveau 5 (zeer streng), omdat een rekeningnummer niet meerdere keren per dag voor kan komen.

Voorbeeld 2: u verkoopt producten waarbij het wel denkbaar is dat op eenzelfde rekeningnummer meerdere betalingen tegelijk op een dag open kunnen staan. Kies dan een lager niveau.

Een betaling mag niet geaccepteerd worden door DigiWallet, indien ...
  • 5: ... er de laatste week al een incasso gedaan is op dit bankrekeningnummer (= zeer streng)
  • 4: ... er nog een betaling met dit bankrekeningnummer openstaat
  • 3: ... er nog een betaling van dit bankrekeningnummer openstaat, met hetzelfde bedrag
  • 2: ... er nog een betaling van dit bankrekeningnummer openstaat, met hetzelfde bedrag en dezelfde omschrijving
  • 1: De betaling wordt altijd geaccepteerd
5
userip IP adres van de klant: is niet verplicht, maar is handig bij het vinden van problemen. 213.76.8.33
test Test Modus: vul hier 1 in voor de test modus. Alle input validatie wordt uitgevoerd, en bij correcte invoer krijgt u altijd '12345678' terug als het transactie ID.
Vergeet deze optie niet uit te zetten als de site live gaat. Standaard staat testmode uit.
1


U krijgt vervolgens een resultaat in de volgende vorm:

resultaatcode   OK | transactienummer

Voorbeeld

000000 OK|651691489


Mogelijke resultaatcodes:

Resultaatcode Omschrijving
000000 Betaling is klaargezet
DW_SE_0001 No layoutcode Geen layoutcode meegegeven
DW_SE_0002 Amount too low Bedrag is te laag
DW_SE_0003 Amount too high Bedrag is te hoog
DW_SE_0004 No or invalid return URL Geen of ongeldige return URL meegegeven
DW_SE_0006 No or invalid description Geen omschrijving meegegeven
DW_SE_0007 Your service to this payment method is (temporarily) blocked by the administrator Account geblokkeerd wegens vermeend misbruik
DW_SE_0008 Your approval for this payment method is still in progress Het account is nog niet goedgekeurd voor Incasso. Vul de gegevens van uw account aan
DW_SE_0026 No or invalid userip Geen of een ongeldig user IP adres gegeven
DW_SE_0036 No or invalid salt Geen of een ongeldige salt gegeven
DW_SE_0037 Salt too long Gegeven salt is te lang
DW_SE_0042 No or invalid reporturl Geen of een ongeldige reporturl gegeven
DW_SE_0043 No or invalid securitylevel Geen of een ongeldige securitylevel gegeven
DW_SE_0044 No or invalid cname Geen of een ongeldige cname gegeven
DW_SE_0045 No or invalid IBAN Geen of een ongeldige cbank gegeven
DW_SE_0046 No or invalid mandate Geen of een ongeldige mandate gegeven
DW_SE_0047 No or invalid mandatestart Geen of een ongeldige mandatestart gegeven
DW_SE_0048 Mandate longer than 27 characters Mandate is te lang, er is maar beperkt ruimte op een bankafschrift
DW_SE_0049 Consumer charged back multiple transactions in the last year Consument is geblokkeerd door DigiWallet omdat ze een te hoog storno-risico vertegenwoordigen
DW_SE_0050 Securitylevel: same IBAN, amount and description still pending De securitylevel controle faalde omdat er een andere betaling nog in de wacht staat
DW_SE_0051 Securitylevel: same IBAN and amount still pending De securitylevel controle faalde omdat er een andere betaling nog in de wacht staat
DW_SE_0052 Securitylevel: same IBAN still pending De securitylevel controle faalde omdat er een andere betaling nog in de wacht staat
DW_SE_0053 Securitylevel: same IBAN already billed in past week De securitylevel controle faalde omdat er een andere betaling nog in de wacht staat
DW_SE_0054 DirectDebit only allowed after iDEAL payment Een goedkeuring via iDEAL betaling ontbreekt voor de gegeven IBAN
DW_SE_0055 Duplicate mandate found for one-off, mandate must be unique Voor eenmalige betalingen moet de mandate een unieke reeks zijn voor elke betaling
DW_XE_0001 Layoutcode expected, customer number given Een shop ID (layoutcode) was verwacht terwijl een klantnummer gegeven is
DW_XE_0002 Bank account fails IBAN validation Het gegeven IBAN is structureel fout

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.

Check API Status van een betaling opvragen


Aan de hand van het transactienummer kunt u controleren of de betaling daadwerkelijk is gedaan. Na de betaling wordt de report URL onder water aangeroepen door de DigiWallet server. Hierbij wordt ook de betaalstatus vermeld, maar we adviseren om veiligheidsredenen altijd zelf de status nog op te vragen bij DigiWallet.

Roep de volgende URL aan met een GET of POST:

https://transaction.digiwallet.nl/directdebit/check

Met de volgende parameters (* = verplicht):

Variabele Toelichting Voorbeeld
rtlo* Shop ID (layoutcode) 93393
trxid* transactienummer 30626804185492
test Testmode: vul 1 in voor de testmode. Ook de afgebroken betalingen worden goedgekeurd. Vergeet deze optie niet uit te zetten als de site live gaat. Standaard staat testmode uit. 1
once* Als u 1 invult, dan zal slechts eenmaal een OK status teruggegeven worden. Als de bovenstaande URL nog een keer wordt aangeroepen voor dezelfde transactie, dan volgt een melding DW_SE_0028 Transaction already checked. Als u voor once '0' invult, dan zal steeds een 000000 OK status terug blijven komen. 0


U ontvangt als antwoord:

Resultaatcode Omschrijving
000001 Open De betaling is nog niet aangeboden bij de bank
000002 Processing De betaling is aangeboden bij de bank, maar nog niet verwerkt
000003 Chargeback Het geld is gestorneerd door de consument
000004 Rejected De incasso is geweigerd bij de bank
DW_IE_0001 Unknown internal error Onbekende interne foutmelding. Mail naar techsupport@targetmedia.eu voor ondersteuning
DW_SE_0028 Transaction already checked at datetime Reeds ingewisseld
DW_SE_0001 No layoutcode Geen layoutcode opgegeven
DW_SE_0018 No valid identifiers Geen transactie-id opgegeven
DW_SE_0016 Transaction not found Geen transactie met dit ID gevonden
DW_SE_0019 Layoutcode does not match transaction Layoutcode hoort niet bij deze transactie
DW_SE_0041 Incorrect checksum De gegeven checksum komt niet overeen, bekijk de documentatie voor de juiste structuur