iDEAL

iDEAL is the most popular method for online payments in the Netherlands.

About iDEAL

The iDeal payment method is only available in the Netherlands where the customer logs in to their bank account and directly pays you. So, the money is reflected immediately on your bank account. It is a safe and secure payment method because the customer completes the transaction in their banking enviornment.

The banks that participate in the iDeal payment workflow have a Bank Identification Code (BIC) assigned to them. The BIC is an alphanumeric value that is usually sent with the payment. Note that this is not a mandatory field and you do not need to specify this when making a payment. Following is a list of different banks and their BIC codes.

Bank name BIC value
ABN AMRO ABN_AMRO
ASN Bank ASN_BANK
BUNQ BUNQNL2A
ING ING
Knab Bank KNAB_BANK
Rabo Bank RABOBANK
Regio Bank SNS_REGIO_BANK
SNS Bank SNS_BANK
Tridos Bank TRIODOS_BANK
Van Lanschot Bankiers VAN_LANSCHOT_BANKIERS

Accept an iDEAL payment

To accept an iDEAL payment, follow the steps below.

When testing, do not use real customer data. Use the iDEAL test data prepared by Unzer.

Step 1: Create an ideal resource

To start an iDEAL transaction, first create an ideal resource.

Make a POST call to types/ideal, with the following parameters in the request body:

Parameter Required Type Default Description Example
bic Optional String / The Bank Identification code used for identifying the customer’s bank. RABONL2U
POST: https://api.unzer.com/v1/types/ideal/
Body:
{
  "bic" : "INGBNL2A"
}
{
    "id": "s-idl-obig4czju5hc",
    "method": "ideal",
    "recurring": false,
    "geoLocation": {
        "clientIp": "127.0.0.1",
        "countryIsoA2": "NL"
    },
    "bic": "INGBNL2A"
}
Property Type Description
id String The ID of the ideal resource that you just created.
method String The payment method.
recurring Boolean Indicates if this is a recurring payment.
clientIp String The current IP address of the device that the customer used for the payment.
countryCode String The country associated with clientIp, displayed in the ISO 3166-1 alpha-2 format.
bic String The Bank Identification code used for identifying the customer’s bank.

Step 2: Make a charges call

Make a payments/charges POST call with the following parameters in the request body:

Parameter Required Type Default Description Example
amount Yes Number / The transaction amount. 20.0000
currency Yes String / The transaction currency, in the ISO 4217 alpha-3 format. EUR
returnURL Yes String / The URL to redirect the customer to after the payment is completed. https://www.unzer.com
typeId Yes String / The id of the related ideal resource. s-idl-shgzitf5indu
POST: https://api.unzer.com/v1/payments/charges

{
  "amount" : "20",
  "currency": "EUR",
    "returnUrl": "https://unzer.com",
  "resources" : {
    "customerId" : "",
    "typeId" : "{{payment_method_id}}"
  }
}
{
    "id": "s-chg-1",
    "isSuccess": false,
    "isPending": true,
    "isError": false,
    "redirectUrl": "https://payment.unzer.com/v1/redirect/ideal/s-f5QpxjetXBOm",
    "message": {
        "code": "COR.000.100.112",
        "merchant": "Request successfully processed in 'Merchant in Connector Test Mode'",
        "customer": "Your payments have been successfully processed in sandbox mode."
    },
    "amount": "20.0000",
    "currency": "EUR",
    "returnUrl": "https://unzer.com",
    "date": "2021-03-08 14:34:13",
    "resources": {
        "customerId": "",
        "paymentId": "s-pay-123665",
        "traceId": "68fd0ae147ff64440b1f2226643887a6",
        "typeId": "s-idl-obig4czju5hc"
    },
    "paymentReference": "",
    "processing": {
        "uniqueId": "31HA07BC81037EBF932EA9FED4DB2DBA",
        "shortId": "4791.4045.2581",
        "traceId": "68fd0ae147ff64440b1f2226643887a6"
    }
}
Property Type Description
id String The transaction’s unique ID.
isSuccess Boolean Set to true if the transaction was successful.
isPending Boolean Set to true if the transaction is pending
(e.g. if a redirect to an external system is required).
isError Boolean Set to true if an error occurs.
redirectUrl String The URL where the customer completes the payment.

Step 3: Forward the customer to the redirect URL

After you charge the ideal resource, implement the following flow:

  1. Redirect the customer to the redirectURL.
  2. The customer is forwarded to the iDEAL payment page.
  3. After a successful payment, the customer is redirected to the returnURL that you specified in the charges call (Step 2).

Step 4: Check the payment status

After the customer is redirected to the returnUrl, check the status of the payment.

Make a GET call with the following parameters in the request path:

