IDIN (iDEAL Bank Verification)

Verify a user's bank account via iDEAL (the Dutch online banking standard). The user is redirected to their bank, authorises, and is returned to you; the API exposes the bank list, starts a session, and receives the result via a callback.

List banks

GET /idin/banks

curl https://api.dev.valydar.com/idin/banks

Response:

{ "banks": [ { "id": "INGBNL2A", "name": "ING" }, { "id": "ABNANL2A", "name": "ABN AMRO" } ] }

Start a session

POST /idin/start

curl -X POST https://api.dev.valydar.com/idin/start \
  -H 'Content-Type: application/json' \
  -d '{"return_url": "https://yourapp.example/idin/return", "bank_id": "INGBNL2A"}'

Field	Type	Description
return_url	string	Where the bank returns the user after authorisation
bank_id	string	Optional — bank to preselect; omit to let the user choose

Response:

{ "redirect_url": "https://...", "session_id": "idin_...", "bank_id": "INGBNL2A" }

Redirect the user to redirect_url to complete bank authorisation.

Callback

POST /idin/callback

The bank/provider posts the result here. In development, GET /idin/mock-auth simulates the return leg so you can exercise the flow end-to-end without a real bank.

Error handling

A malformed request or unsupported bank returns 400. Provider/transport failures return 5xx; retries are safe because sessions are idempotent per session_id.