Payment with iDEAL Checkout (Snel Bestellen) for Direct Connection
An iDEAL payment with iDEAL Checkout allows a User to centrally manage his shipping, invoice and contact details in its iDEAL profile and provide these to a Merchant as part of the iDEAL payment
Transaction overview
Present iDEAL Checkout: In the shopping process, a separate iDEAL checkout button is presented by the Merchant.
Initiate iDEAL Checkout transaction: To start an iDEAL Checkout transaction, the Merchant specifically indicates this in the transaction initiation
iDEAL Payment Page: If the User is recognized by a cookie and an iDEAL profile is detected, the shipping address preferences are shown to him on the iDEAL payment page. The User then confirms its shipping details on the iDEAL payment page.
Issuer Authorization: The User authorizes the payment at the Issuer (like in regular iDEAL payments)
Transaction Confirmation & Return to Merchant: The payment is confirmed by Issuer and User is redirected to Merchant. Next to the payment status the Merchant also receives the shipping details of the User.
Currently only Dutch shipping addresses are supported.
Present iDEAL Checkout
To indicate to Users that iDEAL Checkout is offered the Merchant MUST show the iDEAL Checkout button. Instruction on how to do this can be found here: iDEAL Snel bestellen button: brand guidelines
Before the User selects iDEAL Checkout, the applicable shipping costs MUST be communicated to the User, to prevent that the User is confronted with a higher amount in the iDEAL screens than expected;
Transaction Initiation
A transaction initiation for an iDEAL Checkout transaction has the same properties as a normal transaction Initiation, except for the following differences:
The
POST /transactions
call must include:transactionFlow
MUST be set toFAST_CHECKOUT
the
amount.breakdown
fieldThis field MUST include both an
orderAmount
and ashippingCost
subfield. If no shipping costs apply, the field must be filled with 0.The sum of the
orderAmount
andshippingCost
MUST be equal to theamount
field, which represents the total transaction amount to be payed by the User.
It is (currently) not possible to dynamically define or alter the shipping amount based on the User’s chosen shipping address. The shipping amount can only be provided one time in the transaction initiation. The shipping amount can also be 0.
To specify the desired iDEAL Checkout data to be received, the
requestedCheckoutDetails
field MUST be set. Only those data fields that are set totrue
will be included in the callback
To comply with the General Data Protection Regulation (GDPR), the Merchant SHOULD only request the personal data which is absolutely needed to fulfill the agreement with the User;
The
200OK
response of the/transactions
call will always include a URL to the payment page in thelinks.redirectURL
field, never an IssuerURL.
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}' \
-d '{
"amount": {
"amount": 1100,
"breakdown": {
"orderAmount": 1000,
"shippingCost": 100
},
"currency": "EUR"
},
"description": "Cookie",
"reference": "iDEALpurchase21",
"creditor": {
"countryCode": "NL"
},
"transactionCallbackUrl": "https://checkout.company.com/transaction/webhook/91FA6EEC30844FAAB5",
"returnUrl": "https://www.myshop.com/paymentHandling"
}'
"transactionFlow": "FAST_CHECKOUT",
"requestedCheckoutDetails": {
"debtorContactDetails": {
"phoneNumber": true,
"email": true
},
"shippingAddress": true,
"invoiceAddress": true,
},
"transactionCallbackUrl": "https://checkout.company.com/transaction/webhook/91FA6EEC30844FAAB5",
"returnUrl": "https://www.myshop.com/paymentHandling",
}
Transaction Confirmation & Return to Merchant
After initiating an iDEAL Checkout, the User is redirected to the iDEAL Payment Page. Depending on whether the User has a recognized iDEAL profile, the User is guided through the iDEAL Fast-Checkout flow:
If the User is recognised by a browser cookie, his shipping address preferences from its iDEAL profile are shown. Note that only the data fields indicated in
requestedCheckoutDetails
will be shown to the UserProfile information presented will be partly masked for privacy reasons. The User can unmask these if needed by logging in via his Issuer.
If a registered User does not have any shipping address registered with its profile yet, it will first be asked to provide an address before he can proceed.
If the User is not recognized, but does have an iDEAL profile, he can login at his Issuer to load his shipping data from his profile.
At any time during the iDEAL Checkout flow, the User may choose to swap between saved shipping addresses for the transaction, or add a new address.
If the User is not recognized and is a new user, the User is asked to register an iDEAL profile, including shipping address.
After the confirmation on the payment page, the User is directed to the Issuer for finalizing the payment (via QR, redirect or push notification).
After the User has confirmed the transaction payment at the Issuer, the User’s iDEAL Checkout data (like shipping address) is added to the POST /transaction-callback
alongside the other payment details.
The iDEAL Checkout data can be found in the debtor.CheckoutPreferences
. Note that only data fields that were indicated in the requestedCheckoutDetails
will be included in the callback.
Example POST /transaction-callback
{
"transactionId": "0001000000000001",
"amount": {
"amount": 1100,
"breakdown": {
"orderAmount": 1000,
"shippingCost": 100
},
"type": "FIXED",
"maximum": 10000,
"minimum": 1,
"currency": "EUR"
},
"description": "Cookie",
"reference": "iDEALpurchase21",
"createdDateTimestamp": "2022-08-24T14:26:53.135Z",
"expiryDateTimestamp": "2022-08-24T14:26:53.135Z",
"finalStateDateTimestamp": "2022-08-24T14:26:53.135Z",
"status": "SUCCESS",
"guaranteedAmount": 1000,
"debtor": {
"iban": "NL44RABO0123456789",
"bic": "ABNANL2AXXX",
"name": "Edsger Wybe Dijkstra",
"checkoutPreferences": {
"contactDetails": {
"phoneNumber": "+31612345678",
"email": "edsger@domain.nl"
},
"shippingAddress": {
"firstName": "Edsger",
"lastName": "Dijkstra",
"companyName": "Cookie factory",
"postalCode": "1234AB",
"houseNumber": "100",
"addition": "2B",
"street": "Bankastraat",
"city": "Amsterdam",
"countryName": "Netherlands"
},
"invoiceAddress": {
"firstName": "Edsger",
"lastName": "Dijkstra",
"companyName": "Cookie factory",
"postalCode": "1234AB",
"houseNumber": "100",
"addition": "2B",
"street": "Bankastraat",
"city": "Amsterdam",
"countryName": "Netherlands"
}
}
},
"issuerID": "RABONL2UXXX"
}
User names received after successful Checkout transactions
Copyright © Currence iDEAL B.V. All rights reserved.