Parameter Required Type Default Description Example
resource_ID Yes String / The returned ID of the ideal resource that you created in Step 1. s-idl-shgzitf5indu
transaction_ID Yes String / The transaction’s unique ID that you received in Step 2. s-chg-1
GET https://api.unzer.com/v1/payments/{resource_ID}>/charges/{transaction_ID}
{
    "id": "s-pay-123665",
    "state": {
        "id": 1,
        "name": "completed"
    },
    "amount": {
        "total": "20.0000",
        "charged": "20.0000",
        "canceled": "0.0000",
        "remaining": "0.0000"
    },
    "currency": "EUR",
    "orderId": "",
    "invoiceId": "",
    "resources": {
        ...
    },
    "transactions": [
        {
            "date": "2021-03-08 14:34:13",
            "type": "charge",
            "status": "success",
            "url": "https://api.unzer.com/v1/payments/s-pay-123665/charges/s-chg-1",
            "amount": "20.0000"
        }
    ]
}
Property Type Description
id String The transaction’s unique ID.
isSuccess Boolean Set to true if the transaction was successful.
isPending Boolean Set to true if the transaction is pending
(e.g. if a redirect to an external system is required).
isError Boolean Set to true if an error occurs.
redirectUrl String The URL to which the customer gets redirected after the payment.

Implement the iDEAL UI on your website

To integrate iDEAL into your website, implement our ready-made UI components.

Web integration
Before implementing the iDEAL UI on your website, read the web integration topic.

Step 1: Load our JS script and CSS stylesheet

Include Unzer’s script and stylesheet on your website.

Always load the script and stylesheet 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>
Faster load time
To make your website load faster, insert the script at the bottom of your HTML document.

Step 2: Create a heidelpayInstance

Create a heidelpayInstance with your public key:

var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');

Step 3: Create your HTML form

Create an HTML form, into which the iDEAL UI will be inserted:

<form id="payment-form" class="unzerUI form">
  <div id="ideal-element"></div>
  <button type="submit">Pay</button>
</form>
Localization
We support localization. You can create your HTML form in different languages.

Step 3: Create a new iDEAL resource

To create a new iDEAL instance, call the unzerInstance.Ideal() method:

// Creating an iDEAL instance
var Ideal = unzerInstance.Ideal()
// Rendering input field
Ideal.create('ideal', {
  containerId: 'ideal-element'
});
The IDs must match
Make sure that the IDs in your HTML and JavaScript files match. For more information on how to create your HTML form correctly, go to web integration.

Step 4: Add an event listener and submit the form

Now get the HTML form by its unique ID and add an event listener.

Inside, create a Promise on the ideal object. The Promise gets either resolved or rejected:

// 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
    });
});

Step 5: Review the code

View the complete code samples that you can use to implement the iDEAL UI on your website.

<form id="payment-form">
  <div id="ideal-element"></div>
  <button type="submit">Pay</button>
</form>
// Creating a unzer instance with your public key
var unzerInstance = new unzer('s-pub-xxxxxxxxxx');
// Creating an iDEAL instance
var Ideal = unzerInstance.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
    });
});

Optional: Update an iDEAL resource

You can update the value of an existing iDEAL resource. The update process is very similar to creating a new iDEAL resource, with the following differences:

  • You need to pass the resourceId when calling create().
  • At the end, you need to run updateResource() instead of createResource().

The HTML is the same as in Step 2.

// iDEAL JavaScript (updateResource)
// Creating a unzer instance with your public key
var unzerInstance = new unzer('s-pub-xxxxxxxxxx');
// Creating an iDEAL instance
var Ideal = unzerInstance.Ideal()
// Rendering input field
Ideal.create('ideal', {
  containerId: 'ideal-element',
  resourceId: 's-idl-resourceid' // ID of the resource that 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
    });
});

UI reference

Constructors

Constructor Description
unzer.Ideal() Initializes the Ideal object.

Methods

Method Type Description Returns
create(type, options) Promise Creates an input field for the Unzer Direct Debit payment method
specified by the type parameter.
You can also pass different options as key-value pairs
inside the options parameter.
An object containing success or error details.
createResource() Promise Creates a Promise object for input validation.
Either gets resolved (validation passed) or rejected (validation didn’t pass).
An object containing success or error details.

Success:
{id: String,
method: String,
iban: String}

Error:
{input: String,
message: String}
updateResource() Promise Creates a Promise and submits the new data from the form.
If resolved, the old IBAN data is updated.
An object containing success or error details.

Success:
{id: String,
method: String,
iban: String}

Error:
{input: String,
message: String}
create properties
Property Type Description
type String Specifies the type of input field to be created.

Valid value: ideal
options Object A JSON with various options for the created input field.
containerId String The HTML id of the DOM element, where the UI component will be inserted.
Example:
containerId: 'card-element-id-number'
resourceId String The id of the created resource you wish to update.

You need to pass the resourceId before before using the updateResource method.
createResource response properties
Property Type Description
id String The ID of the returned /types/ideal resource.
method String The chosen payment method.
bic String The customer BIC.
recurring Boolean Indicates if this is a recurring payment.
updateResource response properties
Property Type Description
id String The ID of the returned /types/ideal resource.
method String The chosen payment method.
bic String The customer BIC.
recurring Boolean Indicates if this is a recurring payment.