iDEAL
Integrate iDEAL, the most successful and most frequently used payment method in the Netherlands. iDEAL covers all major Dutch banks and nearly all Dutch online consumers are comfortable paying and familiar with it. Learn more.
Markets | NL |
Processing currencies | EUR |
Consumer currencies | EUR |
Settlement currencies | EUR |
Minimum payment amount | 0.01 EUR |
Maximum payment amount | Varies by consumer bank |
Recurring payments | Yes (through SEPA Direct Debit) |
Separate captures | No |
Timeout | 30 minutes |
Refund | Full - Partial - Multiple Partial |
Refund validity | 365 days |
Chargeback | No |
Sandbox availability | PPRO provided |
Consumer Bank Selection
In the iDEAL payment flow, the consumer selects their online bank and is then redirected to their bank's online environment to approve the payment.
The iDEAL APIs support the provisioning of the consumer's BIC. The conditions for providing the bankCode
, and thereby bypassing the iDEAL payment page are:
- Acquiring Participants who know the preferred bank of the consumer are allowed to send in their BIC. The preferred bank could be known for example because it is stored in a user account.
- Acquiring Participants that store the preferred bank must offer the option to pay with another bank than the preferred bank, which can only be done via the iDEAL payment page.
- Acquiring Participants that can store a preferred bank must be able to support all (new) iDEAL Issuers as a preferred bank.
The bank selection step can be integrated in two different ways:
- If you already know the consumers preferred bank and meet iDEAL's conditions, you can send us the BIC representing the chosen bank in your API request using the
bankCode
field of theBANK_ACCOUNT
payment instrument.
The consumer will then be redirected directly to their bank's environment.
bankCode (BIC) | Bank |
---|---|
ABNANL2A | ABN AMRO |
ASNBNL21 | ASN Bank |
BUNQNL2A | Bunq |
INGBNL2A | ING |
KNABNL2H | Knab |
NTSBDEB1 | N26 |
NNBANL2G | Nationale-Nederlanden |
RABONL2U | Rabobank |
RBRBNL21 | RegioBank |
REVOLT21 | Revolut |
SNSBNL2A | SNS |
TRIONL2U | Triodos Bank |
FVLBNL22 | Van Lanschot Kempen |
BITSNL2A | Yoursafe |
- Alternatively, if you do not include the
bankCode
in the request, the consumer is redirected to iDEAL's payment page where the consumer scans the QR code or selects their bank. After selecting their bank, the consumer is then redirected to their bank's environment.
Make an iDEAL Payment
To make an iDEAL payment, you'll need to provide the following data when calling our /v1/payment-charges API:
Data Field | Required | Description |
---|---|---|
paymentMethod | Y | IDEAL |
amount.value | Y | The amount to be paid in the smallest units of the currency used. |
amount.currency | Y | EUR The currency used for the payment |
consumer.name | Y | Full name of the consumer |
consumer.country | Y | The country where the consumer is shopping |
authenticationSettings: REDIRECT settings.returnUrl | Y | Specify the URL that the consumer should be redirected back to after completing the payment |
instrument: BANK_ACCOUNT details.bankCode | Valid BIC. It can only contain 8 or 11 alphanumeric characters. Must be an iDEAL issuer’s BIC as listed above. | |
initiator | Required for payments initiated by a consumer. If not included, it's assumed the transaction is initiated by a merchant. | |
webhooksUrl | You should include the endpoint URL where you want to receive webhooks for updates to the payment charge. |
Request
POST /v1/payment-charges
{
"paymentMethod":"IDEAL",
"amount":{
"value":1000,
"currency":"EUR"
},
"consumer":{
"name": "Connor Summer",
"country": "NL"
},
"instrument": {
"type": "BANK_ACCOUNT",
"details": {
"bankCode": "ABNANL2A" //optional
}
},
"authenticationSettings": [
{
"type": "REDIRECT",
"settings": {
"returnUrl": "https://example.com/order_details?order_id=12345"
}
}
],
"webhooksUrl": "https://your-webhooks-endpoint/" //optional
}
Response
You'll receive one of our standard payment charge responses (see potential responses in the API Reference)
{
"id": "charge_X0O78tadFHrZCbGhktcPk",
"status": "AUTHENTICATION_PENDING",
"instrumentId": "instr_2134sdfjk340sdfjk23ksd",
"authenticationMethods": [
{
"type": "REDIRECT",
"details": {
"requestUrl": "https://either-bank-page-or-ppro-hpp.com",
"requestMethod": "GET"
}
}
]
}
Consumer Authentication
iDEAL requires authentication by the consumer, which they do via their bank's online environment. You will need to redirect their browser to this environment using the link provided in the requestUrl
field of the REDIRECT
authentication method response.
As mentioned above, if you do not specify a bank code in your initial request, the redirect URL will send them to PPRO's hosted page to choose their bank.
The payment charge will remain in the AUTHENTICATION_PENDING
state until the consumer logs into their bank and approves the payment. After this, the charge will transition to the CAPTURED
state.
Handling the Payment Result
The consumer will be redirected to the authenticationMethods.settings.returnUrl
provided in the initial payment charge creation request, depending on whether the authorization is a success, a failure, or if the user cancelled/aborted the flow.
If the consumer fails to authenticate the payment within the timeout window, the charge will transition to the DISCARDED
state.
You can receive webhooks for all changes to the payment charge state and use these to build business logic such as delivering the goods when the charge is CAPTURED
.
Recurring Payments
Since iDEAL currently does not offer native recurring payments, SEPA Direct Debits are used for all subsequent charges. You can set up iDEAL recurring payments easily using PPRO Payment Agreements.
When you offer iDEAL in the checkout for a recurring product, you should get explicit approval (mandate) from the consumer to have their account charged on a recurring basis via direct debit. SEPA Direct Debits have a chargeback risk, which can be reduced by being as transparent with the consumer as possible.
When the consumer selects iDEAL for their recurring payment and agrees to a direct debit mandate, you'll need to generate an ID for this mandate and store it in your system. This ID is then passed to PPRO when you create the payment agreement.
To set up a payment agreement for iDEAL, the consumer needs to authorise the first transaction. If you don't include an initialPaymentCharge
, the customer will be charged a small verification amount to create a link-only payment agreement. This amount would be automatically refunded by PPRO. To reduce friction, we advise that this amount and the fact that it'll be refunded is mentioned on the checkout.
Create the Payment Agreement
To set up a recurring agreement for iDEAL, you'll need to provide the following data when calling our /v1/payment-agreements API:
Data Field | Required | Description |
---|---|---|
paymentMethod | Y | IDEAL |
amount.value | Y | The amount of the recurring charge in the smallest units of the currency used. |
amount.currency | Y | EUR The currency used for the payment |
consumer.name | Y | Full name of the consumer |
consumer.country | Y | The country where the consumer is shopping |
instrument: BANK_ACCOUNT details.debitMandateId | Y | The ID of the direct debit mandate you have generated and stored in your system. |
authenticationSettings: REDIRECT settings.returnUrl | Y | Specify the URL that the consumer should be redirected back to after completing the payment |
instrument: BANK_ACCOUNT details.bankCode | Valid BIC. It can only contain 8 or 11 alphanumeric characters. Must be an iDEAL issuer’s BIC as listed above. | |
initiator | Required for payments initiated by a consumer. If not included, it's assumed the transaction is initiated by a merchant. | |
initialPaymentCharge: amount.value | The amount to be paid in the smallest units of the currency used. This is required if you want to immediately capture the charge. | |
initialPaymentCharge: amount.currency | EUR The currency used for the payment | |
webhooksUrl | You should include the endpoint URL where you want to receive webhooks for updates to the agreement and payment charges. |
You can also include the initialPaymentCharge object in this agreement creation call to immediately initiate the first payment without making a separate call. If you include this object, you'll need to specify the exact amount.value
and amount.currency
of the first payment.
If you don't include an initialPaymentCharge
during agreement creation, you'll need to make a separate API call to /v1/payment-agreements/{agreement_id}/payment-charges to create the first charge.
Request
POST /v1/payment-agreements
{
"paymentMethod":"IDEAL",
"amount":{
"value":1000,
"currency":"EUR"
},
"consumer":{
"name": "Connor Summer",
"country": "NL"
},
"instrument": {
"type": "BANK_ACCOUNT",
"details": {
"debitMandateId": "YOURGENERATEDMANDATEID",
"bankCode": "ABNANL2A" //optional
}
},
"authenticationSettings": [
{
"type": "REDIRECT",
"settings": {
"returnUrl": "https://example.com/order_details?order_id=12345"
}
}
],
"initialPaymentCharge": { //if first payment should be immediately captured
"amount": {
"value": 1000,
"currency": "EUR"
},
"paymentDescriptor": "PPRO - ORDER 1234" //optional
},
"webhooksUrl": "https://your-webhooks-endpoint/" //optional
}
Response
You'll receive a standard payment agreement response (see potential responses in the API Reference)
{
"id": "agrmt_X0O78tadFHrZCbGhktcPk",
"status": "AUTHENTICATION_PENDING",
"initialPaymentChargeId": "charge_DOS43DF023dka42kdTwGa", //if initialPaymentCharge was specified
"authenticationMethods": [
{
"type": "REDIRECT",
"details": {
"requestUrl": "https://either-bank-page-or-hpp.com",
"requestMethod": "GET"
}
}
]
}
Make Subsequent Recurring Charges
Once the first successful iDEAL payment has been made with a Payment Agreement, you can make subsequent recurring charges by calling POST /v1/payment-agreements/{agreement_id}/payment-charges
These subsequent charges are processed via SEPA Direct Debit and have a chargeback risk.
Updated 2 months ago