iDEAL Payment Integration
iDEAL is the most popular online payment method in the Netherlands. Customers choose their bank and approve the payment directly in their own online-banking environment. This guide explains how to accept iDEAL payments with the Netvalve Payment Gateway.
| Customer country | Currency | paymentOption |
|---|---|---|
| Netherlands (NL) | EUR | apm_ideal |
The order currency must be EUR for iDEAL to be offered.
For the shared redirect flow, webhook handling, and Checkout SDK notes, see the European Payment Methods overview.
How to offer iDEAL
Contact the Netvalve team to enable iDEAL on your account before going live.
Step 1 — Create the order
Send a POST request to the Create Order endpoint with paymentOption set to "apm_ideal" and the order currency set to EUR.
{
"amount": 44.99,
"currency": "EUR",
"siteId": "f76fb7ed-3312-4791-a216-45918f899271",
"clientOrderId": "{{clientOrderId}}",
"orderDesc": "Order #12345",
"successUrl": "https://merchantsite.com/success.html",
"cancelUrl": "https://merchantsite.com/cancel.html",
"failedUrl": "https://merchantsite.com/failed.html",
"pendingUrl": "https://merchantsite.com/pending.html",
"paymentOption": "apm_ideal",
"customerDetails": {
"customerAddress": "1 Test Street",
"customerCity": "Amsterdam",
"customerCountryCode": "NL",
"customerEmail": "customer@example.com",
"customerIp": "123.123.123.123",
"customerName": "Jan",
"customerLastName": "Jansen",
"customerPhone": "800-1234567",
"customerZipCode": "1011"
}
}
paymentOption accepts a comma-separated list. For example, "card,apm_ideal" shows both card and iDEAL on the hosted page.
Step 2 — Redirect and handle the outcome
On success the response contains a redirectUrl (verify responseCode === "GTW_1000" first). Send the customer there; Netvalve takes them to their bank to authorise, then returns them to one of your URLs:
| Outcome | Redirect target |
|---|---|
| Payment succeeded | successUrl |
| Customer cancelled | cancelUrl |
| Payment failed | failedUrl |
| Payment pending | pendingUrl |
Treat the webhook or an Inquiry poll as the source of truth for the final result.
Sandbox testing
Create the order against the Sandbox / UAT base URL and follow the redirectUrl. On the test bank page:
- Select any bank from the list, or submit the bank code
TESTNL2A. - Choose the outcome you want to test — the test bank page lets you approve, cancel, or fail the payment.
- Check that the customer lands on the matching return URL and that your webhook records the same result.
See Testing in sandbox for the shared setup, amount limits, and how to test the pending path.
Related resources
| Resource | Link |
|---|---|
| European Payment Methods overview | Overview |
| Hosted Payment Page guide | Hosted Payment Page |
| Swagger API reference | API Reference |
| Webhook Message guide | Webhook Message |
| Error Codes reference | Error Codes |