iDEAL API
Ready to use scripts for iDEAL
Mollie has collected some iDEAL PHP, ASP and other scripts for you that are ready to use, that way you can start quicker and don't have to build everything yourself. If those scripts don't suit your needs you can also read the full documentation below.
How the API works
To accept iDEAL payments a couple of steps need to be followed:
- Your platform requests a list of available banks that support iDEAL.
- Your platform requests a payment, which includes 'partner_id' and the chosen 'bank_id'. You save the data and redirect the client to the given URL.
- Our API gives a report when a payment status has been changed and your platform checks whether the payment has been done.
- We send your client back to the URL your platform gave us. For example a 'thank you' page of your store.
Our API uses HTTP requests. When you send a HTTP request to our server, you will be able to send values using POST or GET variables. The variable a is used to trigger the API into a specific 'mode'.
Test-mode
To enable testing you need to turn on test-mode. When test-mode is turned on the bank "TMB Bank" will be added to the available bank list. This is a fake bank we made up to test payments without really paying. You also need to add the parameter 'testmode=true' to step 3 while testing.
You can switch the iDEAL testmode on and off at the settings page.
Step 1: Retrieve the list of bank ID's
The bank list is variable. That is why you need to grap it once in a while. Here is an example of a response.
Request:
https://secure.mollie.nl/xml/ideal?a=banklist
An example of the result:
<?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>
After getting the bank ID's you will have to ask your client to select his or her bank. For example in a dropdown menu.
Step 2: Start a payment with the API
Because now we know which bank the client uses we ask the API to start a payment with the corresponding bank. In order to do this we use the 'fetchmode'. Therefore the variable a is 'fetch'. Below you'll find an example of the request.
Request:
https://secure.mollie.nl/xml/ideal?a=fetch&partnerid=[your 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
Below you see an example of the response:
<?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>
The table below shows the explanation of all possible variables. All parameters in the request to our API has to be 'url-encoded'.
Explanation of the variables of the iDEAL API in the 'fetchmode' (a=fetch):
| Parameter | Explanation |
|---|---|
partnerid |
[request] Mollie.nl account ID. For example partnerid=[your partner id]. This account ID will be used to register the payments. |
amount |
[request] Amount of the payment given in cents. For example, 10 EUR is 'amount=1000'. |
bank_id |
[request] ID of the bank. (given in the bank list). The 'leading zeros' are required. |
description |
[request] Description of the payment. This will also appear on the duplicates of the bank statement of the client. You may use a maximum of 29 characters (more will be thrown away). |
reporturl |
[request] When our platform knows if the client has paid, our platform will do a background HTTP request to this 'reporturl'. You will need to cross check it at our platform by doing a request back to our API in the 'checkmode'. More information about this subject will be discussed later on. This is a security-enhancement. |
returnurl |
[request] The client is sent to this URL when the payment process is done, independent on whether the payment was successful or not. When we send the client to this URL we add the variable 'transaction_id'. With this extra variable you can check which client it is and whether the amount was actually paid or not. |
profile_key (optional) |
[request] Allows you to select a different profile for this payment.Use the desired value from the Key column from your profile overview page. [ view available profiles ]. |
transaction_id |
[response] This is a hash used to check the payment state at our API. You have to save this ID into your own database, for example to match it to your client. You can also use this ID whenever you want to check the payment status. |
amount |
[response] The amount of the payment (double check). |
URL |
[response] You will have to redirect the client to this address to start the payment process. The client will be sent to his/her selected bank. |
Step 3: Feedback of the API and check payment state
By the payment request you choose a reporturl. On this URL on your own server you need to make a script that checks the payments when your platform does a request in the background. Our platform always adds a 'transaction_id' in the GET variable. You can use this 'transaction_id' to check if the payment has been successfully done or not. This status should probably be saved in your own database as well. To check a payment status you need to do the following:
reporturl fails (i.e. when the connection fails or the final HTTP response status code is not 200), Mollie will try another 10 times to access the reporturl. If by then the reporturl could still not be accessed, a warning will popup on your Mollie.nl dashboard.This does not happen when you have the testmode enabled: report URLs will only be tried once when testmode is activated.
Request:
https://secure.mollie.nl/xml/ideal?a=check&partnerid=[your partner id]&transaction_id=[transaction_id]
Example of the response you will get:
<?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>
If you double check a payment status that was successful the first time you checked, the second time it will appear as 'payed=false'. This is an extra protection to prevent that your clients can pay once en receive twice.
If you get 'payed=true' you may set the order as paid in your own database and start delivering the product or service. When the client comes back to you website you may give him/her the good news a.k.a. the 'thank you' page. Below a specification of the request- and response variables.
Variables for the iDEAL-API in the 'checkmode' (a=check):
| Parameter | Explanation |
|---|---|
partnerid |
[request] Mollie.nl account ID. For example partnerid=[your partner id]. This account ID will be used to register the payments. |
transaction_id |
[request and response] The transaction ID to track the payment in your and our platform. |
amount |
[response] The amount of the payment. Could be useful for double check. |
payed |
[response] 'true' or 'false'. Shows if client has paid. Note: we keep track of whether the payment is checked or not. Checking a successful payment twice will return 'false'. |
consumer |
[response] Subtag for client information, only shown with 'payed=true'. |
consumerName |
[response] Name of the client. |
consumerAccount |
[response] Account # of the client. (Postbank # starts with a 'P') |
consumerCity |
[response] City of the client. |
Step 4: The client redirects to returnurl
After the payment process is finished (even if the consumer cancelled the payment), we forward the client to the given returnurl. We add an extra GET parameter transaction_id. With this extra parameter you can match the client and show some relevant information, also known as the 'thank you' page.
Examples & Modules
You don't want to parse all the data yourself? Download the examples and classes 'to do your dirty work'.
| Download | Programming language | Author | Version |
|---|---|---|---|
| PHP class | PHP 5.x and higher | 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 and hoger | Mollie | v0.2.3 (20/07/10) |
| OpenCart module | PHP 5.x and higher | Marco Cox | v1.x t/m 4.x |
| osCommerce module | PHP 5.x and higher | Mollie | v2.7 (02/08/10) |
| osCommerce module (deprecated) | PHP 5.x and higher | Mollie | v1.5 (24/02/09) |
| VirtueMart module | PHP 5.x and higher | DcP ICT | v1.9 (16/08/10) |
| aMember | PHP 4.1.x and higher | Bart Kruger | v1.0 (10/02/09) |
| PrestaShop | PHP 5.x and higher | Jos Steenbergen | v1.2.5 (16/07/10) |
| WHMCS module | PHP 5.x and higher | Mollie | v1.1 (11/06/10) |
| X-Cart module | PHP 5.x and higher | PS4ALL | v1.0 (27/07/10) |
Overview error codes
The API output always contains a useful explanation. This overview of error codes may help you programming:
| Error code | Explanation |
|---|---|
| -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. |
