Documentatie: Automatische incasso
   Niet ingelogd, klik hier
Aanmelden TargetPay home TargetPay SEPA ready
Home iDEAL Bancontact SOFORT Banking Mobile Billing 0900 nummer Premium SMS Paysafecard



SEPA-incasso
Documentatie





Documentatie: Automatische incasso

1. Algemeen
In dit document staat beschreven hoe u kunt incasseren bij uw klanten via TargetPay. U roept hiervoor een API aan met het IBAN bankrekeningnummer en het bedrag dat ingehouden moet worden.

De uitstaande incasso-opdrachten worden de eerste werkdag na het indienen om 08:00 uur naar de bank gestuurd. Tot die tijd blijft de status op 'Open' staan. De verwerking bij de bank duurt 2-3 werkdagen. In die periode is de status 'Processing'. Na verwerking krijgen wij de eindstatus van de bank, waarna u via de opgegeven report URL een statusupdate ontvangt.

2. Incasso opdracht klaarzetten
2.1 Aanroep


U vraagt een incasso aan met een HTTP GET of POST naar:

https://www.targetpay.com/directdebit/start

Met de volgende parameters:

Variabele Naam Formaat Verplicht
rtloLayoutcodeNumeriekJa
descriptionOmschrijvingAlfanumeriekJa
useripIP adres of uniek ID van uw klantAlfanumeriekJa
amountBedrag in eurocentenAlfanumeriekJa
countryLandcode consumentAlfanumeriekJa
mandateUnieke nummer van de SEPA machtigingAlfanumeriekJa
mandatestartStartdatum van de SEPA machtigingNumeriekJa
cbankIBAN bankrekeningnummer consumentAlfanumeriekJa
cnameNaam consumentAlfanumeriekJa
saltEen willekeurige reeks karakters voor berekenen van checksum van de reporturl (zie: reporturl). Maximaal 32 tekens.AlfanumeriekJa
reporturlRapporteer naar URLAlfanumeriekJa
emailE-mailadres van uw klantAlfanumeriekNee
returnurlReturn URLAlfanumeriekJa
duedateDatum van de incassoYYYY-MM-DDNee
securitylevelBeveiliging voor dubbele betalingenNumeriekJa
oneoffEenmalige incasso0 of 1Nee
testTest modus0 of 1Nee

Toelichting per variabele:
  • rtlo
    De layoutcode waarop de betaling geboekt moet worden. Zie subaccounts.

  • description
    Duidelijke omschrijving van de te leveren dienst. Alleen letters of cijfers, maximaal 32 tekens.

  • userip
    Vermeld het IP adres of een ander uniek ID van de klant. Bijv. een klantnummer.

  • amount
    Het in rekening te brengen bedrag in eurocenten. Mogelijke waarden: minimaal 84, maximaal 100000 ( 0,84 - 1.000,00)

  • country
    Landcode van de consument in ISO 3166-1 formaat. Aangezien automatische incasso vooralsnog alleen in Nederland beschikbaar is, kunt u hier nu alleen NL invullen. Het veld is wel verplicht i.v.m. toekomstige uitbreiding over meerdere landen.

  • mandate
    Uniek identificatienummer voor de machtiging.

  • mandatestart
    De datum waarop de consument de incasso overeenkomst met u is aangegaan.
    Gebruik datum 2009-11-01 voor overeenkomsten die voor 1 februari 2014 zjin aangegaan

  • cbank
    Bankrekeningnummer (IBAN) van de consument.

  • cname
    De naam van uw klant, exact overgenomen van de bankpas.

  • reporturl
    Deze URL roepen we op uw server aan zodra de status van de betaling wijzigt (vanaf onze server). Aan uw URL voegen we 4 parameters toe:
    • trxid: het betaalkenmerk
    • rtlo: layoutcode
    • status: de status van de betaling. Mogelijke waarden zijn:
      - 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.
    • checksum: controlegetal waarmee u kunt controleren of de terugmelding van ons systeem afkomstig is. Checksum wordt als volgt berekend, het is de MD5 van (achter elkaar gezet): trxid, rtlo, status en salt (zie hierboven). Voorbeeld: stel dat u voor 'salt' doorgaf 'e381277' dan kunt u in PHP de juiste checksum uitrekenen met:

      $checksum = md5($_POST["trxid"].$_POST["rtlo"].$_POST["status"]."e381277");

  • email
    Vul hier het e-mailadres van uw klant in als dit bekend is en als u wilt dat wij uw klant een mail sturen zodra de betaling binnen is gekomen. Wij verwijzen uw klant in dat geval naar de opgegeven return URL, mits die vermeld is.

  • returnurl
    Als u een e-mailadres opgegeven heeft zal de return URL gemaild worden na betaling. Achter de return URL plakken wij als parameter trxid met daarin het betaalkenmerk zodat u weet om welke betaling het gaat.

  • duedate
    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. Vult u de datum in in de vorm YYYY-MM-DD. 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.

  • securitylevel
    Hiermee kunt u aangeven hoe streng de aangeboden incasso's door TargetPay gecontroleerd moeten worden om te voorkomen dat betalingen dubbel klaargezet kunnen worden. U doet er verstandig aan dit zo hoog mogelijk in te stellen. Bijvoorbeeld: als u incasso gebruikt voor het 1x per maand afrekenen van abonnementsgeld dan zet u het niveau op 5 (zeer streng), omdat een rekeningnummer niet meerdere keren per dag voor mag komen.
    Verkoopt u 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 TargetPay, 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

  • oneoff
    Als u 1 meegeeft, wordt de incasso aangemerkt als eenmalig. In dit geval toont de incasso als eenmalig in de online bankomgeving van de consument, en moet het machtigingsnummer uniek zijn op de layoutcode.

  • test
    Als u 1 meegeeft, wordt de testmodus gebruikt. In dat geval worden alle checks gedaan, maar de betaling niet daadwerkelijk klaargezet. U krijgt altijd als transactie ID terug '12345678'. Als u de status navraagt van dit betaalkenmerk zal dit altijd '000000 OK' zijn.


