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. |
|
---|---|---|
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. |
-
Consumer adds items to his/her shopping basket.
-
Consumer selects iDEAL.
-
The merchant sends a get-url request to Payment Gateway.
-
Payment Gateway processes and validates the transaction.
-
Payment Gateway forwards the request to iDEAL.
-
iDEAL provides the URL of the consumer’s online banking account for payment verification.
-
Payment Gateway processes the response.
-
Payment Gateway redirects the consumer to the provided online banking URL.
-
Consumer verifies the payment within the personal online banking system.
-
iDEAL transfers funds from the consumer’s bank account to the merchant’s bank account.
-
iDEAL redirects consumer to the merchant’s result page.
-
iDEAL sends the transaction Status to Payment Gateway (Payment Gateway continuously queries for the payment status).
-
Payment Gateway processes the notification and sends the payment debit notification to the merchant.
-
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:
|
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:
|
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
|
Samples
<?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 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&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 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 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 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 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.
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) |
|
---|---|
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 |
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.
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:
-
Create a payment session (initial request).
-
Redirect the consumer to the payment page (initial response URL).
-
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.
The initial request creates the payment session. If it’s successful, you receive a URL as a response which redirects to the payment form.
Authorization |
Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg= |
---|---|
Content-Type |
application/json |
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.
{
"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.
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 |
||
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 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 |
{
"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.
{
"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:
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 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:
|
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).
{
"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 ({ }) |
{
"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 ({ }) |