Tutorial 2: Create SEPA batch (pain.008.001.02.)

Door xleeuwx op maandag 2 juni 2014 10:00 - Reacties (5)
Categorie: PHP Scripts, Views: 9.974

Voorwoordje

Het probleem:
Een groot ledenbestand (50k+) met een hoop geld te innen via automatisch incasso bestand dit moet omgezet worden in een SEPA bestand. Bij mijn weten iets waar velen tegen aan zullen lopen komende tijd.
Wat is SEPA ?
Waar te beginnen... SEPA is in het leven geroepen om de automatisch incasso te vervangen door een nieuw protecol vanuit europa, op zich een voordeel. Het grootste nadeel is echter dat de controle wat strenger is en dat je inplaats van bankrekening nummer een IBAN en BIC nodig hebt.
De oplossing:
Een webbased script dat van leden bestand een sepa batch bestand kan maken.
Het systeem:
Het systeem waarop gewerkt word is Windows server 2012 met Apache 2.4 en mysql 5.6 (eventjes uit het hoofdje)
Alternatieven
Hoor ik graag, laat maar in een reactie achter hoe jij denkt dat dit beter opgelost kan worden.
De problemen waar ik tegen aan liep
Het omschrijven van automatisch incasso naar SEPA... Documentatie opzoeken van de vereisten ... een paar uur later me te verdiepen in wat SEPA inhield wist ik dat dit geen normaal klusje ging worden.
Inmiddels was ik er al wel achter dat er al een PHP class voor bestond en dat er diverse test servers waren waar je je XML kan testen. Ik zal deze ook onderaan de tutorrial zetten
Voor we beginnen zijn er wel een paar vereisten waar je klanten / leden / sponsers / enz. aan moet voldoen.
  • Geldige naam voor ontvanger
  • IBAN
  • BIC (niet vereist wel aanbevolen)
En ander probleem wat ik tegen kwam was dat ik een gebruikers bestand probeerde aan te maken die 10000 leden had. En blijkbaar mag je per SEPA bestand maar 100 leden bestelen, dan stoppen we toch alles in een zip file :)
Credits:
Voor we gaan beginnen met de code wil ik graag wat credits toeschuiven naar de maker van de SEPA class die deze onder MIT LICENSE heeft vrijgegeven

De tutorial

Start van het script
Ik heb het scripje uit een bestaand systeem gehaald en dit als stand alone systeem gemaakt voor de tutorial, daarvoor heb ik een index file gemaakt die alles afhandeld.
Voor de database tabellen heb ik fictieve data gebruikt (wel valide iban en bic codes maar geen echte) verder is de bic_code tabel wel valide en deze zou je eventueel kunnen gebruiken.

Daarnaast heb ik de volgende files in de includes map:En de database file met de volgende tabellen:De files kunnen gedownload worden vanaf sourceforge:
Files
De index.php
In de index file worden de autoloader en getMembers functie's geladen. De autoloader haalt automatisch de classes op uit de map includes als deze aangeroepen wordt.

ook zit in de index.php de configuratie voor de afzender van de batch file, het totaal bedrag te betalen word uit de database gehaald.


PHP:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
<?php
/* MIT LICENSE ... etc *knip* */
/**
 *
 * Includes required files
 * 
 * Get Config (Required for autoloader that is loading the classes)
 *
 * Get Members
 *
 */
    // Include Autoloader
        include_once("includes/autoLoader.inc.php");
    
    // Includes members file
        include_once("includes/getMembers.inc.php");

/**
 *
 * Start function get Members
 * 
 */ 
$members = fgetMembers();

/**
 *
 * Create array of config for sepa Export 
 *
 */


$config = array("name" => "xleeuwx",
                "IBAN" => "NL24RABO0123456789",
                "BIC" => "RABONL2U",
                "batch" => true,
                "creditor_id" => "00000",
                "currency" => "EUR"             
                );

/**
 *
 * Start class for exporting the SEPA files And execute -> fstartExport()
 *
 */ 
