{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"iDEAL","type":"basic","slug":"ideal","excerpt":"Learn how to process iDEAL transactions with BlueSnap's Payment API.","body":"iDEAL is the most popular online payment method in the Netherlands (in the Euro) and is supported by the major Dutch banks. iDEAL enables shoppers to pay online through their banking portal and authenticate the transaction by entering their credentials, adding an additional layer of checkout security. \n\nThis guide covers the following topics: \n\n* [Requirements](#section-requirements)\n* [iDEAL transaction processing](#section-ideal-transaction-processing)\n* [API integrations](#section-api-integrations)\n* [Sandbox testing](#section-sandbox-testing)\n\n# Requirements\nIn your Merchant Portal, [verify Real-Time Bank Transfer has been enabled](https://support.bluesnap.com/docs/payment-method-setup) and is set to **Show**.\n\n# iDEAL transaction processing \nThese are the main steps involved in processing iDEAL transactions:\n\n1. Create a page for your shopper to enter their [personal information](/v8976-JSON/docs/payer-info). \n\n2. [Show a list of available banks](#section-retrieving-available-banks) so your shopper can make their selection. (Recommended)\n\n3. Send a [Create iDEAL Transaction request](/v8976-JSON/docs/create-ideal-transaction) to BlueSnap from your server. <br>\n  As part of the required parameters, provide a `returnUrl` where you would like BlueSnap to send your shopper after they complete their purchase. \n\n4. The API response will include `idealUrl` where you'll need to direct your shopper so they can complete their purchase. <br>\n  If your shopper did not select their bank on your website in step 2, then they will be prompted to select it at this time. \n\n5. Your shopper logs in to their banking portal and completes their purchase. Once complete, your shopper gets directed to the return URL you provided in step 3. You can parse the [query string](#section-return-url-query-string-parameters) of your URL to get the transaction results. \n\n**Note:** The transaction stays in pending status until the shopper completes the purchase. When the purchase is completed, the status updates to success or failed. \n\n### Retrieving available banks\nYou can get a list of available banks from BlueSnap and show them to your shopper. This enables your shopper to select their bank on your website, instead of having to complete this as a separate step later in the checkout process. The result is reduced checkout friction. Follow the steps below. \n\n1. Send a [Retrieve Bank Details](/v8976-Tools/docs/get-bank-details) request from your server. BlueSnap returns a list of `issuerId` and `issuerName` parameters.   \n\n2. In the UI, display the list of issuing bank names. \n\n3. When your shopper selects their bank, associate the bank name with its `issuerId`. You'll need this value when you create the transaction. \n\n4. In the [Create iDEAL Transaction request](/v8976-JSON/docs/create-ideal-transaction) request, include the `issuerId` parameter.\n\nIncluding `issuerId` in the request tells BlueSnap which bank your shopper selected and removes this step later in the checkout process. When you direct your shopper to the `idealUrl` provided by BlueSnap, they will go directly to their banking portal. \n\n### Return URL query string parameters \nBefore redirecting your shopper to your return URL, BlueSnap appends the query string with the following parameters to inform you of the transaction results. \n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`STATUS`\",\n    \"h-0\": \"Parameter Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The status of the transaction. \\n\\nPossible values: \\n\\n- `SUCCESS`\\n- `FAIL`\\n- `PENDING`\",\n    \"1-0\": \"`ORDER-ID`\",\n    \"1-1\": \"integer\",\n    \"1-2\": \"BlueSnap identifier for the order.\",\n    \"2-0\": \"`TRANSACTION-ID`\",\n    \"2-1\": \"string\",\n    \"2-2\": \"BlueSnap identifier for the approved transaction. Only returned if `STATUS` is `SUCCESS`\",\n    \"3-0\": \"`MTI`\",\n    \"3-1\": \"string\",\n    \"3-2\": \"The Merchant Transaction ID. Only returned if the value was included in the [Create iDEAL Transaction](/v8976-JSON/docs/create-ideal-transaction) request.\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n# API integrations\niDEAL transactions are supported in BlueSnap's Payment API. See: \n\n* [Create iDEAL Transaction](/v8976-JSON/docs/create-ideal-transaction)\n* [Retrieve iDEAL Transaction](/v8976-JSON/docs/retrieve-ideal-transaction)\n\n# Sandbox testing \nYou can use the following test cases to test various scenarios in Sandbox via the [Create iDEAL Transaction](/v8976-JSON/docs/create-ideal-transaction) request. \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Test Case\",\n    \"h-1\": \"Result\",\n    \"0-1\": \"The transaction status is `SUCCESS`.\",\n    \"0-0\": \"Append your `firstName` value with **_APPROVE**. \\nFor example: `Jane_APPROVE`\",\n    \"1-1\": \"The transaction status is `FAIL`.\",\n    \"1-0\": \"Append your `firstName` value with **_REJECT**. \\nFor example: `Jane_REJECT`\",\n    \"2-0\": \"Append your `firstName` value with **_DELAYAP**. \\n\\nFor example: `Jane_DELAYAP`\",\n    \"2-1\": \"The initial transaction status is `PENDING`, then changes to `SUCCESS` within 15 minutes.\",\n    \"3-0\": \"Append your `firstName` value with **_DELAYRJ**. \\n\\nFor example: `Jane_DELAYRJ`\",\n    \"3-1\": \"The initial transaction status is `PENDING`, then changes to `FAIL` within 15 minutes.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>","updates":[],"order":19,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"62db2350a08c5b01d83ecf66","createdAt":"2020-08-20T16:51:27.379Z","user":"5ea72d649148ff00653f6bbc","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Guides","slug":"topics","order":7,"from_sync":false,"reference":false,"_id":"62db2350a08c5b01d83ecf2a","version":"62db2350a08c5b01d83ecf6f","project":"57336fd5a6a9c40e00e13a0b","createdAt":"2015-11-03T20:45:01.593Z","__v":0},"version":{"version":"8976-Basics","version_clean":"8976.0.0-Basics","codename":"3.43 Release","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["62db2350a08c5b01d83ecf25","62db2350a08c5b01d83ecf26","62db2350a08c5b01d83ecf27","6183ed028202aa001610248b","62db2350a08c5b01d83ecf28","62db2350a08c5b01d83ecf29","5beb278ac442ab0213f00990","62db2350a08c5b01d83ecf2a","5c3f542c12c4ac004bc51718","6183ed028202aa001610248f","5df806ccecebde0059f17225","5dfa8a8f340c2b007418eb8a","62db2350a08c5b01d83ecf2b","5e597199fd2b0200117c2c1c"],"_id":"62db2350a08c5b01d83ecf6f","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"622623052699060013831de5","createdAt":"2018-04-23T14:36:48.535Z","releaseDate":"2018-04-23T14:36:48.535Z"},"project":"57336fd5a6a9c40e00e13a0b","__v":0,"parentDoc":null}

