iDEAL

REST API

iDEAL is a type of Online Bank Transfer.

Countries and Currencies

Countries

Netherlands

Currencies

EUR

Communication Formats

This table illustrates how iDEAL notifications are encoded and which formats and methods can be used for requests and responses.

Requests/Responses

Format

XML

Methods

POST

IPN Encodement

A signed XML document

Transaction Types

For transaction type details which are not given here, look at Transaction Types.

Transaction Type Description Link to samples

get-url

A transaction for initiating an iDEAL payment. As long as there is no notification from iDEAL there is only a get-url transaction.

See sample

debit

Transfer funds from the Account Holder to the Merchant. The debit will be created when notification for the transaction is received from IDEAL.

See sample

Reference Transaction
For additional information regarding the referenced transaction functionality, see Cross-Payment-Methods Referencing.
Test Credentials

URL (Endpoint)

For transaction type get-url.

https://api-test.getneteurope.com/engine/rest/paymentmethods/

Merchant Account ID (MAID)

76977f95-d929-4870-acee-4ef89fd200cd

Username

515225-GetnetEuropeTEST

Password

4cHLRE-Q7YcAP

Secret Key

01ab26af-d5c7-46f8-b5dd-8a1516c3e85c

Workflow
debit
The merchant sends a debit request to Getnet and receives a response which contains the URL of the consumers online banking system to which the consumer must be redirected to. The consumer is redirected back to merchants shop after the transaction is approved and the merchant receives a payment notification from Getnet.
image
  1. Consumer adds items to his/her shopping basket.

  2. Consumer selects iDEAL.

  3. The merchant sends a get-url request to Payment Gateway.

  4. Payment Gateway processes and validates the transaction.

  5. Payment Gateway forwards the request to iDEAL.

  6. iDEAL provides the URL of the consumer’s online banking account for payment verification.

  7. Payment Gateway processes the response.

  8. Payment Gateway redirects the consumer to the provided online banking URL.

  9. Consumer verifies the payment within the personal online banking system.

  10. iDEAL transfers funds from the consumer’s bank account to the merchant’s bank account.

  11. iDEAL redirects consumer to the merchant’s result page.

  12. iDEAL sends the transaction Status to Payment Gateway (Payment Gateway continuously queries for the payment status).

  13. Payment Gateway processes the notification and sends the payment debit notification to the merchant.

  14. The merchant receives the notification with the payment result.

Fields

The fields used for iDEAL requests, responses and notifications are the same as the ReST API Fields. Please refer to the REST API field list. Only the fields listed below have different properties.

The following elements are mandatory (M) or optional (O) for a request/response/notification. If the respective cell is empty, the field is disregarded or not sent.

Field Request Response Notification Data Type Size Description

bank-account.bic

M

M

xs:string

11

This is the BIC of the end-consumer. It can’t be used together with account-number/bank-code.

order-number

O

O

O

xs:string

35

This is the order number of the merchant. The following characters are allowed: a-z A-Z 0-9 +

descriptor

O

O

O

xs:string

35

Description on the settlement of the account holder’s account about a transaction. The following characters are allowed: umlaut space 0-9 a-z A-Z ' + , - .

success-redirect-url

M

M

M

xs:string

512

The URL to which the consumer will be re-directed after a successful payment. This is normally a success confirmation page on the merchant’s website.

Participating Banks

BIC

Name

ABNANL2A

ABN Amro Bank

ASNBNL21

ASN Bank

BUNQNL2A

bunq

INGBNL2A

ING

KNABNL2H

Knab

MOYONL21

Moneyou

NTSBDEB1

N26

NNBANL2G

Nationale Nederlanden (NN)

RABONL2U

Rabobank

RGGINL21

Regio Bank

REVOLT21

Revolut Bank

SNSBNL2A

SNS Bank

TRIONL2U

Triodos Bank

FVLBNL22

Van Lanschot Kempen

BITSNL2A

Yoursafe B.V.

Frieslandbank merged into Rabobank. They are now available as Rabobank.

Only the following banks can be used on http://api-test.getneteurope.com and iDEAL sandbox:

  • RABONL2U (Rabobank)

  • INGBNL2A (ING)