$exportFile = new SepaExport($config, $members);

$zipFile = $exportFile->fstartExport();
    
?>

autoLoader.inc.php
Zoals in de index al besproken word hier de classes geladen wanneer deze aangeroepen wordt. Op zich geen bijzondere code.
config.class.php
Hierin worden de mysql settings gedefineerd bijvoorbeeld de host, user, pass en database name. Dit is misschien voor deze tutorial beetje omslachtige manier, maar om niet te veel te hoeven ombouwen heb ik er toch voor gekozen het in een class te laten zitten en de benodigde functies er in te laten.

in de construct kan je de waardes gewoon aanpassen, van bijvoorbeeld de host zoals hieronder in de code blok, is het eerste parameter de group van de settings. De tweede parameter is de key en de derde de waarde.


PHP:
1
$this->fsetConfig("mysql", "dbhost", "localhost");

database.class.php
Ook hier heb ik weer moeten lopen knippen in de class, deze is met het minimaal benodigde functies uitgerust.

Om een database connectie te maken type je gewoon:


PHP:
1
2
$db = new database();
    $conn = $db->fgetConnection();



En daarna zit de mysqli link in de $conn. Deze zal ik ook in de andere files gebruiken om snel een connectie met de database te maken. Voor de rest weinig interresants :)
getMembers.inc.php
Een script die de members uit de database haalt en de IBAN en BIC codes controleerd, mocht de IBAN goed zijn en de BIC niet dan haalt hij de juiste BIC uit de database, kan hij deze niet vinden ? dan verwijderd hij de member uit de array.

LET OP! de members waar geen juiste gegevens van zijn (IBAN, BIC, Geen naam) worden niet opgenomen in de batch, dit om errors te voorkomen
sepaExport.class.php
Deze class maakt van de members array een SEPA export en per 100 (max members per batch) members maakt hij een xml file aan. Daarna zipt hij deze xml files in een zipje en deze geeft hij terug.
sepaSDD.class.php
Deze class is ongewijzigd gewoon van GitHub gehaald. hier ga ik dus ook niet lang bij stil staan hij doet wat hij moet doen, de xml files maken :)

Volgende week

Het probleem
Kijken of de dns records naar de juiste IP adressen word verwezen

Oplossing
DNS ophalen van de domeinnaam en deze uitlezen en vergelijken.

Volgende: Tutorial 3: DNS records ophalen 06-'14 Tutorial 3: DNS records ophalen
Volgende: Tutorial 1: Create apache dynamic vhost file with php from mysql 05-'14 Tutorial 1: Create apache dynamic vhost file with php from mysql

Reacties


Door Tweakers user Eparox, maandag 2 juni 2014 11:26

Ik liep ook tegen dit probleem aan en heb me rot gezocht. Wij werken met een jaarlijks event waarvoor inschrijfgelden geïncasseerd worden (eenmaling, non-recurring). De stoplichtkaarten heb ik automatisch laten invullen d.m.v. een python-scriptje, zodat deze alleen nog maar ondertekend hoefden te worden bij aankomst.

De SEPA-batch .xml heb ik gemaakt d.m.v. een tooltje in excel, in elkaar geflanst door de beste man van deze website: http://www.ro-pay.nl/ (zie downloads). Geheel met voorbeeldinput en documentatie.

Het enige wat je nodig hebt is dat gratis excel-script en je inputdata in de juiste kolommen. Een paar instelling doorklikken en floempie: 1000 incasso's binnen een seconde gegenereerd in één .xml. Geen enkele fout tijdens het uploaden en geen enkele incasso gestorneerd (m.u.v. ontoereikend saldo ;) ). Het mooie is dat hij ook controleert of bijvoorbeeld de IBAN nummers aan alle eisen voldoen (geen spaties, juiste format, etc.)

Hierboven gegeven is ook een kekke oplossing, maar ik denk deze excel oplossing wat laagdrempeliger is voor de gemiddelde incasseur die geen kaas heeft gegeten van webservers en php.

