Online Payments / Payment Methods / IDEAL

iDEAL

iDEAL is a payment method that enables consumers to pay online through their banking portal. In the Netherlands all the major consumer banks support iDEAL and most consumers know how to use iDEAL.

If you integrate iDEAL through CCV Online Payments, you don’t need to enter into external contracts with iDEAL acquiring banks.

Typical iDEAL Transaction Flow

1. The Consumer selects the iDEAL payment method on your checkout page.
2. From a list of issuing banks, the Consumer selects their bank.
3. The consumer is redirected to their banking portal (app or website) where they enter their credentials and complete the payment.
4. After payment completion, the consumer is redirected towards your webshop or app.

Before you begin

• If you haven’t done so already, make sure to set up your test account and get your API key to start testing. Contact ecommerce@ccv.eu for questions surrounding your test account and credentials. Contact psp-support@ccvlab.eu for technical support.

iDEAL Transaction Processing Through CCV

The below steps describe a typical integration through CCV for iDEAL transactions:

1. The customer is done shopping and proceeds to checkout.
2. You request their/her authentication or a new registration in order to gather personal information.
3. Once the authentication is complete, you present the customer with the possible payment methods.
4. The customer selects payment method iDEAL.
5. At this point you want us to handle the payment. Your backend system initiates a payment transaction using the API. See also Create a new payment.
   • Specify a returnUrl to where the customer should be redirected after the payment is completed (successfully or otherwise). This can be a link to your webshop or a deep link to your mobile application.
   • You can register to our notification system to receive notifications regarding the transaction. Visit our Notifications section for more info.

Example request

curl --basic --user apikey: -H "User-Agent: Shop123456" -H "Idempotency-Reference: 1FAvu5eqNFwohXwPZLJajVecN5AIPaUl7qPFi4jFx4Hvt4SeUO" -H "Content-Type: application/json" --data '{  "amount" : 0.10,  "currency" : "eur",  "method" : "ideal",  "returnUrl" : "https://shop/return?order=123456",  "merchantOrderReference" : "123456",  "description" : "Order 123456",  "language" : "eng" }' https://api.psp.ccv.eu/api/v1/payment

Request body details

{
 "amount" : 0.10,
 "currency" : "eur",
 "method" : "ideal",
 "returnUrl" : "https://shop/return?order=123456",
 "merchantOrderReference" : "123456",
 "description" : "Order 123456",
 "language" : "eng"
}

6. After we validated the input parameters, we’ll return a new payment transaction. See also Payment object.

Example response

{
 "created": 1631889346517,
 "method": "ideal",
 "language": "eng",
 "currency": "eur",
 "lastUpdate": 1631889346517,
 "returnUrl": "https://shop/return?order=123456",
 "payUrl": "https://onlinepayments-accept.ccv.eu/ideal/payment.html?reference=I210917163546510CB87E181.2",
 "reference": "I210917163546510CB87E181.2",
 "merchantOrderReference": "123456",
 "amount": 0.10,
 "paidout": "no",
 "type": "sale",
 "description": "Order 123456",
 "status": "pending"
}

7. Redirect your customer to the payment URL (payUrl) as generated for the payment.

   • For details on how to use the payUrl inside a mobile application, visit the payUrl mobile integration consideration section below.

8. The customer lands on the issuer’s hosted authentication form to complete the payment authentication.

   Example of an issuer generated authentication form

   

9. The customer completes the authentication and approves the transaction. Once approved, the customer is redirected towards CCV and CCV will redirect the customer back to the return URL (returnUrl) you provided in the initial payment request, see step 6.

   Import note: You should not imply that the customer will return! See the returnUrl integration consideration below.

10. At this point you don’t know whether the payment is successful or not.

• You must request the status of the payment to complete your order correctly. See also Read a transaction.

Example request

curl --basic --user apikey: https://api.psp.ccv.eu/api/v1/transaction?reference=I210917163546510CB87E181.2

Example response