Samples
XML Get-URL Request (Successful)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>76977f95-d929-4870-acee-4ef89fd200cd</merchant-account-id>
    <request-id>03cfdf09-86eb-4956-945e-da9ba61d8052</request-id>
    <transaction-type>get-url</transaction-type>
    <requested-amount currency="EUR">1.23</requested-amount>
    <order-number>180516095533783</order-number>
    <descriptor>customer-statement</descriptor>
    <payment-methods>
        <payment-method name="ideal" />
    </payment-methods>
    <bank-account>
        <bic>INGBNL2A</bic>
    </bank-account>
    <success-redirect-url>http://someshop.com/success.html</success-redirect-url>
    <locale>de</locale>
</payment>
XML Get-URL Response (Successful)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
 <merchant-account-id>76977f95-d929-4870-acee-4ef89fd200cd</merchant-account-id>
 <transaction-id>67bea562-baa8-40fb-8ac2-cd84d1b2840c</transaction-id>
 <request-id>03cfdf09-86eb-4956-945e-da9ba61d8052</request-id>
 <transaction-type>get-url</transaction-type>
 <transaction-state>success</transaction-state>
 <completion-time-stamp>2018-05-16T07:55:34.000Z</completion-time-stamp>
 <statuses>
  <status code="201.0000" description="The resource was successfully created." severity="information" />
 </statuses>
 <requested-amount currency="EUR">1.23</requested-amount>
 <order-number>180516095533783</order-number>
 <descriptor>customer-statement</descriptor>
 <payment-methods>
  <payment-method url="https://idealtest.secure-ing.com/ideal/issuerSim.do?trxid=0050000172511748&amp;ideal=prob" name="ideal" />
 </payment-methods>
 <bank-account>
  <bic>INGBNL2A</bic>
 </bank-account>
 <success-redirect-url>http://someshop.com/success.html</success-redirect-url>
 <locale>de</locale>
</payment>
XML Debit Notification (Successful)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction" self="https://api-test.getneteurope.com:443/engine/rest/merchants/4aeccf39-0d47-47f6-a399-c05c1f2fc819/payments/404894a2-fe56-4b79-8453-2935f78c0a6d">
 <merchant-account-id ref="https://api-test.getneteurope.com:443/engine/rest/config/merchants/76977f95-d929-4870-acee-4ef89fd200cd">76977f95-d929-4870-acee-4ef89fd200cd</merchant-account-id>
 <transaction-id>404894a2-fe56-4b79-8453-2935f78c0a6d</transaction-id>
 <request-id>03cfdf09-86eb-4956-945e-da9ba61d8052</request-id>
 <transaction-type>debit</transaction-type>
 <transaction-state>success</transaction-state>
 <completion-time-stamp>2018-05-16T08:01:55.000Z</completion-time-stamp>
 <statuses>
  <status code="201.1126" description="Successful confirmation received from the bank." severity="information" />
 </statuses>
 <requested-amount currency="EUR">1.230000</requested-amount>
 <parent-transaction-id>67bea562-baa8-40fb-8ac2-cd84d1b2840c</parent-transaction-id>
 <account-holder>
  <first-name>Hr</first-name>
  <last-name>E G H Küppers en/of MW M.J. Küpp</last-name>
 </account-holder>
 <order-number>180516095533783</order-number>
 <descriptor>customer-statement</descriptor>
 <payment-methods>
  <payment-method name="ideal" />
 </payment-methods>
 <bank-account>
  <iban>NL53INGB0654422370</iban>
  <bic>INGBNL2A</bic>
 </bank-account>
 <api-id>---</api-id>
 <success-redirect-url>http://someshop.com/success.html</success-redirect-url>
 <locale>de</locale>
</payment>
XML Get-URL Request (Failure)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>76977f95-d929-4870-acee-4ef89fd200cd</merchant-account-id>
    <request-id>e530a6ca-fb93-4049-9c88-a8d6b9645f4b</request-id>
    <transaction-type>get-url</transaction-type>
    <requested-amount currency="EUR"/>
    <order-number>180516100904530</order-number>
    <descriptor>customer-statement</descriptor>
    <payment-methods>
        <payment-method name="ideal" />
    </payment-methods>
    <bank-account>
        <bic>INGBNL2A</bic>
    </bank-account>
    <success-redirect-url>http://someshop.com/success.html</success-redirect-url>
    <locale>de</locale>
