As an enhancement on the iDEAL Payment for Direct Connection a Merchant can make use of iDEAL User Tokens for User recognition by iDEAL. By using iDEAL User tokens, Merchants are able to enhance the iDEAL user flow by cutting out the browser redirect to the Issuer or payment page in some cases. This is possible for transactions where the following conditions apply:

User has an iDEAL profile and has consented to provide a user token to Merchant in a previous transaction
User works with iDEAL push notifications in its Issuer’s Mobile banking app
User shops at the Merchant on a desktop browser or application

If one or more of the above conditions do not apply, a redirect is needed for the User.

Transaction overview

For an enhanced iDEAL Payment flow with User Token the following steps apply:

Steps to retrieve a User Token:

Request iDEAL User Token: During a normal iDEAL payment transaction, the Merchant requests for a token for the User
User consents to provide Token for Merchant: During the transaction on the iDEAL Payment Page, the User consents to provide Token for faster iDEAL Payments at the Merchant
Retrieve User Token: at the end of the transaction, the Merchant receives the User Token, and can use this Token to enhance the transaction flow for a next iDEAL payment.

Steps to initiate and finalize an iDEAL payment with User token.

Request User Issuer/IBAN preferences: The Merchant uses the User token to request the User preferences on Issuing bank and IBAN. These are to be shown by the Merchant alongside the iDEAL payment button.
Transaction Initiation: When the user pushes the iDEAL button, Merchant initiates a transaction at the iDEAL Hub, including a User token. iDEAL responds with an instruction on whether to redirect to Issuer or to show a waiting screen (push notification is sent to User by Issuer).
Show waiting screen: The Merchant, if instructed to do so, shows a waiting screen, awaiting a status callback from iDEAL.
Issuer Authorization: The User receives a push notification through its mobile banking app
Transaction Confirmation: When the User authorizes the payment, the iDEAL Hub informs the recipient on the transaction callback URL of the confirmation. The Merchant shows confirmation of transaction to the User. Any requested new User Token is provided via the User Token callback URL

Request iDEAL User Token for a User

A User token for a given User can only be requested as part of a normal iDEAL payment transaction. To request a User token for a given User, the POST /transactions is called and a userTokenCallbackUrl is included in the body.

Once the User consented to providing a User token, identified itself and confirmed the payment through its Issuer, the User token is sent by iDEAL to the userTokenCallbackUrl .

The userToken retrieved in the callback MAY be used in a following transaction to request User Issuer/IBAN preferences and initiate an enhanced iDEAL payment transaction with a possible skip of the redirect.

The following general rules apply for User Tokens

The User for which a User Token is requested/used MUST hold an account with the merchant;
The Merchant MUST be able to recognize the User on a return visit;
The Merchant MUST only use iDEAL User Tokens that were received in the last transaction (on the User Token callback) for that User

Please note that an iDEAL User Token can only be linked to one iDEAL profile, and therefore only one User Token can be registered per Merchant account per User.

Example POST /transactions

curl -X 'POST' \
  'https://merchant-cpsp-mtls.idealapi.nl/v2/merchant-cpsp/transactions' \
  -H 'accept: application/json' \
  -H 'Request-ID: u06zf2cMq-w6ciUvZ8_MeVaQ4h' \
  -H 'Authorization: Bearer {JWT access token}' \
  -H 'Signature: {signature}' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": {"amount": 1100},
  "description": "Cookie",
  "reference": "iDEALpurchase21",
  "creditor": {"countryCode": "NL"},
  "transactionCallbackUrl": "https://checkout.company.com/transaction/webhook/91FA6EEC30844FAAB5",
  "userTokenCallbackUrl": "https://checkout.company.com/token/webhook/91FA6EEC30844FAAB5",
  "returnUrl": "https://www.myshop.com/paymentHandling"
}'

Example POST /user-token-callback to userTokenCallbackURL

{
  "transactionId": "0001000000000001",
  "userToken": "Z7xmaEJlB3rDLpmln9xbUlaQ"
}'

Request User Issuer/IBAN preferences

To be able to show the preferred Issuer and IBAN to the User in the Merchant environment, the Merchant needs to request these via its Acquirer. The User preferences can be retrieved by calling the GET /debtors/{usertoken}/preferences endpoint, and must include the iDEAL User Token (expectedDebtor.usertoken).

The preference call MUST include an iDEAL User Token (expectedDebtor.usertoken) that is provided by the Merchant
The /preferences API will return the User’s preferred Issuer and IBAN as stored in the User’s iDEAL profile. The User’s IBAN will be masked, showing only the first 8 and last 4 characters.
Acquirers MUST offer the /preferences endpoint to their Merchants and return the User’s preferred Issuer and IBAN to the Merchant

Example GET /debtors/{usertoken}/preferences

curl -X 'GET' \
  'https://merchant-cpsp-mtls.idealapi.nl/v2/merchant-cpsp/debtors/Z7xmaEJlB3rDLpmln9xbUlaQ/preferences' \
  -H 'accept: application/json' \
  -H 'Request-ID: u06zf2cMq-w6ciUvZ8_MeVaQ4h' \
  -H 'Authorization: Bearer {JWT access token}' \
  -H 'Signature: {signature}' \

HTTP 200 OK - Response Example

Transaction Initiation with User Token

A transaction initiation for an iDEAL transaction with User Token has the same properties as a normal transaction Initiation, except for the following differences:

The POST /transactions call must include:
- the iDEAL User Token expectedDebtor.userToken
- the user-agent of the User expectedDebtor.userAgent
The 200 OK response includes, next to the above-mentioned fields that are echoed, a notificationResult.

The notificationResult in the response can contain two values:

PUSH_SENT_SHOW_WAITING_SCREEN : in this case the Merchant should show a “waiting for confirmation” screen, as the User will have been sent a push notification from his Issuer in his mobile banking app to authorize the iDEAL transaction.
REDIRECT : in this case the Merchant must redirect the User to the URL received in the links.redirectUrl

iDEAL will ask for a redirect if for any reason the push notification could not be made by the Issuer. This could be e.g. in case the user agent is mobile phone, User has push notifications turned off, etc

Example POST /transactions

HTTP 200 OK - Response Example

User Token callback

If a usertokenCallbackUrl was provided in the POST /transactions call AND the User approved to be remembered by the Merchant for next transactions, iDEAL will provide a User Token by calling the /user-token-callback API. The endpoint used for this callback is the usertokenCallbackUrl provided in the transaction initiation.

Unhappy flow: User wants to pay with another IBAN/bank

In case the User, after having been presented its preferred IBAN/Issuer, indicates she wants to use anther IBAN/Issuer to pay for the iDEAL transaction, a normal POST /transactions without a expectedDebtor.userToken and/or usertokenCallbackUrl provided should be initiated. This way, a link to the payment page is returned to which the User can be redirected. Here the User can select another Issuer. A POST /transactions with a expectedDebtor.userToken should not be initiated in this case, because then a push notification is attempted to her preferred IBAN, which cold confuse the User (as she indicated she wanted to choose another IBAN/Issuer).

iDEAL Acquiring Participants Implementation

Enhanced iDEAL Payment flow with User Token for Direct Connection