# Integrate iDEAL (Legacy)

Deprecation Notice

This version of the iDEAL integration is deprecated and and will no longer be supported after April 1, 2025.

To ensure continued functionality upgrade to the latest version of the integration.

The updated version ensures compliance with the latest iDEAL payment experience (opens new window) by redirecting payers to an iDEAL-hosted page for payment collection. We recommend upgrading as soon as possible to avoid any disruptions to your payment processing.

iDEAL (opens new window) is a payment method that enables customers to complete online payments using their bank credentials. It is a preferred online payment method in the Netherlands.

This tutorial guides you on using Chargebee.js to integrate iDEAL on your website, and creating a subscription after the user checks out.

Currently, Chargebee JS supports the below payment options for iDEAL:

Stripe
Adyen
Mollie

# Gateway prerequisites

The following is the list of requirements to fulfill before starting the integration steps.

Enable the payment gateway of your choice:

Configure Smart routing (opens new window) to select iDEAL for EUR currency.

# Setting up Chargebee JS

# Inserting chargebee.js script in your application

Include the following script in your HTML page. You need to do this only once per page.

<script src="https://js.chargebee.com/v2/chargebee.js"></script>

# Initializing a Chargebee instance

Inside your JavaScript code, initialize chargebee with the publishable key (opens new window) once the page is loaded and get 'chargebee instance' object. This object is used further to create components.

Example:

var cbInstance = Chargebee.init({
	site: "site-name", // your test site
	domain: "https://mybilling.acme.com" // this is an optional parameter.
    publishableKey: "test__"
})

1
2
3
4
5

Learn more about initializing a Chargebee instance.

# Create a Payment Intent

You should create a payment intent before submitting the form to authorize the payments.

payment_intent performs the essential function of tracking different events involved in a transaction. This includes:

Automatically changing its status based on the outcome of authorization and capture events.
Automatically refunding in case of an error post-payment.

A payment_intent can be created at your server-side using create a payment intent API (opens new window) and returned to the client side. The payment method handler uses the created payment_intent internally to perform authorization.

Here's the sample code to create a payment_intent.

TIP

This must be done from your backend to avoid exposing sensitive data.

Example:

Curl

The above step should be initiated as a request from your front end.

Front end code:

function createPaymentIntent() {
  return fetch('/payment-intents', {
    method: 'POST',
    body: JSON.stringify({
      amount: 500,
      currency_code: 'EUR',
      payment_method_type: 'ideal'
    })
  }).then(function(response) {
    return response.json();
  }).then(function(responseJson) {
    return responseJson.payment_intent;
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Authorize payment intent

Follow the step below to integrate iDEAL into your website.

# 1. Create a container in DOM to load the iDEAL component

Create a DOM container to hold and display the iDEAL bank selector component.

<div id='ideal-container'></div>

# 2. Set up iDEAL

Set up iDEAL using the steps below:

# a. Load iDEAL integration.

load iDEAL integration using cbInstance.load('ideal').

# b. Mount iDEAL component

Note: When using Adyen, Stripe or your own components, you need to replace this step with code needed to get the bank ID and pass it as the paymentInfo parameter to handlePayment in the next step.

Assign the ID of the DOM container to the mountBankList function. This attaches a drop-down list of supported banks to that DOM node. Chargebee validates whether a bank is selected before initiating the transaction.

# Handle Payment

Use ideal as the input parameter to handlePayment function, as this enables the function to handle iDEAL payments.

Chargebee takes care of redirecting users to the page meant for payment authorization.

Note:

Currently, Chargebee JS does not support payments via in-app browsers of Instagram, Facebook and Snapchat.

Sample code:

cbInstance.handlePayment('ideal', {
  paymentIntent: () => {
    return createPaymentIntent()
  },
  paymentInfo: {
    issuerBank: selectedBank_id
  }
}).then(intent => {
  // SUCCESS!!! payment_intent is authorised.
  var response = fetch('/subscriptions', {
    method: 'POST',
    body: JSON.stringify({
      paymentIntentId: intent.id,
      plan_id: 'pro_plan',
      plan_quantity: 1,
      billingAddress: {...}, // provide billing address
      customer: {...} // provide customer details if the subscription is to be created for an existing <code>customer</code> in Chargebee.
    })
  }).then(function(response) {
    return response.json();
  });
}).catch(err => {
  // OOPS!!! payment_intent is not authorised.
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

On successful authorization, the payment_intent turns authorized and the user is redirected back to your website.

Learn more about the additional functions for iDEAL.

Using webhooks

Use webhooks (opens new window) for production use, instead of making the subscription creation request from the client-side, it's more secure and reliable to respond to webhooks from Chargebee on the server-side. Listen to the payment_intent_updated (opens new window) event via webhooks and create the subscription when the payment_intent.status (opens new window) is authorized.

# Create a subscription

Pass the ID of the successfully authorized payment_intent to Chargebee’s create a subscription API (opens new window).

Curl

← Integrate iDEAL Integrate Giropay →