</payment>
XML Get-URL Response (Failure)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
 <merchant-account-id>76977f95-d929-4870-acee-4ef89fd200cd</merchant-account-id>
 <transaction-id>40f59357-21e6-4ef8-81e8-9e6cea6b37d6</transaction-id>
 <request-id>e530a6ca-fb93-4049-9c88-a8d6b9645f4b</request-id>
 <transaction-type>get-url</transaction-type>
 <transaction-state>failed</transaction-state>
 <completion-time-stamp>2018-05-16T08:09:04.000Z</completion-time-stamp>
 <statuses>
  <status code="400.1011" description="The Requested Amount has not been provided.  Please check your input and try again." severity="error" />
 </statuses>
 <requested-amount currency="EUR" />
 <order-number>180516100904530</order-number>
 <descriptor>customer-statement</descriptor>
 <payment-methods>
  <payment-method name="ideal" />
 </payment-methods>
 <bank-account>
  <bic>INGBNL2A</bic>
 </bank-account>
 <success-redirect-url>http://someshop.com/success.html</success-redirect-url>
 <locale>de</locale>
</payment>
XML Debit Notification (Failure)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction" self="https://api-test.getneteurope.com:443/engine/rest/merchants/4aeccf39-0d47-47f6-a399-c05c1f2fc819/payments/40f59357-21e6-4ef8-81e8-9e6cea6b37d6">
  <merchant-account-id ref="https://api-test.getneteurope.com:443/engine/rest/config/merchants/76977f95-d929-4870-acee-4ef89fd200cd">76977f95-d929-4870-acee-4ef89fd200cd</merchant-account-id>
  <transaction-id>40f59357-21e6-4ef8-81e8-9e6cea6b37d6</transaction-id>
  <request-id>e530a6ca-fb93-4049-9c88-a8d6b9645f4b-get-url</request-id>
  <transaction-type>get-url</transaction-type>
  <transaction-state>failed</transaction-state>
  <statuses>
    <status code="400.1011" description="The Requested Amount has not been provided.  Please check your input and try again." severity="error" />
  </statuses>
  <requested-amount currency="EUR" />
  <parent-transaction-id>40f59357-21e6-4ef8-81e8-9e6cea6b37d6</parent-transaction-id>
  <order-number>180516100904530</order-number>
  <descriptor>customer-statement</descriptor>
  <payment-methods>
    <payment-method name="ideal" />
  </payment-methods>
  <bank-account>
    <bic>INGBNL2A</bic>
  </bank-account>
  <api-id>---</api-id>
  <success-redirect-url>http://someshop.com/success.html</success-redirect-url>
  <locale>de</locale>
</payment>

Payment Page

General Information

This is a reference page for iDEAL. Here you find all the information necessary for integrating this payment method into your Hosted and Embedded Payment Page.

Are you unfamiliar with Payment Page (Payment Page)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

All Payment Page integrations share a common process flow for creating payments.

Below, you find example requests for the available transaction type debit, including field lists with short descriptions.

These requests are designed for the testing environment and do not use real information.

For production, you need to use production credentials. For details contact merchant support.

All given requests return successful responses.

For more details on the redirect-url, see the Configuring Redirects and IPNs for Payment Page section.

For response verification examples, see the Payment Page Security section.

About iDEAL

iDEAL is an e-commerce payment method widely used in the Netherlands. Introduced in 2005, this payment method allows consumers to buy on the Internet using direct online transfers from their bank account. iDEAL works together with leading Dutch banks using their online banking systems to carry out payment transactions.

Participating Banks

BIC

Name

ABNANL2A

ABN Amro Bank

ASNBNL21

ASN Bank

BUNQNL2A

bunq

INGBNL2A

ING

KNABNL2H

Knab

MOYONL21

Moneyou

NTSBDEB1

N26

NNBANL2G

Nationale Nederlanden (NN)

RABONL2U

Rabobank

RGGINL21

Regio Bank

REVOLT21

Revolut Bank

SNSBNL2A

