{"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":17,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"622623052699060013831ddd","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":"622623052699060013831da1","version":"622623052699060013831de5","project":"57336fd5a6a9c40e00e13a0b","createdAt":"2015-11-03T20:45:01.593Z","__v":0},"version":{"version":"8976-Basics","version_clean":"8976.0.0-Basics","codename":"3.41 Release","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["622623052699060013831d9c","622623052699060013831d9d","622623052699060013831d9e","6183ed028202aa001610248b","622623052699060013831d9f","622623052699060013831da0","5beb278ac442ab0213f00990","622623052699060013831da1","5c3f542c12c4ac004bc51718","6183ed028202aa001610248f","5df806ccecebde0059f17225","5dfa8a8f340c2b007418eb8a","622623052699060013831da2","5e597199fd2b0200117c2c1c"],"_id":"622623052699060013831de5","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"6183ed028202aa00161024e9","createdAt":"2018-04-23T14:36:48.535Z","releaseDate":"2018-04-23T14:36:48.535Z"},"project":"57336fd5a6a9c40e00e13a0b","__v":0,"parentDoc":null}
iDEAL
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:
Create a page for your shopper to enter their personal information.
Show a list of available banks so your shopper can make their selection. (Recommended)
Send a Create iDEAL Transaction request to BlueSnap from your server.
As part of the required parameters, provide areturnUrl
where you would like BlueSnap to send your shopper after they complete their purchase.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.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.
Send a Retrieve Bank Details request from your server. BlueSnap returns a list of
issuerId
andissuerName
parameters.In the UI, display the list of issuing bank names.
When your shopper selects their bank, associate the bank name with its
issuerId
. You'll need this value when you create the transaction.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.
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.
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.
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.