iDEAL API

Wat heeft u nodig?

Om de iDEAL koppeling te testen heeft u de volgende gegevens nodig:

Uw Mollie partner ID: wanneer u bent ingelogd vindt u deze op de Accountgegevens pagina.
Een actief websiteprofielen waar de betalingen aan gekoppeld worden.

Om daadwerkelijk iDEAL betalingen te kunnen ontvangen dient iDEAL eerst geactiveerd te worden voor uw account. U kunt dit doen door de benodigde informatie aan ons te leveren via de Diensten pagina.

Kant-en-klare scripts en integraties voor iDEAL

U hoeft zelf niet opnieuw het wiel uit te vinden. Mollie heeft een hele boel
kant-en-klare scripts voor u klaar staan. 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 bepaalde '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 moet daarom iedere keer worden opgehaald. De XML die terugkomt uit deze aanvraag gaat (zoals bij alle antwoorden) 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 u 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 het gespecificeerde account wordt na succesvolle betaling tegoed bijgeschreven.
`amount`	[aanvraag] Bedrag van de betaling. GEGEVEN IN CENTEN! Dus wilt u een tientje afrekenen? Dan moet de parameter als `amount=1000` worden meegegeven. 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 verwijderd) een beschrijving worden meegegeven die in het online-bankpakket getoond wordt. Zorg dus dat hier iets staat dat de lading dekt, zoals een ordernummer.
`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 websiteprofielen 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. Het transactie id is altijd 32 karakters lang.
`amount`	[antwoord] Dit is het bedrag zoals het is aangevraagd. Puur ter controle.
`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: Status rapportage van de betaling

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. Het transactie id is altijd 32 karakters lang.

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 eerder succesvol gecheckt heeft. Dus als u de tweede keer checkt sinds de betaling, krijgt u hier 'false'. Zo beschermen we u tegen mogelijke fraude bij uw klanten.

status

[antwoord] Geeft de exacte status zoals deze van de bank terug kwam, mits deze beschikbaar was. Mogelijke statussen zijn:

Status	Omschrijving
Success	De betaling is gelukt
Cancelled	De consument heeft de betaling geannuleerd.
Failure	De betaling is niet gelukt (er is geen verdere informatie beschikbaar)
Expired	De betaling is verlopen doordat de consument niets met de betaling heeft gedaan.
CheckedBefore	U heeft de betalingstatus al een keer opgevraagd.

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. Als deze informatie niet beschikbaar is, zal dit veld NOT PROVIDED bevatten.

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 controleerde 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.

Uitzonderlijke situaties

In sommige gevallen is het mogelijk dat uw klant éérder terugkomt op de returnurl dan dat Mollie uw reporturl heeft aangeroepen. Dit kan bijvoorbeeld gebeuren wanneer er een storing optreedt bij de bank waardoor de status nog niet bekend is.

In deze situatie is het belangrijk om te onthouden dat Mollie uw systeem pas een rapportage stuurt op de reporturl op het moment dat de definitieve status van de betaling bij Mollie bekend is. Als u dit nog niet heeft ontvangen, weet uw systeem dus nog niet de definitieve status van de betaling.

Om uw klant in deze uitzonderlijke situatie niet in de war te brengen is het verstandig om duidelijk aan te geven dat de definitieve status van de betaling nog niet duidelijk is; maar dat de betaling - zogauw dat wel duidelijk is - automatisch wordt verwerkt.

Voorbeelden & Modules

Wilt u een direct een iDEAL-module gebruiken die u in uw webshop kan plaatsen?
Kijk in het module-overzicht of uw webshop-systeem ertussen staat.

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,20.
-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.
-17	The provided 'returnurl' cannot be used.

Other languages

In English

iDEAL API

Wat heeft u nodig?

Kant-en-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: Status rapportage van de betaling

Stap 4: De consument komt terug op returnurl

Uitzonderlijke situaties

Voorbeelden & Modules

Overzicht foutcodes

Other languages

Op deze pagina

Navigeer snel naar

Support

Klantportfolio

Salesteam

Contact