Enhanced iDEAL Payment flow with User Token for Direct Connection
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 MerchantThe
/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, anotificationResult
.
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 thelinks.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).
Copyright © Currence iDEAL B.V. All rights reserved.