Quickstart

API Usage

Mobile

SDKs

Reference

Guides

iDEAL

Learn how to process iDEAL transactions with BlueSnap's Payment API.

iDEAL is the most popular online payment method in the Netherlands (in the Euro) and is supported by the major Dutch banks. iDEAL enables shoppers to pay online through their banking portal and authenticate the transaction by entering their credentials, adding an additional layer of checkout security.

This guide covers the following topics:

Requirements

In your Merchant Portal, verify Real-Time Bank Transfer has been enabled and is set to Show.

iDEAL transaction processing

These are the main steps involved in processing iDEAL transactions:

  1. Create a page for your shopper to enter their personal information.

  2. Show a list of available banks so your shopper can make their selection. (Recommended)

  3. Send a Create iDEAL Transaction request to BlueSnap from your server.

    As part of the required parameters, provide a returnUrl where you would like BlueSnap to send your shopper after they complete their purchase.

  4. The API response will include idealUrl where you'll need to direct your shopper so they can complete their purchase.

    If your shopper did not select their bank on your website in step 2, then they will be prompted to select it at this time.

  5. Your shopper logs in to their banking portal and completes their purchase. Once complete, your shopper gets directed to the return URL you provided in step 3. You can parse the query string of your URL to get the transaction results.

Note: The transaction stays in pending status until the shopper completes the purchase. When the purchase is completed, the status updates to success or failed.

Retrieving available banks

You can get a list of available banks from BlueSnap and show them to your shopper. This enables your shopper to select their bank on your website, instead of having to complete this as a separate step later in the checkout process. The result is reduced checkout friction. Follow the steps below.

  1. Send a Retrieve Bank Details request from your server. BlueSnap returns a list of issuerId and issuerName parameters.

  2. In the UI, display the list of issuing bank names.

  3. When your shopper selects their bank, associate the bank name with its issuerId. You'll need this value when you create the transaction.

  4. In the Create iDEAL Transaction request request, include the issuerId parameter.

Including issuerId in the request tells BlueSnap which bank your shopper selected and removes this step later in the checkout process. When you direct your shopper to the idealUrl provided by BlueSnap, they will go directly to their banking portal.

Return URL query string parameters

Before redirecting your shopper to your return URL, BlueSnap appends the query string with the following parameters to inform you of the transaction results.

Parameter Name
Type
Description

STATUS

string

The status of the transaction.

Possible values:

  • SUCCESS
  • FAIL
  • PENDING

ORDER-ID

integer

BlueSnap identifier for the order.

TRANSACTION-ID

string

BlueSnap identifier for the approved transaction. Only returned if STATUS is SUCCESS

MTI

string

The Merchant Transaction ID. Only returned if the value was included in the Create iDEAL Transaction request.

Back to Top

API integrations

iDEAL transactions are supported in BlueSnap's Payment API. See:

Sandbox testing

You can use the following test cases to test various scenarios in Sandbox via the Create iDEAL Transaction request.

Test Case
Result

Append your firstName value with _APPROVE.
For example: Jane_APPROVE

The transaction status is SUCCESS.

Append your firstName value with _REJECT.
For example: Jane_REJECT

The transaction status is FAIL.

Append your firstName value with _DELAYAP.

For example: Jane_DELAYAP

The initial transaction status is PENDING, then changes to SUCCESS within 15 minutes.

Append your firstName value with _DELAYRJ.

For example: Jane_DELAYRJ

The initial transaction status is PENDING, then changes to FAIL within 15 minutes.