iDEAL 2.0
Introduction
iDEAL is one of the most used online payment methods in the Netherlands, allowing consumers to pay with their online banking account.
Sale Transaction Request
In the first step you need to submit an ApmSaleTransaction request with IDEAL as payment method type.
iDEAL session timeout is 60 minutes by default. The transaction will be expired after that if there is no successful user authentication.
Mandatory Elements
| Field name | Description |
|---|---|
paymentMethod | IDEAL is the only value for this payment method |
integrationData | both, RETURN_URL and FAILURE_RETURN_URL arerecommended and for iDEAL they need to be identical |
The following JSON document represents an example of an initial request and the related response with the transactionStatus "WAITING". In the API response you receive the ipgTransactionIdwhat you must use in the inquiry request to confirm the transaction processing status.
{
"requestType": "ApmSaleTransaction",
"transactionAmount": {
"total": "20.85",
"currency": "EUR",
"components":{
"shipping": 0.85,
"subtotal": 15,
"vatAmount": 4
}
},
"paymentMethod": {
"type": "IDEAL"
},
"storeId": "12345678",
"order": {
"shipping": {
"name": "John Doe",
"address": {
"company": "Test Company",
"address1": "House No: 2, street -5",
"address2": "Weberstr",
"city": "BONN",
"postalCode": "53113",
"region": "Nordrhein-Westfalen",
"country": "Germany"
}
},
"basket": {
"items": [
{
"id": "item-1",
"description": "World cup",
"quantity": 1,
"subTotal": 9,
"valueAddedTax": 1,
"deliveryAmount": 0,
"chargeTotal": 10,
"currency": "EUR"
},
{
"id": "item-2",
"description": "cup",
"quantity": 1,
"subTotal": 2,
"valueAddedTax": 3,
"deliveryAmount": 0,
"chargeTotal": 5,
"currency": "EUR"
}
]
}
},
"integrationData": [
{
"item": "RETURN_URL",
"value": "https://www.fiserv.com"
},
{
"item": "FAILURE_RETURN_URL",
"value": "https://www.fiserv.com"
}
]
}
{
"type": "transactionResponse",
"clientRequestId": "e80efc8c-5acc-42bc-a8d0-16fe8748e83f",
"apiTraceId": "Zz88J0nxtg1r7LXuIOl6JAAAA8o",
"ipgTransactionId": "85024575497",
"orderId": "R-cb02f20c-d198-4d6a-a6f3-7a1bfb4a4acb",
"paymentToken": {
"reusable": true,
"declineDuplicates": false
},
"transactionTime": 1732197415,
"transactionAmount": {
"total": 13.00,
"currency": "EUR",
"components": {}
},
"transactionStatus": "WAITING",
"approvalCode": "?:waiting IDEAL",
"processor": {
"referenceNumber": "7030579722094781",
"responseCode": "Open",
"responseMessage": "IDEAL",
"taxRefundData": {}
},
"requiredActions": {
"requiredRedirectionData": {
"target": "https://ext.pay.ideal.nl/transactions/https%3A%2F%2Fext.tx.ideal.nl%2F2%2FACZHNXF5EIBB2O7HGVQFWJKWCXQ?sig=BGBCQEIAO3LPBEDPDQKC3MZ2CDUCTV5GPVQSWML5NIAIRXQJZ4C7CZ2RRBQBCCAGXEZOX3EAKRAE7N4J7W7WVZPC2Z2MHYIVLPSACZLOZGUPVQA6A7I",
"method": "GET"
}
}
}
Payment Status Inquiry
In the next step you need to submit an inquiry request using the ipgTransactionId you have received in the first API response from the Gateway to check the transaction status.
GET .../payments/{ipgTransactionID}
...
GET .../payments/85024575497
The following JSON document represents an example of an inquiry request with APPROVED transactionResult in the response:
{
"type": "transactionResponse",
"clientRequestId": "10c6ecfa-6c59-42b8-bc75-ed136492c26a",
"apiTraceId": "Zz9Aufqjr2GPBO-Uwqtc1gAAAbc",
"ipgTransactionId": "85024575497",
"orderId": "R-cb02f20c-d198-4d6a-a6f3-7a1bfb4a4acb",
"paymentToken": {
"reusable": true,
"declineDuplicates": false
},
"paymentMethodDetails": {
"paymentCard": {
"number": "NL44RABO0123456789",
"cardholderName": "Pino Thebird"
},
"paymentMethodBrand": "IDEAL"
},
"transactionTime": 1732197415,
"approvedAmount": {
"total": 13,
"currency": "EUR",
"components": {
"subtotal": 13
}
},
"transactionAmount": {
"total": 13,
"currency": "EUR",
"components": {
"subtotal": 13
}
},
"transactionResult": "APPROVED",
"approvalCode": "Y:000000:5024575497:PP X:7030579722094781",
"transactionState": "CAPTURED",
"processor": {
"referenceNumber": "7030579722094781",
"responseCode": "SettlementCompleted",
"responseMessage": "IDEAL",
"taxRefundData": {}
}
}
"transactionOrigin": "ECOM",
"integrationData": [
{
"item": "RETURN_URL",
"value": "https://www.fiserv.com"
},
{
"item": "FAILURE_RETURN_URL",
"value": "https://www.fiserv.com"
}
]
}
Debtor Token and Fast Checkout Features
Debtor Token
To allow the system to present the consumer's preferred IBAN without redirecting to iDEAL Payment Page.
| Field name | Description |
|---|---|
CustomerId | Please add Customer ID for billing purpose in the billing object in case you want to use the debtor token feature. |
The following JSON document represents an example of an Debtor Token request and the response:
{
"requestType": "ApmSaleTransaction",
"transactionAmount": {
"total": "13",
"currency": "EUR"
},
"paymentMethod": {
"type": "IDEAL"
},
"order": {
"billing": {
"customerId": "onecust"
}
},
"integrationData": [
{
"item": "RETURN_URL",
"value": "https://www.fiserv.com"
}
]
}
{
"type": "transactionResponse",
"clientRequestId": "fbc321a0-f471-46db-b1bb-c4cbec4c606a",
"apiTraceId": "Z5ybiKmlwkcI_r0_NhPq5QAAAok",
"ipgTransactionId": "85025883455",
"orderId": "R17383166803324753350153000919",
"paymentToken": {
"reusable": true,
"declineDuplicates": false
},
"transactionTime": 1738316680,
"transactionAmount": {
"total": 13.00,
"currency": "EUR",
"components": {}
},
"transactionStatus": "WAITING",
"approvalCode": "?:waiting IDEAL",
"processor": {
"referenceNumber": "7030146695959435",
"responseCode": "Open",
"responseMessage": "IDEAL",
"taxRefundData": {}
},
"requiredActions": {
"requiredRedirectionData": {
"target": "https://ext.pay.ideal.nl/transactions/https%3A%2F%2Fext.tx.ideal.nl%2F2%2FAYNPV6RZPZSXUTNVEQAC74LRIG4?sig=BGBCQEIAVBBGIGBKY4FTYGIZ2AQAKLBX7VNVH4JNMMUZSU2HDL6DQ4ZK74MBCCAH5V72MMXL46QPD2G26QVIAYCCZ6AGVHVAEHYY57CEYOUBVZ3YQKM",
"method": "GET"
}
}
}
Please note that following requirements are necessary to use debtor token functionality:
- The user has an iDEAL profile and has consented to provide a user token to the merchant in a previous transaction. ➡ It means that merchants need to pass
customerIDto IPG - The user utilizes iDEAL push notifications in their issuer’s mobile banking app.
- The user shops at the merchant on a desktop browser or application.
Fast Checkout
A fast and secure checkout experience for consumer with iDEAL Profile. In case your account has been configured for Fast Checkout.
| Field name | Description |
|---|---|
flowType | Please use this optional parameter located in the merchantParameters object populated with the value:FastCheckout to indicated you wish to use Fast Checkout instead of a standard flow. |
subtotal | Subtotal amount of the transaction |
{
"requestType": "ApmSaleTransaction",
"transactionAmount": {
"total": "13",
"currency": "EUR"
},
"paymentMethod": {
"type": "IDEAL"
},
"order": {
"additionalDetails": {
"merchantParameters": {
"FlowType": "FastCheckout"
}
}
},
"integrationData": [
{
"item": "RETURN_URL",
"value": "https://www.fiserv.com"
}
]
}
{
"type": "transactionResponse",
"clientRequestId": "3fbfa08d-ca1e-455a-9032-923f1724c3a6",
"apiTraceId": "Z5ybsk8_xMc0NkbT5pUDMgAAAB0",
"ipgTransactionId": "85025883456",
"orderId": "R17383167227825612568322660101",
"paymentToken": {
"reusable": true,
"declineDuplicates": false
},
"transactionTime": 1738316722,
"transactionAmount": {
"total": 13.00,
"currency": "EUR",
"components": {}
},
"transactionStatus": "WAITING",
"approvalCode": "?:waiting IDEAL",
"processor": {
"referenceNumber": "7030864884019795",
"responseCode": "Open",
"responseMessage": "IDEAL",
"taxRefundData": {}
},
"requiredActions": {
"requiredRedirectionData": {
"target": "https://ext.pay.ideal.nl/transactions/https%3A%2F%2Fext.tx.ideal.nl%2F2%2FAXTFL3CVW7FQ3SLEVDNPUUO2MW4?sig=BGBCQEIIA3DCD4O3GQ56EDXEJ7CNOPGKR6YS74X7GLGP4SOAIVNYPKXJY6BEAEIA4ILUROXLQHJMGPWTK3UAOKNYYQKC3ZO4IX3QY2BSNDTGLI6KZ3I",
"method": "GET"
}
}
Updated 3 days ago