{
  "method": "ideal",
  "merchantOrderReference": "123456",
  "lastUpdate": 1632127457400,
  "details": {
    "consumerName": "Hr E G H Küppers en/of MW M.J. Küppers-Veeneman"
  },
  "paidout": "no",
  "returnUrl": "https://shop/return?order=123456",
  "payUrl": "https://shop-vpos-test.ccvlab.eu/ideal/ideal/dashboard?trxid=0001632127454888",
  "amount": 0.10,
  "reference": "I210917163546510CB87E181.2",
  "entryMode": "ecom",
  "created": 1631889346517,
  "currency": "eur",
  "language": "eng",
  "description": "Order 123456",
  "status": "success",
  "type": "sale"
}

11. Assuming the payment is successful, you can contact the customer by email with a confirmation, show an appropriate notification on the shop, …

12. As a side effect of completing a payment (successfully or not), we will notify you using either a webhook or notifications. This allows you to perform additional operations in your system like sending an email to your customer.

    Import note: A webhook does not contain any data except our payment reference. You must request the status of the payment before taking actions like shipping the order!

Integration Considerations

CCV PayUrl Mobile Integration

When performing a redirect towards the payUrl from inside a mobile device, we recommend the use of SFSafariViewController for iOS or Chrome Custom Tabs for Android, instead of a WebView.

However, if you decide to use a WebView anyway please consider the following:

• Security best practices for WebViews.
• The issuer authentication form for iDEAL may rely on external banking applications to be accessed from within the WebView. Please make sure your mobile application is able to handle these external deeplinks inside a webview.

Return URL

The return of a customer to your app or webshop (provided by the returnUrl) is the best-case scenario. Many reasons exist for why the customer does not return and some are listed here. It is therefore highly recommended that your business logic does not rely on the customer returning to your app or webshop. The actual transaction status is independent of whether the customer returns or not. You should always verify the status of the actual transaction with CCV to know if the payment succeeded or not. This can be done by using webhooks, notifications on your backend system or by the means of polling the transaction status, see also Read a transaction.

Customer chooses not to return

For iDEAL, the issuer’s authentication form provides an option to return to the webshop or app after the customer completes authentication. If the customer decides not to use the return option, he or she will not return to your webshop or application via the returnUrl.

ReturnUrl is opened by the wrong Browser on mobile device

Mobile device users that access your online webshop could experience a returnUrl redirect that is opened inside the wrong browser. This can happen for customers that use a different browser than the default configured browser of the customer’s mobile device. Consider the following scenario: the customer opens the payUrl inside the Opera Mobile browser and authenticates the payment using their/her issuer’s banking app on the same device. After authentication, the issuer’s banking app will redirect the customer to the default browser: eg. Chrome Browser of the customer’s mobile device. Every session data your business logic depends on will be unusable if the customer returns in a different browser. You should be able to handle this difference.

iDEAL user token

By utilizing iDEAL user tokens, you can streamline the iDEAL user experience by eliminating the need for a browser redirect to the Issuer or payment page in certain scenarios. This in turn results in less friction during the checkout process which can significantly reduce payment abandonment. Consider the following criteria if you opt to utilize iDEAL user tokens:

• The customer has an iDEAL profile.
• The customer consents to use an iDEAL user token for future payments.
• The customer interacts with iDEAL push notifications within their Issuer’s Mobile banking app.
• The customer makes purchases from the Merchant using a desktop browser or application.

If one or more of the above conditions do not apply, a redirect to the payUrl is needed for the customer.

CCV Pay offers iDEAL user tokens through our Mandates concept. For iDEAL mandates, the mandate id points directly to an iDEAL user token.

The mandate id can be retrieved during a normal iDEAL payment request, using the obtainMandate option. This payment follows a typical iDEAL flow, but the customer consents to provide the user token for future use. When this initial payment succeeds, you can obtain the mandate id through the transaction details.

Retrieve user token through our mandate flow

1. The customer is done shopping and proceeds to checkout

