iDEAL is a popular online payment method in the Netherlands, allowing customers to make secure payments directly from their bank accounts. If you're a merchant looking to accept payments from Dutch customers, integrating iDEAL as a payment option on your website or e-commerce platform is crucial.
This is what the iDEAL payment flow looks like.
After a successful payment, the funds will be sent to the recipient Rootline account automatically. You don't have to capture the payment separately.
Create a seamless iDEAL flow with the Payments API
In The Payment API section we explain how the Payments API can be leveraged to create an iDEAL flow.
Checkout integration
Let Rootline handle the payment method selection. You initiate the payment by simply sending a payment request with below details.
{
"account_id": "acc_12347Sifdo36cdycbsw4Pum",
"amount": {
"currency": "EUR",
"quantity": "20.00"
},
"reference": "test_reference",
"statement_descriptor":"Bank statement text",
"return_url":"https://www.my_return_url.com"
}
The API will return a next_action object with a checkout_url. This url leads your customer to the Rootline checkout page, where they can select their payment method and further payment details.
{
"payment_id": "pmt_UXRFkdU6kdAtO6ceGdxmW",
"created_at": "2023-09-12T08:22:25.864452Z",
"account_id": "acc_12347Sifdo36cdycbsw4Pum",
"reference": "test_reference",
"amount": {
"currency": "EUR",
"quantity": "20.00"
},
"checkout_status": "open",
"authorizations": [],
"authentications": [],
"next_action": {
"checkout_url": "http://payment-api.rootline.com/payments/pmt_UXRFkdU6kdAtO6ceGdxmW/checkout"
},
"statement_descriptor":"Bank statement text",
"return_url": "https://www.my_return_url.com"
}
Forwarding your customer through the checkout url
Request a redirect to your customer's bank by calling (/GET) the checkout_url that Rootline provides.
Seamless redirect from your website to iDEAL
The custom integration allows you to redirect a customer from your page to the iDEAL bank selection page, without visibly interacting with Rootline's checkout pages. Payment method can be done in your own page. In addition to the /GET request above, to indicate that this is an iDEAL payment, provide ideal as the value for the payment_rails.payment_method field to indicate that iDEAL is the chosen payment method:
{
"account_id": "acc_12347Sifdo36cdycbsw4Pum",
"amount": {
"currency": "EUR",
"quantity": "20.00"
},
"payment_rails":{
"payment_method":"ideal"
},
"reference": "test_reference",
"description":"Test description",
"statement_descriptor":"Bank statement text",
"return_url":"https://www.my_return_url.com"
}
Use the checkout redirect url for a seamless redirect to your customer's bank. After completion of the payment, your customer will be redirected back to the return url that you provided.
{
"payment_id": "pmt_UXRFkdU6kdAtO6ceGdxmW",
"created_at": "2023-09-12T08:22:25.864452Z",
"account_id": "acc_12347Sifdo36cdycbsw4Pum",
"reference": "test_reference",
"amount": {
"currency": "EUR",
"quantity": "20.00"
},
"payment_rails":{
"payment_method":"ideal"
},
"checkout_status": "open",
"authorizations": [],
"authentications": [],
"next_action": {
"checkout_url": "http://payment-api.rootline.com/payments/pmt_UXRFkdU6kdAtO6ceGdxmW/redirect"
},
"statement_descriptor":"Bank statement text",
"return_url": "https://www.my_return_url.com"
}
Bank selection in your page
Only in exempted scenarios, iDEAL still allows for bank selection to be done on your side. The most common exemption is when you are storing a preferred bank for your customers, and now want to do this for new customers as well.
Our API allows for this scenario, as we allow you to provide the bank as part of the payment rails. To avoid fines, however, it is advised to consult with us before doing this.
Handle a shopper canceled response
A payment would ideally convert to a succeeded status. However, in some cases a buyer can decide to cancel the payment after being redirected to their bank. In that case, we treat the shopper's cancellation as a decline. Therefore, the API response will then look as follows.
{
"id": "pmt_UXRFkdU6kdAtO6ceGdxmW",
"object": "payment",
"created_at": "2024-02-22T11:02:51.792413Z",
"account_id": "acc_12347Sifdo36cdycbsw4Pum",
"reference": "ideal payment",
"amount": {
"currency": "EUR",
"quantity": "0.20"
},
"checkout_status": "failed",
"authorizations": [
{
"id": "auth_4Aw0pnL8zRZECx9P3IVbOL",
"object": "authorization",
"created_at": "2024-02-22T11:02:53.326401Z",
"amount": {
"currency": "EUR",
"quantity": "0.20"
},
"status": "declined",
"decline_details": {
"code": "customer_canceled",
"provider_response_code": "Canceled",
"provider_response_message": "Canceled"
},
"payment_rails": {
"payment_method": "ideal",
"bank_code": "abn_amro"
}
}
],
"return_url": "https://rootline.com/",
"description": "Test description",
"statement_descriptor": "Bank statement text"
}
The response will contain an authorization with a status, which in this case is declined. In the decline_details you will be informed about why the authorization was declined. In the 'customer canceled' scenario a code customer_canceled will be sent.
iDEAL banks
iDEAL supports all of the below banks. Use the bank_code in your payment request to Rootline.
| Bank | bank_code |
|---|---|
| ABN Amro | abn_amro |
| ASN Bank | asn_bank |
| Bunq | bunq |
| Knab | knab |
| N26 | n26 |
| Nationale Nederlanden | nationale_nederlanden |
| RegioBank | regiobank |
| Triodos Bank | triodos |
| ING | ing |
| Rabobank | rabobank |
| Revolut | revolut |
| SNS | sns |
| Van Lanschot Kempen | van_lanschot_kempen |
| Yoursafe | yoursafe |
Migration to iDeal 2.0
If you are currently sending in the bank_code, you will be required to change this to comply with the iDeal changes. For more information about the changes, please refer to iDeal's webpage.
May 27th
After this date you can start sending payments without the bank_code and consumers will be redirected to an iDeal page.
June 24th
From this date we will ignore the bank_code if you are still sending it to Rootline. If you still have a bank selection page, it means that your customer will have to select their bank twice. Once in your checkout, and once at iDeal.
July 1st
Official deadline to change to iDeal 2.0.
August 1st
Important. This is a month after the iDeal deadline. From this date onwards, we will stop supporting sending in the bank_code through the Payments API. If -in approaching this deadline- you still are sending in the bank_code, we will reach out to you before the deadline hits.