SNS Bank

TRIONL2U

Triodos Bank

FVLBNL22

Van Lanschot Kempen

BITSNL2A

Yoursafe B.V.

Test Credentials

Test Credentials for Transaction Type debit.

URLI (Endpoint)

https://paymentpage-test.getneteurope.com/api/payment/register

Merchant Account ID (MAID)

76977f95-d929-4870-acee-4ef89fd200cd

Username

515225-GetnetEuropeTEST

Password

4cHLRE-Q7YcAP

Secret Key (used for response verification)

01ab26af-d5c7-46f8-b5dd-8a1516c3e85c

Test banks for iDEAL Sandbox

Bank

BIC

Rabobank

RABONL2U

ING

INGBNL2A

At the moment, only Rabobank (RABONL2U) and ING (INGBNL2A) are available for testing purposes. Choosing any other bank from the selection on the payment or sending its BIC in the request triggers payment failure.

image
Transaction Type debit

A debit transaction charges the specified amount from the account holder’s bank account and marks it for immediate transfer.

For a successful debit transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

  3. Highly recommended: Parse and process the payment response.

We provide ready-made JSON examples for each step of this process. You can find them below.

Endpoint for iDEAL payments.

Initial Request

The initial request creates the payment session. If it’s successful, you receive a URL as a response which redirects to the payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg=

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API iDEAL specification.

For a full structure of a request (optional fields included), see the JSON Field Reference section at the bottom.

1. Create a Payment Session (Initial Request)
{
    "payment": {
        "merchant-account-id": {
        "value": "76977f95-d929-4870-acee-4ef89fd200cd"
        },
        "request-id": "{{$guid}}",
        "transaction-type": "debit",
        "requested-amount": {
            "currency": "EUR",
            "value": "1.23"
        },
        "payment-methods": {
            "payment-method": [
                {
                "name": "ideal"
                }
            ]
        }
    }
}
Field (JSON) Data Type Cardinality Size Description

merchant-account-id

value

String

Mandatory

36

A unique identifier assigned to every merchant account (by Getnet).

request-id

String

Mandatory

150

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later. {{$guid}} serves as a placeholder for a random request-id.

Allowed characters: [a-z0-9-_]

transaction-type

String

Mandatory

n/a

The requested transaction type. For iDEAL payments, the transaction-type must be set to debit.

requested-amount

value

Numeric

Mandatory

18.2

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

currency

String

Mandatory

3

The currency of the requested/contested transaction amount. For iDEAL payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

payment-methods

payment-method

name

String

Mandatory

15

The name of the payment method used. Set this value to iDEAL.

2. Redirect the Consumer to the Payment Page (Initial Response URL)
{
"payment-redirect-url" : "https://paymentpage-test.getneteurope.com/?wPaymentToken=<DYNAMIC_TOKEN>"
}
Field (JSON) Data Type Description

payment-redirect-url

String

The URL which redirects to the payment form. Sent as a response to the initial request.

At this point, you need to redirect your consumer to payment-redirect-url (or render it in an iframe depending on your integration method).

Consumers are redirected to the payment form. There they enter their data and submit the form to confirm the payment. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (transaction-state: failed).

The transaction result is the value of transaction-state in the payment response. More details (including the status code) can also be found in the payment response in the statuses object. Canceled payments are returned as failed, but the status description indicates it was canceled.

In any case (unless the consumer cancels the transaction on a 3rd party provider page), a base64 encoded response containing payment information is sent to the configured redirection URL. See Configuring Redirects and IPNs for Payment Page for more details on redirection targets after payment & transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
  "api-id" : "up3-wpp",
  "parent-transaction-id" : "335da412-98ba-446d-a936-52b53f195e6c",
  "payment-methods" : {
    "payment-method" : [ {
      "name" : "ideal"
    } ]
  },
  "request-id" : "edcdefd8-ba6b-4987-a02c-112ecb3c67a5",
  "merchant-account-id" : {
    "value" : "76977f95-d929-4870-acee-4ef89fd200cd"
  },
  "transaction-state" : "success",
  "account-holder" : {
    "first-name" : "Hr",
    "last-name" : "E G H Küppers en/of MW M.J. Küpp"
  },
  "bank-account" : {
    "iban" : "NL53INGB0654422370",
    "bic" : "INGBNL2A"
  },
  "transaction-type" : "debit",
  "transaction-id" : "cac570c9-d2a3-4b43-ac14-ca9e72b60c8c",
  "completion-time-stamp" : "2018-03-23T10:41:34",
  "requested-amount" : {
    "currency" : "EUR",
    "value" : 1.230000
  },
  "statuses" : {
    "status" : [ {
      "severity" : "information",
      "code" : "201.1126",
      "description" : "Successful confirmation received from the bank."
    } ]
  }
}
Field (JSON) Data Type Description

