iDEAL UI

Implement the iDEAL UI on your website.

Introduction

This guide will show you how to integrate iDEAL payments on your website. We recommend you read the web integration walkthrough first, before jumping into the guide.

iDEAL is an easy to use, realtime payment method from the Netherlands, which allows you to execute secure online payments directly between bank accounts.

Step 1: Setup

First, you need to include Unzer’s script and stylesheet on your website. They must always be loaded directly from https://static.unzer.com:

<link rel="stylesheet" href="https://static.unzer.com/v1/heidelpay.css" />
<script type="text/javascript" src="https://static.unzer.com/v1/heidelpay.js"></script>
Good practice
Even though it’s not mandatory in html, it’s considered good practice to place scripts at the bottom of your HTML document. This way your website will display and load faster.

Next, create a Unzer instance with your public key:

// Creating an Unzer instance with your public key
var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');
Showcase keys
In the example above, we’ve used a random API key for showcase purposes. For production usage you should replace it with your personal public key.

If you don’t have a public and private key yet, you can get them by sending an e-mail to our support.

Additionally we support localization, in case you want your form to be be in a specific language.

Step 2: Create your form

Creating the payment form for iDEAL is easy and straightforward. You just need to define a new HMTL-form, as shown in web Integration. But remember: The ID’s have to be unique!

Simply copy the code below into your HTML file:

<form id="payment-form">
  <div id="ideal-element"></div>
  <button type="submit">Pay</button>
</form>
Importance of Unzer classes
In case you need to structure your HTML in a slightly different way than suggested above, or pass additional custom classes of your own, it is still crucial to add appropriate Unzer classes.

For the example above, in case you place your form element elsewhere, and put the ideal div and button inside another container element (most probably a div), you will still need to add class=\"heidelpayUI form\" to this container. This is required so the entire iDEAL component is rendered properly.

Step 3: Create your payment method

After you’ve established your payment form with the necessary DOM elements, it’s time to create the payment method. In this case iDEAL.

Simply copy the example down below into your code:

// Creating an iDEAL instance
var Ideal = heidelpayInstance.Ideal()
// Rendering input field
Ideal.create('ideal', {
  containerId: 'ideal-element'
});

As you can see, creating an iDEAL instance works just like any other payment method.

Step 4: Create your resource ID and submit it to your server

Finally, the last step in the integration guide is handling the form’s submission, like so:

// Handling payment form's submission.
var form = document.getElementById('payment-form');
form.addEventListener('submit', function(event) {
  event.preventDefault();
  Ideal.createResource()
    .then(function(data) {
      // Success
    })
    .catch(function(error) {
      // Error
    });
});

And that’s it! You’ve successfully integrated iDEAL payments!

Final code review

Here you can find the entire code necessary for iDEAL integration:

<form id="payment-form">
  <div id="ideal-element"></div>
  <button type="submit">Pay</button>
</form>
// Creating an Unzer instance with your public key
var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');
// Creating an iDEAL instance
var Ideal = heidelpayInstance.Ideal()
// Rendering input field
Ideal.create('ideal', {
  containerId: 'ideal-element'
});
// Handling payment form's submission.
var form = document.getElementById('payment-form');
form.addEventListener('submit', function(event) {
  event.preventDefault();
  Ideal.createResource()
    .then(function(data) {
      // Success
    })
    .catch(function(error) {
      // Error
    });
});

Updating iDEAL

You can also choose to update the value of already created iDEAL resource. The updating process is almost identical to creating a new iDEAL resource. The main difference is that you will need to pass the resourceId when calling the create() method, and finally running the updateResource() instead of the createResource() method. The complete process is explained in the code box below (note that HTML will be the same as when following the createResouce() process).

// iDEAL JavaScript (updateResource)
// Creating an Unzer instance with your public key
var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');
// Creating an iDEAL instance
var Ideal = heidelpayInstance.Ideal()
// Rendering input field
Ideal.create('ideal', {
  containerId: 'ideal-element',
  resourceId: 's-idl-resourceid' // ID of the resource you want to update
});
// Handling payment form's submission.
var form = document.getElementById('payment-form');
form.addEventListener('submit', function(event) {
  event.preventDefault();
  Ideal.updateResource()
    .then(function(data) {
      // Success
    })
    .catch(function(error) {
      // Error
    });
});

References

Constructors

Constructor Description
heidelpay.Ideal() Initializes the iDEAL object.

Method summary

Type Method Description
void create(String type, Object options) Creates the specified input fields and mounts them onto the declared DOM element.
Promise createResource() Creates a promise object for input validation. Either gets resolved (validation passed) or rejected (validation didn’t pass).
Promise updateResource() Creates a promise object for input validation. Either gets resolved (validation passed) or rejected (validation didn’t pass).

create

Method

void create(String type, Object options)

Description

Creates an input field for the iDEAL payment method specified by the type parameter.

Properties

Type Property Description
String type Specifies the type of input field to be created.
Valid values for iDEAL: ideal
Object options A JSON with various options for the created input field.

options

Type Property Description
String containerId The HTML id of the DOM element, where the UI component will be inserted.
Example:
containerId: 'card-element-id-number'
String resourceId The id of the created resource you wish to update. It is required to be passed before using updateResource method.

createResource

Method

Object createResource()

Description

Creates a promise and submits the form’s data. A /types/ideal is created and either resolved or rejected. In both cases an object is returned.

Returns

An object with the following structure:

  • Success: {id: String, method: String, bic: String, recurring: Boolean}
  • Error: {}
Type Property Description
String id The returned /types/ideal resource ID.
String method The chosen method.
String bic The specified BIC.
Boolean recurring States whether the payment method is recurring.

updateResource

Method

Object updateResource()

Description

Creates a promise and submits the form’s new data. If resolved, the old BIC data will be updated.

Returns

An object with the following structure:

  • Success: {id: String, method: String, bic: String, recurring: Boolean}
  • Error: {}
Type Property Description
String id The returned /types/ideal resource ID. This value will not change after updating the resource.
String method The chosen method. This value will not change after updating the resource.
String bic The specified BIC.
Boolean recurring States whether the payment method is recurring. This value will not change after updating the resource.