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 expire if no successful user authentication happened within this timeframe.
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 | Represents your customer's identification number. Please add customer ID in the billing object in case you want to use the debtor token feature. The customer ID will also be displayed on client's bank account statement, if provided in the message. |
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 in a previous transaction. It means that
customerIdparameter is to be sent to the Gateway - The user utilizes iDEAL push notifications in their issuer’s mobile banking app.
- The user shops using a desktop browser or an application
Fast Checkout
Provides a fast and secure checkout experience for consumers 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 |
The following JSON documents represent an example of the API request and response for Fast Checkout flow:
{
"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 2 days ago
