|
|
Documentatie: Automatische incasso
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.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 |
| rtlo | Layoutcode | Numeriek | Ja |
| description | Omschrijving | Alfanumeriek | Ja |
| userip | IP adres of uniek ID van uw klant | Alfanumeriek | Ja |
| amount | Bedrag in eurocenten | Alfanumeriek | Ja |
| country | Landcode consument | Alfanumeriek | Ja |
| mandate | Unieke nummer van de SEPA machtiging | Alfanumeriek | Ja |
| mandatestart | Startdatum van de SEPA machtiging | Numeriek | Ja |
| cbank | IBAN bankrekeningnummer consument | Alfanumeriek | Ja |
| cname | Naam consument | Alfanumeriek | Ja |
| salt | Een willekeurige reeks karakters voor berekenen van checksum van de reporturl (zie: reporturl). Maximaal 32 tekens. | Alfanumeriek | Ja |
| reporturl | Rapporteer naar URL | Alfanumeriek | Ja |
| email | E-mailadres van uw klant | Alfanumeriek | Nee |
| returnurl | Return URL | Alfanumeriek | Ja |
| duedate | Datum van de incasso | YYYY-MM-DD | Nee |
| securitylevel | Beveiliging voor dubbele betalingen | Numeriek | Ja |
| oneoff | Eenmalige incasso | 0 of 1 | Nee |
| test | Test modus | 0 of 1 | Nee |
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.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 |
| trxid | Betaalkenmerk | Numeriek | Ja |
| rtlo | Layoutcode | Numeriek | Ja |
| checksum | Checksum | Numeriek | Ja |
| once | 'Reeds ingewisseld' melding? | 0 of 1 | Ja |
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..
|
|
|
|
Niet ingelogd, klik hier
