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
| Note |
|---|
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 /transactionscall must include:transactionFlowMUST be set toFAST_CHECKOUTthe
amount.breakdownfieldThis field MUST include both an
orderAmountand ashippingCostsubfield. If no shipping costs apply, the field must be filled with 0.The sum of the
orderAmountandshippingCostMUST be equal to theamountfield, which represents the total transaction amount to be payed by the User.
| Note |
|---|
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
requestedCheckoutDetailsfield MUST be set. Only those data fields that are set totruewill be included in the callback
| Note |
|---|
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
200OKresponse of the/transactionscall will always include a URL to the payment page in thelinks.redirectURLfield, never an IssuerURL.
Example POST /transactions
| Code Block | ||
|---|---|---|
| ||
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
requestedCheckoutDetailswill 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.
| Note |
|---|
The User can currently only add Shipping and Invoice addresses in The Netherlands. Any other non-NL addresses are currently not allowed. Merchants therefore can trust to receive only NL addresses. |
Example POST /transaction-callback
| Code Block | ||
|---|---|---|
| ||
{
"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
| Info |
|---|
Note that for a checkout transaction you may receive 4 different User names:
|