2. You initiate an iDEAL payment using the obtainMandate option

   • The example below uses notification requests. This allows you to receive notifications about this particular transaction.
   • When the obtainMandate is set to yes, these notification requests are also applied on the mandate that CCV creates during this transaction.
   • The notification requests have the following effect:
     • StatusChanged: you receive a notification when the status of the transaction changes
     • MandateUpdated: you receive a notification when the status of the mandate changes
   • Read more about notifications here

   Request body

 {
     "amount": 0.10,
     "currency": "eur",
     "method": "ideal",
     "returnUrl" : "https://shop/return?order=123456",
     "merchantOrderReference": "123456",
     "description": "Order 123456",
     "language": "eng",
     "obtainMandate": "yes",
     "notificationRequests": [
         {
             "eventType": "StatusChanged",
             "notificationUrl": "https://notifiy.shop/123456"
         },
         {
             "eventType": "MandateUpdated",
             "notificationUrl": "https://notifiy.shop/123456"
         }
     ]
 }

Note that https://notifiy.shop/123456 is just an example. You should use an endpoint at your system.

Response body

{
   "lastUpdate": 1709019909458,
   "created": 1709019909458,
   "status": "pending",
   "notificationRequests": [
      {
         "eventType": "statuschanged",
         "notificationUrl": "https://notifiy.shop/123456"
      },
      {
         "eventType": "mandateupdated",
         "notificationUrl": "https://notifiy.shop/123456"
      }
   ],
   "methodTransactionId": "0001709019911724",
   "amount": 0.10,
   "details": {},
   "description": "Order 123456",
   "merchantOrderReference": "123456",
   "reference": "I240227074509451CB87E196.G",
   "returnUrl": "https://shop/?order=123456",
   "payUrl": "https://shop-vpos-test.ccvlab.eu/ideal-v2/internal/payment-page?idealTransactionId=0001709019911724",
   "paidout": "no",
   "method": "ideal",
   "type": "sale",
   "language": "eng",
   "currency": "eur"
}

3. In the background the mandate is already created, but it is not yet active. Later on in the flow, you will receive a MandateUpdated notification indicating that the Mandate is active and ready to be used.

4. You redirect the customer to the payUrl provided in the response you received on the payment initiate in Step 2

5. During the transaction, on the iDEAL payment page, your customer must consent to provide a user token

6. When the transaction is approved, you receive 2 notifications:

   1. A StatusChanged notification indicating that the iDEAL transaction was successful.

   {
      "id": "I240227074509451CB87E196.G",
      "eventType": "StatusChanged",
      "eventTimestamp": 1709020105875,
      "order": 1,
      "attempt": 1,
      "newStatus": "SUCCESS"
   }
   

   2. A MandateUpdated notification telling you the mandate is now active:
      

   {
      "id": "MAN240227074511582CB87E192.0",
      "eventType": "MandateUpdated",
      "eventTimestamp": 1709020106150,
      "order": 2,
      "attempt": 1,
      "status": "ACTIVE"
   }
   

   Warning

   When the customer does not consent to provide the user token, the mandate won’t become active, and you will not receive the MandateUpdated notification. In this case you will not be able to use the mandate for future payments.

7. When you perform a Get Transaction request, the mandateId is also returned in the details section

      {
      "lastUpdate": 1709020105868,
      "statusFinalDate": 1709020105868,
      "created": 1709019909458,
      "status": "success",
      "notificationRequests": [
         {
            "eventType": "statuschanged",
            "notificationUrl": "https://notifiy.shop/123456"
         },
         {
            "eventType": "mandateupdated",
            "notificationUrl": "https://notifiy.shop/123456"
         }
      ],
      "methodTransactionId": "0001709019911724",
      "amount": 0.10,
      "details": {
         "consumerBic": "INGBNL2A",
         "mandateId": "MAN240227074511582CB87E192.0",
         "consumerAccountNumber": "NL53INGB0654422370",
         "consumerName": "Hr E G H Küppers en/of MW M.J. Küppers-Veeneman"
      },
      "description": "Order 123456",
      "merchantOrderReference": "123456",
      "entryMode": "ecom",
      "reference": "I240227074509451CB87E196.G",
      "returnUrl": "https://shop/?order=123456",
      "payUrl": "https://shop-vpos-test.ccvlab.eu/ideal-v2/internal/payment-page?idealTransactionId=0001709019911724",
      "paidout": "no",
      "method": "ideal",
      "type": "sale",
      "language": "eng",
      "currency": "eur"
   }
   

