iDEAL API

Kant & klare scripts en integraties voor iDEAL

U hoeft zelf niet opnieuw het wiel uit te vinden. Mollie heeft een hele boel klant & klare scripts voor u klaargezet. Natuurlijk kunt u er ook voor kiezen om de integratie geheel zelf te doen als de scripts niet voldoen aan uw eisen.

Hoe werkt de API?

Om een iDEAL-betaling te realiseren moet u een aantal stappen doorlopen. Deze stappen zijn als volgt:

U vraagt bij onze API de lijst van banken op en laat uw klant haar bank kiezen.
U vraagt bij onze API een betaling aan op uw partner_id voor de gekozen bank en het bedrag. U slaat de teruggekregen informatie op en stuurt uw klant naar de URL die ook in het antwoord op de aanvraag van de betaling zit.
De API meldt zich na de betaling op de achtergrond bij een door u opgegeven url, waarna u de betaling controleert en dit resultaat bewaart.
Wij sturen nu de klant naar een door u opgegeven URL, zodat hij uw winkel weer inkomt. U toont de klant op die URL een melding dat het gelukt is, of dat het niet gelukt is en u verwerkt eventueel de order.

Onze API werkt middels HTTP requests. Wanneer u een HTTP request naar onze server stuurt, kunt u met behulp van POST of GET variabelen de waarden meesturen. De a-variabele wordt gebruikt om de API in een betaalde 'mode' te zetten. We behandelen nu de aanroepen en antwoorden van bovengenoemde stappen.

Testmode

Bij de eerste stap haalt u de lijst van actieve banken op die op dit moment iDEAL-betalingen ondersteunen. Als u betalingen wil testen, zonder daadwerkelijk een betaling uit te voeren kan dit door de 'testmode' aan te zetten. U krijgt dan een extra bank in deze lijst terug om te testen, namelijk de "TBM Bank" (a.k.a. "The Big Mollie Bank"). Bij stap 3 moet u dan (vanwege extra veiligheidsmaatregelen) ook een extra parameter 'testmode=true' meesturen om aan te geven dat het om een testbetaling gaat, welke u na het live gaan van uw product weer moet verwijderen.

Op de instellingen-pagina kunt u de iDEAL testmode aan en uit te zetten.

Stap 1: Ophalen lijst van banken

De lijst van banken kan veranderen en dient daarom telkens te worden opgehaald. De XML die terugkomt uit deze aanvraag gaat (zoals alle antwoorden doen) gepaard met een verklarende melding.

Als u 'testmode' aan heeft staan dient u de parameter 'testmode=true' ook mee te sturen. Hieronder een voorbeeld hoe een status opvraagt:

Aanvraag:

https://secure.mollie.nl/xml/ideal?a=banklist

Hierop krijgt u bijvoorbeeld het volgende antwoord:


        <?xml version="1.0"?>

        <response>

            <bank>

                <bank_id>0031</bank_id>

                <bank_name>ABN AMRO</bank_name>

            </bank>

            <bank>

                <bank_id>0721</bank_id>

                <bank_name>Postbank</bank_name>

            </bank>

            <bank>

                <bank_id>0021</bank_id>

                <bank_name>Rabobank</bank_name>

            </bank>

            <message>This is the current list of banks and their ID's that currently support iDEAL-payments</message>

        </response>

Stap 2: Vraag een betaling aan bij de API

Nu we weten welke bank de klant gebruikt kunnen we de betaling klaarzetten. Daartoe doen we een aanvraag in de 'fetchmode'. Hierbij is de a-variabele dus 'fetch'. Eerst een voorbeeld van zo'n aanvraag. Daarna uitleg over de gebruikte variabelen.

Aanvraag:

https://secure.mollie.nl/xml/ideal?a=fetch&partnerid=[uw partner id] &description=Hier+een+beschrijving&reporturl=http%3A%2F%2Fwww.uwsite.nl%2Freport.php&returnurl=http%3A%2F%2Fwww.uwsite.nl%2Freturn.php&amount=123&bank_id=0721

