Versions Compared

Old Version 3

changes.mady.by.user Currence

Saved on

compared with

New Version 4

changes.mady.by.user Currence

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

  1. Present iDEAL Checkout: In the shopping process, a separate iDEAL checkout button is presented by the Merchant.

  2. Initiate iDEAL Checkout transaction: To start an iDEAL Checkout transaction, the Merchant specifically indicates this in the transaction initiation

  3. 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.

  4. Issuer Authorization: The User authorizes the payment at the Issuer (like in regular iDEAL payments)

  5. 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.

Figma for confluence lite
nodeUrlhttps://www.figma.com/proto/52tKlPbzhG8E5IUSS4U51R/iDEAL-2.0---New-visual-designs?kind=&node-id=8694%3A549025&page-id=8694%3A548925&scaling=scale-down&starting-point-node-id=8694%3A554359
height600px

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: /wiki/spaces/I2P/pages/3156443147 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 to FAST_CHECKOUT

    • the amount.breakdown field

      • This field MUST include both an orderAmount and a shippingCost subfield. If no shipping costs apply, the field must be filled with 0.

      • The sum of the orderAmount and shippingCost MUST be equal to the amount field, 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 requestedCheckoutDetails field MUST be set. Only those data fields that are set to true will 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 200OK response of the /transactions call will always include a URL to the payment page in the links.redirectURL field, never an IssuerURL.

Example POST /transactions

Code Block
languagejson
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 User

    • Profile 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
languagejson
{
  "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"
}