api-id

String

Identifier of the currently used API.

parent-transaction-id

String

The ID of the transaction being referenced as a parent.

payment-method

name

String

The name of the payment method used.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

merchant-account-id

value

String

A unique identifier assigned to every merchant account (by Getnet).

transaction-state

String

The current transaction state.

Possible values:

  • in-progress

  • success

  • failed

Typically, a transaction starts with state in-progress and finishes with state either success or failed. This information is returned in the response only.

account-holder

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

bank-account

iban

String

The international bank account number (IBAN) of the account holder.

bic

String

The bank identifier code (BIC) of the account holder.

transaction-type

String

The requested transaction type.

transaction-id

String

A unique identifier assigned to every transaction (by Getnet). Used when searching for or referencing to it later.

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount. For iDEAL payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction. 2 decimals allowed.

statuses

status

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

description

String

The description of the transaction status message.

Post-Processing Operations

Payment Page is best used to deal with one-off payments (e.g. regular, independent debit transactions) or the initial transaction in a chain of them (e.g. a first authorization in a chain of recurring transactions). However, when it comes to referencing a transaction for any kind of post-processing operation — such as a refund of one of your debit transactions — use our REST API directly.

A direct refund through Payment Page is not possible for iDEAL so you have to obtain your consumer’s banking information and send the refund using SEPA Credit Transfer.
Check the REST API SEPA Credit Transfer specification for details on iDEAL specific post-processing operations.
JSON Field Reference

Here you can see the structure of a full request (optional fields included).

JSON Structure for iDEAL Requests
{
    "payment": {
        "merchant-account-id": {
        "value": "string"
        },
        "request-id": "string",
        "transaction-type": "string",
        "requested-amount": {
            "currency": "string",
            "value": "0"
        },
        "payment-methods": {
            "payment-method": [
                {
                "name": "string"
                }
            ]
        },
        "bank-account": {
            "iban": "string",
            "bic": "string"
        },
        "account-holder" : {
            "first-name" : "string",
            "last-name" : "string"
        },
        "descriptor": "string",
        "order-number": "string",
        "locale": "string",
        "success-redirect-url": "string",
        "fail-redirect-url": "string",
        "cancel-redirect-url": "string"
    }
}
Field (JSON) JSON Parent

value

merchant-account-id ({ })

request-id

payment ({ })

transaction-type

payment ({ })

currency

requested-amount ({ })

value

requested-amount ({ })

payment-method ([ ])/name

payment-methods ({ })

bic

bank-account ({ })

iban

bank-account ({ })

first-name

account-holder ({ })

last-name

account-holder ({ })

descriptor

payment ({ })

order-number

payment ({ })

locale

payment ({ })

success-redirect-url

payment ({ })

fail-redirect-url

payment ({ })

cancel-redirect-url

payment ({ })

Response-Only Fields
{
  "api-id" : "string",
  "parent-transaction-id" : "string",
  "transaction-state" : "string",
  "transaction-id" : "string",
  "completion-time-stamp" : "2018-03-23T10:41:34",
  "statuses" : {
    "status" : [ {
      "severity" : "string",
      "code" : "string",
      "description" : "string"
    } ]
  }
}
Field (JSON) JSON Parent

api-id

payment ({ })

parent-transaction-id

payment ({ })

transaction-state

payment ({ })

transaction-id

payment ({ })

completion-time-stamp

payment ({ })

status ([ {} ])/ severity

statuses ({ })

status ([ {} ])/ code

statuses ({ })

status ([ {} ])/ description

statuses ({ })