Hierop krijgt u bijvoorbeeld het volgende antwoord:


        <?xml version="1.0"?>

        <response>

            <order>

                <transaction_id>482d599bbcc7795727650330ad65fe9b </transaction_id>

                <amount>123</amount>

                <currency>EUR</currency>

                <URL>https://mijn.postbank.nl/internetbankieren/SesamLoginServlet?sessie=ideal&trxid=003123456789123&random=123456789abcdefgh</URL>

                <message>Your iDEAL-payment has succesfuly been setup. Your customer should visit the given URL to make the payment</message>

            </order>

        </response>

Dit lijkt allemaal wat ingewikkeld, maar dat valt best mee. Onderstaande tabel geeft uitleg over de in- en output variabelen van dit soort aanvragen. Zorg er overigens altijd voor dat de variabelen 'url-encoded' zijn. Zorg dat alles volgens het HTTP-protocol geschiedt.

Variabelen voor de iDEAL-API in de 'fetchmode' (a=fetch):

Parameter	Uitleg
`partnerid`	[aanvraag] Mollie.nl accountnummer. Bijvoorbeeld `partnerid=[uw partner id]`. Op de gespecificeerde account worden tegoeden bijgeschreven bij succesvolle betaling.
`amount`	[aanvraag] Bedrag van de betaling. GEGEVEN IN CENTEN! Dus wilt u een tientje afrekenen? Dan moet amount=1000 zijn. Let op, want door dit fout te doen kan de marge nogal klein worden ;)
`bank_id`	[aanvraag] Id van de bank. (Zoals de Id's voorkomen in de banklist uiteraard). We willen ook de 'leading zeros', en als zodanig bestaat een bank_id dus altijd uit 4 cijfers, en niets anders.
`description`	[aanvraag] Hiermee kan in 29 letters (extra letters worden getrashed) een beschrijving worden meegegeven die in het online-bankpakket getoond wordt. Zorg dus dat hier iets staat dat de lading dekt.
`reporturl`	[aanvraag] Op het moment dat door het handelen van uw bezoeker duidelijk wordt of een betaling wel of niet is gelukt, doen wij OP DE ACHTERGROND een aanvraag naar deze url. In deze aanvraag vermelden we niet of de betaling al dan niet gelukt is. Dit moet u zelf checken als reactie op onze aanvraag naar uw reporturl (met de api in 'checkmode', wordt later behandeld). Dit lijkt onhandig, maar is feitelijk een security-enhancement. Als we dit niet zo doen, zouden mensen direct informatie aan uw report-script kunnen voeren. En dat kan gevaarlijk zijn. We geven als extra variablele 'transaction_id' mee. Deze parameter heeft u nodig bij het checken.
`returnurl`	[aanvraag] Dit is de URL waar we uw klant heen sturen als het betaalproces (al dan niet succesvol) is afgerond. Als we de klant naar deze URL sturen, voegen we weer als extra variabele 'transaction_id' mee. Zo kunt u bijvoorbeeld weer opzoeken om welke klant het ging.
`profile_key` (optioneel)	[aanvraag] Hiermee kunt u een ander profiel selecteren om uw betaling aan te linken. Gebruik de waarde uit het veld Key uit het profiel overzicht. [ bekijk overzicht van uw profielen ].
`transaction_id`	[antwoord] Dit is de combinatie van cijfers en letters waarmee de zojuist aangevraagde transactie kan worden geïndentificeerd. Deze ID kan gebruikt worden om in uw eigen datatabase op te slaan, en te koppelen aan de klant van uw site. Ook kan deze ID in combinatie met de 'checkmode' van de API gebruikt worden om te checken of de betaling gelukt is.
`amount`	[antwoord] Dit is het bedrag zoals het is aangevraagd. Puur voor checks.
`URL`	[antwoord] Dit is de URL waar de klant heen moet worden gestuurd zodat hij aan de betaling kan beginnen. Dit correspondeert met de gekozen bank. Daar is alvast een sessie aangemaakt, waar uw klant direct haar betaling in kan doen.

Stap 3: Feedback van de API

Bij de aanvraag heeft u een reporturl meegegeven. Op deze URL dient een script van u te staan die, wanneer het wordt aangeroepen, met een 'transaction_id' als GET-variabele een check gaat uitvoeren bij onze API. Middels deze check controleert u of de betaling die bij 'transaction_id' hoort, betaald is of niet. Dit resultaat slaat u op bij de klant die bij de transaction_id hoort in uw database. (U heeft deze koppeling immers aan de hand van de response van stap 2 gemaakt).

Als u 'testmode' aan heeft staan dient u de parameter 'testmode=true' ook mee te sturen. Hieronder een voorbeeld hoe u een status opvraagt:

Let op: Wanneer de aanroep naar uw reporturl niet lukt (bijvoorbeeld wanneer de connectie niet lukt of als de uiteindelijke HTTP status code niet 200 is), zal Mollie nog 10x op verschillende tijdsintervallen proberen de reporturl alsnog aan te roepen. Mocht het dan nog niet gelukt zijn, dan krijgt u een waarschuwing op uw beheer pagina.

Heeft u echter de testmode aan staan, dan zal dit niet gebeuren en zal de 'reporturl' slechts éénmaal aangeroepen worden.

Aanvraag:

https://secure.mollie.nl/xml/ideal?a=check&partnerid=[uw partner id]&transaction_id=[transaction_id]

Hierop krijgt u bijvoorbeeld het volgende antwoord:


        <?xml version="1.0"?>

        <response>

            <order>

                <transaction_id>482d599bbcc7795727650330ad65fe9b</transaction_id>

                <amount>123</amount>

                <currency>EUR</currency>

                <payed>true</payed>

                <consumer>

                    <consumerName>Hr J Janssen</consumerName>

                    <consumerAccount>P001234567</consumerAccount>

                    <consumerCity>Amsterdam</consumerCity>

                </consumer>

                <message>This iDEAL-order has successfuly been payed for, and this is the first time you check it.</message>

            </order>

        </response>

Als u een tweede keer een betaling probeert te checken die weliswaar betaald is, maar die u al een keer heeft gecheckt, krijgt u daar geen payed=true uit. Zo kunnen pogingen van doortrapte klanten om orders twee keer geleverd te krijgen voor de prijs van één, in de kiem gesmoord worden.

Als u payed=true krijgt, kunt u dus in uw eigen database de order van de klant op betaald zetten. Als de klant dan later terugkomt in de winkel kunt u hem of haar het goede nieuws mededelen. Als de API onbekend is met een transactie, of de transactie niet betaald is (of dus al gecheckt), zal de API u dit altijd duidelijk vertellen in de message variabele. Hieronder de specifieke uitleg over de aanvraag- en antwoordvariabelen van de API in de 'checkmode'.

Variabelen voor de iDEAL-API in de 'checkmode' (a=check):

Parameter	Uitleg
`partnerid`	[aanvraag] Mollie.nl accountnummer. Bijvoorbeeld `partnerid=[uw partner id]`. Op de gespecificeerde account worden tegoeden bijgeschreven bij succesvolle betaling.
`testmode`	[aanvraag] Als de waarde `true` is, betreft het een testbetaling (optioneel, standaard `false`).
`transaction_id`	[aanvraag en antwoord] Dit is de combinatie van cijfers en letters waarmee de transactie kan worden geïndentificeerd bij ons (en uw) systeem.
`amount`	[antwoord] Dit is het bedrag zoals het is aangevraagd. Puur voor checks.
`payed`	[antwoord] 'true' of 'false'. Geeft aan of er betaald is. Let op, wij houden bij of u al succesvol gecheckt heeft. Dus als u de tweede keer checkt sinds er betaald is, krijgt u hier 'false'. Zo beschermen we u tegen mogelijke fraude bij uw klanten.
`consumer`	[antwoord] Subtag met klantgegevens. Wordt alleen meegegeven bij payed=true, om pogingen tot data-mining te voorkomen.
`consumerName`	[antwoord] Naam van de klant.
`consumerAccount`	[antwoord] Rekeningnummer van de klant. (Postbankrekeningnummers beginnen met een 'P', en zijn 1 cijfer korter.)
`consumerCity`	[antwoord] Woonplaats van de klant.

Stap 4: De consument komt terug op returnurl

Nadat de betaling wel of niet gelukt is, sturen we de consument terug naar de door u in returnurl opgegeven URL met als extra variabele transaction_id, waarmee u weer kunt bepalen welke klant het is, en of volgens uw database die betaling gelukt was (u checkte dat immers eerder met het script op reporturl via de 'checkmode', en bewaarde dat resultaat). Aan de hand hiervan laat u de consument dus een bevestiging zien, of iets anders wat van toepassing is.

Voorbeelden & Modules

Hieronder hebben we voor u simpele voorbeelden klaarstaan in verschillende programmeertalen en modules voor webwinkelsystemen.

Omschrijving	Programmeertaal	Auteur	Versie
PHP class	PHP 5.x en hoger	Mollie	v1.11 (01/07/2010)
Perl module	Perl	b10m	v0.01
ASP module	ASP (classic)	Directshop.nl	v0.01 (12/08/09)
ASP.NET module	ASP.Net	LotenDelen.nl	v1.00
Magento module	PHP 5.x en hoger	Mollie	v0.2.3 (20/07/10)
OpenCart module	PHP 5.x en hoger	Marco Cox	v1.x t/m 4.x
osCommerce module	PHP 5.x en hoger	Mollie	v2.7 (02/08/10)
osCommerce module (oud)	PHP 5.x en hoger	Mollie	v1.5 (24/02/09)
VirtueMart module	PHP 5.x en hoger	DcP ICT	v1.9 (16/08/10)
aMember	PHP 4.1.x en hoger	Bart Kruger	v1.0 (10/02/09)
PrestaShop	PHP 5.x en hoger	Jos Steenbergen	v1.2.5 (16/07/10)
WHMCS module	PHP 5.x en hoger	Mollie	v1.1 (11/06/10)
X-Cart module	PHP 5.x en hoger	PS4ALL	v1.0 (27/07/10)

Overzicht foutcodes

De API geeft bij iedere output een zinvolle uitleg. Bij het programmeren kan het fijn zijn om een overzicht te hebben van de foutcodes en de bijbehorende berichten.

Foutcode	Uitleg
-1	Did not receive a proper input value.
-2	A fetch was issued without specification of 'partnerid'.
-3	A fetch was issued without (proper) specification of 'reporturl'.
-4	A fetch was issued without specification of 'amount'.
-5	A fetch was issued without specification of 'bank_id'.
-6	A fetch was issues without specification of a known 'bank_id'.
-7	A fetch was issued without specification of 'description'.
-8	A check was issued without specification of transaction_id.
-9	Transaction_id contains illegal characters. (Logged as attempt to mangle).
-10	This is an unknown order.
-11	A check was issued without specification of your partner_id.
-12	A fetch was issued without (proper) specification of 'returnurl'.
-13	This amount is only permitted when iDEAL contract is signed and sent to Mollie.
-14	Minimum amount for an ideal transaction is € 1,18.
-15	A fetch was issued for an account which is not allowed to accept iDEAL payments (yet).
-16	A fetch was issued for an unknown or inactive profile.

Other languages

In English

iDEAL API

Kant & klare scripts en integraties voor iDEAL

Hoe werkt de API?

Testmode

Stap 1: Ophalen lijst van banken

Stap 2: Vraag een betaling aan bij de API

Stap 3: Feedback van de API

Stap 4: De consument komt terug op returnurl

Voorbeelden & Modules

Overzicht foutcodes

Other languages

Op deze pagina

Navigeer snel naar

Support

Klantportfolio

Sales-team

Contact