2.2 Resultaatcode's
Als de incasso klaargezet is ontvangt u als resultaat:

000000 OK|#transactie-ID

Als de incasso niet is klaargezet volgt een van de volgende foutcodes:

TP0001 No layoutcode specified
TP0002 Amount too low
TP0003 Amount too high
TP0004 Invalid return URL
TP0005 Invalid or no report URL
TP0006 No description specified
TP0007 Invalid e-mailaddress
TP0009 Invalid or no user IP given
TP0010 No value for salt specified
TP0011 Value for salt is too long
TP0012 Invalid or no securitylevel set
TP0014 No bankaccount given
TP0015 No or invalid country given
TP0016 TargetPay account does not exist
TP0017 No customer name given (cname)
TP0018 No IBAN given
TP0019 No mandate given
TP0020 No mandatestart given
TP0021 Invalid mandatestart given
TP0022 SEPA cannot be in live and test mode at the same time
TP0999 Layoutcode expected, customer number given. Please use your correct layoutcode.

TP1000 Refused: invalid bankaccount, fails IBAN validation
TP1001 Refused: same account already billed last week
TP1002 Refused: same account still pending
TP1003 Refused: same account and amount still pending
TP1004 Refused: same account, amount AND description still pending
TP1006 Refused: user made a chargeback in the last 12 months
TP1007 Refused: not allowed to use direct debit
TP1008 Refused: only allowed after iDEAL/bank wire transaction
TP1009 Refused: duplicate mandate found for this one-off payment, must be unique


3. Status opvragen
3.1 Aanroep
Als u wilt kunt u ook actief de status van een betaling bij ons navragen. Dat kan met een aanroep naar:

https://www.targetpay.com/directdebit/check

Met de volgende parameters:

Variabele Naam Formaat Verplicht
trxidBetaalkenmerkNumeriekJa
rtloLayoutcodeNumeriekJa
checksumChecksumNumeriekJa
once'Reeds ingewisseld' melding?0 of 1Ja

Toelichting per variabele:
  • trxid
    Transactie ID, geretourneerd in de vorige stap

  • rtlo
    Layoutcode (zelfde waarde als meegegeven onder 5.1)

  • checksum
    De checksum is nodig om zeker te weten dat het verzoek van u afkomt. De checksum wordt berekend middels: $checksum = md5($trxid.$rtlo.'salt'); en wordt doorgegeven in kleine letters. Zie ook het kopje reporturl hierboven. Let wel, 'amount' maakt in dit geval geen onderdeel uit van de checksum berekening.

  • once
    Als u voor once '1' invult dan zal slechts 1x een OK status teruggegeven worden. Als de bovenstaande URL nog een keer wordt aangeroepen voor hetzelfde Transactie ID dan krijgt u een foutmelding TP00014 (Reeds ingewisseld) terug.
    Als u voor once '0' invult dan zal steeds een OK status terug blijven komen.
    Vul bij twijfel 1 in, zo weet u zeker dat een dienst niet meerdere malen geleverd wordt als de bezoeker op Refresh/F5 zou drukken.


3.2 Resultaatcode's
U ontvangt als antwoord de huidige status van deze transactie:

000000 OK

dit betekent dat de transactie aangeboden, geaccepteerd en verwerkt is door de bank. Het bedrag is niet gestorneerd door de klant.

Andere statussen zijn:

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

Mogelijke foutcodes zijn:

TP0014 Already redeemed at XXXX-XX-XX XX:XX:XX
TP0020 No layoutcode given
TP0021 No transaction ID given
TP0022 No transaction with this ID
TP0023 Layoutcode doesn't match transaction
TP0024 Checksum incorrect..


4. Machtigen met iDEAL
Het is naast een ondertekend formulier ook mogelijk om een incasso machtiging te verkrijgen door middel van een iDEAL transactie. Hiervoor dient de iDEAL API gecombineerd te worden met deze API. Zodra u in de iDEAL start aanroep een extra parameter &cinfo_in_callback=1 meestuurt, krijgt uw applicatie het rekeningnummer en de naam van de klant automatisch terug bij de statuscontrole van de transactie(check) De iDEAL start aanroep gaat er dan als volgt uit zien:
$url= "https://www.targetpay.com/ideal/start?".
"rtlo=".$rtlo.
"&cinfo_in_callback=1".
"&bank=".$bank.
"&description=".urlencode($description).
"&amount=".$amount.
"&returnurl=".urlencode($returnurl).
"&reporturl=".urlencode($reporturl);

Het resultaat wat terugkomt met de iDEAL status check wordt dan:
00000 OK|bankrekening|naam|plaats
Uw reporturl wordt met HTTP POST aangeroepen met de volgende parameters:
trxid=0030000794957746&rtlo=107053&status=000000 OK&cname=Naam&cbank=bankrekeningnumer
bankrekening en naam kunt u vervolgens gebruiken als cbank en cname als invoer voor de incasso.



© TargetPay.com

F.A.Q. | Contact | Netwerk status | Voorwaarden | Cookie Policy | Cookie Instellingen | Privacy | Regelgeving | Over ons... | Print versie