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.wirecard.com/engine/rest/paymentmethods/

Merchant Account ID (MAID)

4aeccf39-0d47-47f6-a399-c05c1f2fc819

Username

16390-testing

Password

3!3013=D3fD8X7

Secret Key

7a353766-23b5-4992-ae96-cb4232998954
Additional Test Credentials on iDEAL Environment

BIC

INGBNL2A

The transaction result depends on the requested amount

Requested Amount

Result

EUR 1.00

Success

EUR 2.00

Canceled

EUR 3.00

Expired

EUR 4.00

Forever pending transaction

EUR 5.00

Failure
Workflow
debit
The merchant sends a debit request to Wirecard 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 Wirecard.
image

  1. Consumer adds items to his/her shopping basket.

  2. Consumer selects iDEAL.

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

  4. Wirecard Payment Gateway processes and validates the transaction.

  5. Wirecard Payment Gateway forwards the request to iDEAL.

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

  7. Wirecard Payment Gateway processes the response.

  8. Wirecard 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 Wirecard Payment Gateway (Wirecard Payment Gateway continuously queries for the payment status).

  13. Wirecard 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

HANDNL2A

Handelsbanken

INGBNL2A

ING

KNABNL2H

Knab

MOYONL21

Moneyou

RABONL2U

Rabobank

RGGINL21

Regio Bank

SNSBNL2A

SNS Bank

TRIONL2U

Triodos Bank

FVLBNL22

Van Lanschot Bankiers

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

Only the following banks can be used on http://api-test.wirecard.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>4aeccf39-0d47-47f6-a399-c05c1f2fc819</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>4aeccf39-0d47-47f6-a399-c05c1f2fc819</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.wirecard.com:443/engine/rest/merchants/4aeccf39-0d47-47f6-a399-c05c1f2fc819/payments/404894a2-fe56-4b79-8453-2935f78c0a6d">
 <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/4aeccf39-0d47-47f6-a399-c05c1f2fc819">4aeccf39-0d47-47f6-a399-c05c1f2fc819</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>4aeccf39-0d47-47f6-a399-c05c1f2fc819</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>4aeccf39-0d47-47f6-a399-c05c1f2fc819</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.wirecard.com:443/engine/rest/merchants/4aeccf39-0d47-47f6-a399-c05c1f2fc819/payments/40f59357-21e6-4ef8-81e8-9e6cea6b37d6">
  <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/4aeccf39-0d47-47f6-a399-c05c1f2fc819">4aeccf39-0d47-47f6-a399-c05c1f2fc819</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>

Wirecard Payment Page v2

Wirecard Payment Page v1 LEGACY is no longer supported. We recommend using Wirecard Payment Page v2 integration instead. If you have questions about your existing Wirecard Payment Page v1 integration, consult our REST API integration guide.

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 Wirecard Payment Page v2 (WPP v2)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

All WPP v2 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 WPP v2 section.

For response verification examples, see the WPP v2 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

HANDNL2A

Handelsbanken

INGBNL2A

ING

KNABNL2H

Knab

MOYONL21

Moneyou

RABONL2U

Rabobank

RGGINL21

Regio Bank

SNSBNL2A

SNS Bank

TRIONL2U

Triodos Bank

FVLBNL22

Van Lanschot Bankiers
Test Credentials

Test Credentials for Transaction Type debit.

URLI (Endpoint)

https://wpp-test.wirecard.com/api/payment/register

Merchant Account ID (MAID)

adb45327-170a-460b-9810-9008e9772f5f

Username

70000-APITEST-AP

Password

qD2wzQ_hrc!8

Secret Key (used for response verification)

1b9e63b4-c132-42c3-bcbd-2d2e47ae7154
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/NVP Field Reference section at the bottom.

1. Create a Payment Session (Initial Request)
{
    "payment": {
        "merchant-account-id": {
        "value": "adb45327-170a-460b-9810-9008e9772f5f"
        },
        "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 Wirecard).

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://wpp-test.wirecard.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7"
}
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 WPP v2 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" : "adb45327-170a-460b-9810-9008e9772f5f"
  },
  "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 Wirecard).

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 Wirecard). 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

WPP v2 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 WPP v2 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/NVP Field Reference

NVP equivalents for JSON fields (for migrating merchants).

Here you can:

  • find the NVP equivalents for JSON fields (for migrating merchants),

  • 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 (NVP) Field (JSON) JSON Parent

merchant_account_id

value

merchant-account-id ({ })

request-id

request-id

payment ({ })

transaction-type

transaction-type

payment ({ })

requested_amount_currency

currency

requested-amount ({ })

requested_amount

value

requested-amount ({ })

payment_method

payment-method ([ ])/name

payment-methods ({ })

bank_account_bic

bic

bank-account ({ })

bank_account_iban

iban

bank-account ({ })

first_name

first-name

account-holder ({ })

last_name

last-name

account-holder ({ })

descriptor

descriptor

payment ({ })

order_number

order-number

payment ({ })

locale

locale

payment ({ })

success_redirect_url

success-redirect-url

payment ({ })

fail_redirect_url

fail-redirect-url

payment ({ })

cancel_redirect_url

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 (NVP) Field (JSON) JSON Parent

api_id

api-id

payment ({ })

parent_transaction_id

parent-transaction-id

payment ({ })

transaction_state

transaction-state

payment ({ })

transaction_id

transaction-id

payment ({ })

completion_time_stamp

completion-time-stamp

payment ({ })

status_description_n

status ([ {} ])/ severity

statuses ({ })

status_severity_n

status ([ {} ])/ code

statuses ({ })

status_code_n

status ([ {} ])/ description

statuses ({ })

← Google Pay™ | Interac →