Use the user token in a payment

1. The customer is done shopping and proceeds to the checkout

2. You initiate an iDEAL payment using the mandateId. Mind that the userAgent is required in the details field. This is the User-Agent header of customers browser.

   Request body

    {
      "amount" : 0.10,
      "currency" : "eur",
      "method" : "ideal",
      "returnUrl" : "https://shop/return?order=789456",
      "merchantOrderReference" : "789456",
      "description" : "Order 789456",
      "language" : "eng",
      "mandateId" : "MAN240219140950233CB87E192.0",
      "notificationRequests": [
        {
          "eventType": "StatusChanged",
          "notificationUrl": "https://notifiy.shop/789456"
        }
      ],
      "details" : {
        "userAgent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Safari/605.1.15"
      }
    }
   

   Response body

   {
     "lastUpdate": 1708424404169,
     "methodTransactionId": "0001708424404291",
     "created": 1708424404169,
     "description": "Order 789456",
     "status": "pending",
     "amount": 0.10,
     "returnUrl": "https://shop/return?order=789456",
     "payUrl": "https://shop-vpos-test.ccvlab.eu/ideal-v2/internal/payment-page?idealTransactionId=0001708424404291",
     "paidout": "no",
     "notificationRequests": [
       {
         "eventType": "statuschanged",
         "notificationUrl": "https://notifiy.shop/789456"
       }
     ],
     "details": {
       "notificationResult": "PUSH_SENT_SHOW_WAITING_SCREEN"
     },
     "merchantOrderReference": "789456",
     "reference": "I240220102004164CB87E19A.5",
     "method": "ideal",
     "type": "sale",
     "language": "eng",
     "currency": "eur"
   }
   

3. iDEAL responds with an instruction on whether to redirect or to show a waiting screen (push notification is sent to customer by issuer). This instruction is shown in the details.notificationResult field of the response.

   The notificationResult can contain two values:

   • PUSH_SENT_SHOW_WAITING_SCREEN: in this case you should show a “Waiting for confirmation” screen, as the customer will have received a push notification from his issuer on their mobile phone to authorize the iDEAL transaction.
   • REDIRECT: in this case you must redirect the customer to the payUrl

   Note

   iDEAL will ask for a redirect if for any reason the push notification could not be made by the Issuer. Fo example if the user agent is a mobile phone, and customer has push notifications turned off on their mobile phone.

4. After the payment succeeds, you get a StatusChanged notification

5. When you perform a Get Transaction request, you see the same details as for a normal transaction

   Response body

     {
       "lastUpdate": 1708352229295,
       "statusFinalDate": 1708352229295,
       "methodTransactionId": "0001708352229158",
       "created": 1708352227060,
       "reference": "I240219141707056CB87E19C.N",
       "amount": 0.10,
       "entryMode": "ecom",
       "returnUrl": "https://shop/return?order=789456",
       "payUrl": "https://ext.pay.ideal.nl/transactions/https%3A%2F%2Fext.tx.ideal.nl%2F2%2FA4OBLQAWDUPJZAOUP4RHDKM5MQY?sig=BGBDAEIIAQ4ZABOVCJ4DRSGGQL4QZTFOO7X4X6UYHECJDTG5YKHZYCIRE2NBQEIIAWDXF2YWCU22MXDLMS5Y7W73EIC5JS3VYO5UK5A3YKMIKCCSGZYAA",
       "paidout": "no",
       "notificationRequests": [
         {
           "eventType": "statuschanged",
           "notificationUrl": "https://notifiy.shop/789456"
         }
       ],
       "details": {
         "consumerBic": "INGBNL2A",
         "mandateId": "MAN240219140950233CB87E192.0",
         "notificationResult": "PUSH_SENT_SHOW_WAITING_SCREEN",
         "consumerAccountNumber": "NL53INGB0654422370",
         "consumerName": "Hr E G H Küppers en/of MW M.J. Küppers-Veeneman"
       },
       "merchantOrderReference": "789456",
       "status": "success",
       "description": "Order 789456",
       "method": "ideal",
       "type": "sale",
       "language": "eng",
       "currency": "eur"
     }
   

