The iDeal Token Payment is an an iDEAL 2.0 feature with which a merchant can make use of iDEAL User Tokens (aka. Debtor Token) for User recognition by iDEAL. This feature allows the shopper to pay without browser redirection, but instead receive a push notification for the payment on their mobile device.

Ideal Token Registration

This feature requires the use of tokens, which are registered per shopper. This requires that a payment is performed is performed to validate the shopper before a token can be used. This payment can be either an implicit or penny check (2 cents) or consists of an actual order and payment. See the guide Tokenized Payments.

A token registration is completed when a successful iDeal payment is done for that token.

Ideal Tokenized Payment

Ideal token payments can only be performed using Rest API calls, see also Starting Tokenized Payment. For iDeal Token payment there are two scenarios:

The iDeal issuer is able to provide a push notification (it is enabled on the consumer's mobile device).
A fallback redirect URL is also available with this option, which allows for a redirect to the issuer in case the push notification could not or is not delivered for some technical reason.
The iDeal issuer is not able to provide a push notification (e.g. it is not enabled on the consumer's mobile device), in which case a redirect must be performed.

The combined flow is as followed, which is slightly different from Tokenized Payments due to the two above scenarios.

Ideal Token Payment

The data flow for paying an order with a token is as followed:

Shopper places an order and the order is created in the payment system. Optionally order items can be added.

A list of available tokens is retrieved for the order. The element additional_ideal_token_details contains additional information that should be displayed along side the iDEAL payment button.

>    curl \
       -X GET \
       --header 'Content-Type: application/json' \
       --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
       https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/shoppers/11111111-993a-424d-a769-3ee97116a1b6/tokens?page=1
 
   < Http 200 OK
   <    '[ {
            "token_key": "ece01f11-86e5-4bc6-9289-588d7c3ade4e",
            "state": "VALID",
            "date_created": "2025-08-25T14:51:53Z",
            "last_used": "2025-08-25T14:52:04Z",
            "payment_method": "IDEAL",
            "additional_ideal_token_details": {
               "masked_iban": "NL44RABO******6789",
               "issuer_name": "NG Bank N.V.",
               "issuer_logo_url": "https://www.ideal.nl/issuer-logos/ing.png"
         },
          {
            "token_key" : "252327a1-711b-421a-bf36-4dd34243fde9",
            "state" : "VALID",
            "date_created" : "2025-08-25T19:51:53Z",
            "last_used": "2025-08-25T14:51:53Z",
            "payment_method" : "BANCONTACT",
            "description": "Bancontact: **** 3002"
           },
 
   ]'

It is assumed that the available payments methods matches with the available tokens. Optionally, a list of available payment methods can be retrieved to filter out the tokenized payment method options that are not available for the order.
The shopper selects a valid ideal token.

The payment is started with the selected token.

>    curl \
       -X POST \
       --header 'Content-Type: application/json' \
       --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
       https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/11111111-993a-424d-a769-3ee97116a1b6/payments \   
    -d '{
            "method": "TOKEN",
            "authentication_methods" : ["USER_PASSWORD", "OUT_OF_BAND"],
            "token_details": {
               "token_key": "e7861525-a430-45bf-8a5b-f2989529ad42",
               "browser_information" : {
                   "shopper_ip" : "0.0.0.0",
                   "accept" : "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
                   "user_agent" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36 Edge/18.18363"
           }
        }
   }'
 
   < Http 201 Created
   <    '{
             "id": "pid1607665410t",
             "status": "AUTHORIZATION_REQUESTED",
             "urls": [
                 {
                     "purpose": "FALLBACK",
                     "method": "GET",
                     "url": "http://localhost:9090/ps_sim/idealbanksimulator.jsf?trxid=822526577880500&ec=1607665410&returnUrl=http%3A%2F%2Flocalhost%3A8080%2Fps%2FreturnFromAuthorization%3FpaymentReference%3D1607665410A657CE0566292C0EDE9CE641AF1B24A5%26checkDigitId%3D1607665410A657CE0566292C0EDE9CE641AF1B24A5&transactionCallbackUrl=http%3A%2F%2Flocalhost%3A8080%2Fps%2Fapi%2Fpublic%2Fintegrations%2Fv1%2Fideal%2Fcallback%2Ftransaction",
                     "order": 1
                 }
             ]
         }'

The status of the payment is returned. Depending on the scenario the returned payment information contains the state AUTHORIZATION_REQUESTED or REDIRECTED_FOR_AUTHORIZATION. The first state indicates that the iDeal issuer is able to send a push notification. The other state indicates that a push notification is not possible.

a. iDeal Sends a push notification

A popup should be shown indicating that a push notification is send. This popup should also contain the FALLBACK link, in case the notification was not received. If the shopper clicks on the link, then the shopper is redirected to the iDeal platform.

b. Redirect Shopper
The iDeal platform was unable to send a push notification, so the shopper must be redirected to the iDeal platform itself. This is the same as starting a normal iDeal payment.

iDeal Screens

Tokens with/without user preferences :

Token List Screen

Waiting screen for push notification :

Wait for Push Notification Screen

On clicking "Didn't Receive Notification", screen will be redirected to the below standard ideal payment page :

Ideal Standard Payment Screen