Door Tweakers user Shinoki, maandag 2 juni 2014 13:32

Let trouwens ook op dat elke bank weer een variatie hanteert op het PAIN.00X standard. De verschillen zijn subtiel maar die zijn er wel.

Door Tweakers user xleeuwx, maandag 2 juni 2014 13:36

Eparox schreef op maandag 02 juni 2014 @ 11:26:
[...]
De SEPA-batch .xml heb ik gemaakt d.m.v. een tooltje in excel, in elkaar geflanst door de beste man van deze website: http://www.ro-pay.nl/ (zie downloads). Geheel met voorbeeldinput en documentatie.

[...]

Hierboven gegeven is ook een kekke oplossing, maar ik denk deze excel oplossing wat laagdrempeliger is voor de gemiddelde incasseur die geen kaas heeft gegeten van webservers en php.
Zal het er nog even bijvermelden als alternatief ;) al was het hoofdzakelijk voor de doelgroep programmeurs bedoelt :Y)
Shinoki schreef op maandag 02 juni 2014 @ 13:32:
Let trouwens ook op dat elke bank weer een variatie hanteert op het PAIN.00X standard. De verschillen zijn subtiel maar die zijn er wel.
Had ik inderdaad ook al uitgezocht

En wat ik onderandere tegen kwam was:

Op 1 februar1 2014 zal er geen nieuwe versie van het pain.008 van toepassing zijn. De huidige versie (pain.008.001.02) blijft dan nog steeds van toepassing. Er zijn nog geen plannen om de volgende ISO versies (pain.008.001.03 resp. pain.008.001.04) te gaan gebruiken.

Oftewel het is nog veilig om PAIN 008.001.02 te gebruiken. Dit ook omdat niet alle banken de nieuwe standaarden nog accepteren (Volgens mij in NL wel maar der buiten sommige nog niet)

[Reactie gewijzigd op maandag 2 juni 2014 13:39]


Door Tweakers user The Fox NL, dinsdag 3 juni 2014 20:40

Met SEPA Incasso zijn IBAN en BIC wel de minste van je problemen ;) Machtigingenadministratie, das pas een gedoe. Bijhouden wanneer je een First of Recurrent sequencetype moet gebruiken. Oppassen dat je niet twee Firsts voor dezelfde machtiging in een batch stopt, amendmentinfo meegeven etc.

Een maximum is van 100 opdrachten per batch is niet juist, dat is veel hoger. Ik weet het niet meer precies, maar een paar duizend is geen probleem. Je hebt waarschijnlijk de ING formatenchecker gebruikt? Volgens mij geeft die een limiet van 100 om te voorkomen dat men bestanden met duizenden opdrachten erin probeert te valideren.

Verder is het een leuke eerste opzet.

Door Tweakers user xleeuwx, woensdag 4 juni 2014 10:12

The Fox NL schreef op dinsdag 03 juni 2014 @ 20:40:
Met SEPA Incasso zijn IBAN en BIC wel de minste van je problemen ;) Machtigingenadministratie, das pas een gedoe. Bijhouden wanneer je een First of Recurrent sequencetype moet gebruiken. Oppassen dat je niet twee Firsts voor dezelfde machtiging in een batch stopt, amendmentinfo meegeven etc.

Een maximum is van 100 opdrachten per batch is niet juist, dat is veel hoger. Ik weet het niet meer precies, maar een paar duizend is geen probleem. Je hebt waarschijnlijk de ING formatenchecker gebruikt? Volgens mij geeft die een limiet van 100 om te voorkomen dat men bestanden met duizenden opdrachten erin probeert te valideren.

Verder is het een leuke eerste opzet.
True story, alleen om dat allemaal in deze blog post te gooien werd het wel heel erg lang :) maar inderdaad. Voor ons gold dit niet omdat de batch files uit meerdere systemen kwamen werd dit overal appart ingevoerd. Dus de vraag voor ons was ook om dit een variabel te maken. (in de tutorial is hij een vaste waarde in een array)

Reageren is niet meer mogelijk