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.

• 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

• 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

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",
}

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.

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"
}