iDeal Checkout - ‘Fast Checkout’

One of the factors that limits customer completion is registration: customers may decide to purchase something but change their minds when an account is required, because of the effort registration might take. This often leads to cart abandonment.

To avoid this iDeal offers iDeal Checkout / ‘Fast Checkout’ where a customer can purchase something without an account with the merchant. Billing, shipping and contact details are stored by and provided by iDeal to the merchant after order completion. iDeal stores and manages the required checkout details securely so that the merchant does not need to.

Using Ideal Checkout

1. A merchant can offer iDeal Fast Checkout using a 1-click button solution. Please review the iDeal Marketing Style guide .

2. To request an iDeal Checkout include one or more requestCheckoutDetails in your payment request. 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 (in this case an order that needs to be delivered) with the customer.

If a shipping fee applies it should be provided using a SHIPPING_FEE Order Line, with one or more additional order lines’s total amount adding up to the total payment amount. Before the customer selects iDEAL Checkout, the shipping costs must be communicated to the customer.

Example with shipping fee

{
  "amount" : 45,
  "currency" : "EUR",
  "method" : "ideal",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e2",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e2",
  "description" : "API Payment description",
  "language" : "nld",
  "details" : {
    "expirationDuration" : "P0Y2M1DT0H0M0.000S"
  },
  "requestCheckoutDetails" : [
      "first_name", "last_name", "email", "shipping"
  ],
  "orderLines": [
        {
           "type":"PHYSICAL",
            "name": "Wine Glass Large",
            "quantity": 2,
            "unit": "pcs",
            "totalPrice": 32,
            "unitPrice": 16
       },
       {
           "type":"SHIPPING_FEE",
            "name": "Standard Post",
            "quantity": 1,
            "unit": "package",
            "totalPrice": 13,
            "unitPrice": 13
       }
   ]
}

3. After the customer completes the payment iDeal provides us with the requested checkout details as approved by the customer. This information can be retrieved by reading the transaction:

• address details for billing and shipping are provided in the Payment Object as per usual. The customer can currently only add Shipping and Invoice addresses that are located in the Netherlands. Addresses outside of the Netherlands are not allowed. Merchants therefore can trust to receive only NL addresses.
• additional requested details are provided via the Payment Object’s Consumer object.

Example of transaction with consumer and shipping address details

{
  "amount" : 45,
  "currency" : "EUR",
  "method" : "ideal",
  "reference": "I240220102004164CB87E19A.5",
  "type": "sale",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e2",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e2",
  "description" : "API Payment description",
  "language" : "nld",
  "shippingFirstName": "Marie Josee",
  "shippingLastName": "Küppers-Veeneman",
  "shippingHouseNumber": "3",
  "shippingHouseExtension": "B",
  "shippingAddress": "Diamantstraat",
  "shippingCity": "Hengelo",
  "shippingPostalCode": "7554TA",
  "details" : {
    "expirationDuration" : "P0Y2M1DT0H0M0.000S"
  },
  "consumer" : {
      "firstName" : "M.J.",
      "lastName" : "Küppers-Veeneman",
      "emailAddress" : "mj_kuppers-veeneman@gmail.com"
  }
}

Test and go live

Using your test API key in combination with our API at https://api.psp.ccv.eu/api/v1, you can start testing your integration. Our iDEAL testing environment uses the payment amount field to trigger various test scenarios.

Refunds

iDEAL payments can be refunded up to 180 days after the original payment. Only successful payments can be refunded. Visit our refund endpoint documentation for more info.