Skip to content

iDEAL

Accept payments with iDEAL, the go-to online banking method in the Netherlands, with widespread support from major Dutch banks.

When customers use iDEAL, they select their issuing bank and complete payments on the bank’s platform. It is highly secure, with immediate payment notification.

Payment optionCategoryCountryCurrencyFeaturesIntegrations
iDEALOnline BankingNetherlandsEURPartial refund
Refunds
Cancellation
API
Payment form
Prestashop plugin
WooCommerce plugin
Magento plugin

How to use iDEAL

The journey unfolds as follows:

  1. On the merchant’s website, the customer selects iDEAL as their payment method.
  2. They are redirected to a page where they are presented with a list from which they can select their preferred bank.
  3. The customer chooses a bank from the list, and they are redirected to their online bank.
  4. The customer confirms the payment and is redirected back to the merchant’s website.
  5. The merchant receives the payment confirmation.
  6. The merchant can ship the order/deliver the goods to the customer.

How it works

Here is an overview of the crucial steps required to integrate the iDEAL payment method.

Step 1: Create the Order
Step 2: Get the Payment Link
Step 3: Get the Payment Status
Step 1: Create the Order

Make sure to initiate the order request with iDEAL (“IDEL”) as the chosen payment method (transaction.paymentMethod) and configure the customer’s language preference in customerInfo.customerLanguage.

Step 2: Get the Payment Link

Follow the instructions below to obtain the payment link, to redirect the customer to a secure payment page for authentication and payment authorization.

Please be aware that the request below requires an Authorization Header containing the transactionSignature obtained on the previous step.

Endpoints:
EnvironmentURLOperation Method & EndpointOperation Description
PRODapi.sibsgateway.comPOST {version-id}/payments/{id}/pbl/payment-linkPerform the transaction and redirect user to Payment Host.
TESTstargate-cer.qly.site[1|2].sibs.ptPOST {version-id}/payments/{id}/pbl/payment-linkPerform the transaction and redirect user to Payment Host.

Ensure that you include these essential elements as specified:

LocationData ElementTypeConditionDescription
PathidStringMandatoryUsed to identify the transaction
Header parameters:
LocationData ElementTypeConditionDescription
Request HeaderContent-TypeStringMandatoryapplication/json
Request HeaderAuthorizationStringMandatoryAuthorization Digest
Request parameters:
LocationData ElementTypeConditionDescription
Request BodyuserAcceptanceIndicatorBooleanMandatoryIndicates if the user has accepted the Terms and Conditions, in order to continue with the payment.
Request BodygatewayIdStringMandatoryPayment Channel identifier for the channel the Customer is going to use for their payment.
Value: ‘ideal’ – iDEAL;
Request BodyinfoInfoMandatoryObject that defines the transaction additional information.
Request Body.infodeviceInfoDeviceInfoOptionalObject that defines the customer device information.
Request Body.info.deviceInfobrowserAcceptHeaderstringOptionalBrowser Accept Header
Request Body.info.deviceInfobrowserJavaEnabledstringOptionalBrowser Java Enabled
Request Body.info.deviceInfobrowserLanguagestringOptionalbrowser Language
Request Body.info.deviceInfobrowserColorDepthstringOptionalbrowser Color Depth
Request Body.info.deviceInfobrowserScreenHeightstringOptionalbrowser Screen Height
Request Body.info.deviceInfobrowserScreenWidthstringOptionalbrowser Screen Width
Request Body.info.deviceInfobrowserTZstringOptionalBrowser Time Zone
Request Body.info.deviceInfobrowserUserAgentstringOptionalBrowser User Agent
Request Body.info.deviceInfosystemFamilystringOptionalSystem Family
Request Body.info.deviceInfosystemVersionstringOptionalSystem Version
Request Body.info.deviceInfosystemArchitecturestringOptionalSystem Architecture
Request Body.info.deviceInfodeviceManufacturerstringOptionalDevice Manufacturer
Request Body.info.deviceInfodeviceModelstringOptionalDevice Model
Request Body.info.deviceInfodeviceIDstringOptionalDevice Unique Identification
Request Body.info.deviceInfoapplicationNamestringOptionalApplication Name
Request Body.info.deviceInfoapplicationVersionstringOptionalApplication Version
Request Body.info.deviceInfogeoLocalizationstringOptionalGeolocation
Request Body.info.deviceInfoipAddressstringOptionalIP Address
Request BodycustomerInfoCustomerInfoOptionalKey Value tuple array.
Request Body.customerInfokeystringMandatoryUsed to supply “customerName”, “customerEmail”.
Request Body.customerInfovaluestringMandatoryUsed to supply “customerName”, “customerEmail”.
Request BodymerchantMerchantOptionalMerchant Data
Request Body.merchantmerchantURLstringMandatoryMerchant Shop URL for redirect.
Request Body.infoaccountInfoAccountInfoOptionalAccount related data. 
Applicable when gatewayId is ‘ideal’
Request Body.info.accountInfoholderNameMax100TextOptionalAccount Holder Name. UTF-8 Format. 
Request Body.info.accountInfocustomerCountryCountry CodeOptionalCustomer Country Code. Alpha2

Here’s a model of how to get the payment link:

{
    "userAcceptanceIndicator": true,
    "gatewayId": "ideal",
    "info": {
        "deviceInfo": {
            "browserAcceptHeader": "application/json, text/plain, */*",
            "browserJavaEnabled": "false",
            "browserLanguage": "en",
            "browserColorDepth": "24",
            "browserScreenHeight": "1080",
            "browserScreenWidth": "1920",
            "browserTZ": "-60",
            "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
            "geoLocalization": "Lat: 38.7350528 | Long: -9.2143616",
            "systemFamily": "Windows",
            "systemVersion": "Windows",
            "deviceID": "498bfd4c3a3645b38667a7037b616c18",
            "applicationName": "Chrome",
            "applicationVersion": "106"
        },
        "customerInfo": [
            {
                "key": "customerName",
                "value": "Test Name"
            },
            {
                "key": "customerEmail",
                "value": email@provider.com
            }
        ],
        "accountInfo": {
            "holderName": "Test Name",
            "customerCountry": "BE"
        }
    },
    "merchant": {
        "merchantURL": https://egadget2.azurewebsites.net/#/returns?id={{transactionId}}
    }
}

After successfully completing the operation, a ‘pending’ paymentStatus is received.

The user is then redirected to a payment confirmation environment before being seamlessly returned to the merchant’s URL.

Step 3: Get the Payment Status

You can perform a “Get Status” operation to check the status at any time.

The Authorization HTTP header is set to the Bearer token as it was used in the initial Checkout.

GET {transactionID}/status
Request URL:
https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status
Request Headers:
Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>’
Content-Type: application/json

A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.

Here are some examples of the possible result codes:

Result CodestatusMsgDescriptionAction
HTTP-200SuccessSuccess responseN/A
HTTP-400Bad RequestThe JSON payload is not matching the API definition or some mandatory HTTP headers are missing.Please check in API Market for the correct syntax.
HTTP-401UnauthorizedOn the Authorization, Bearer token is invalid/expired or not associated with the Terminal used.Please check in SIBS Backoffice under the Credentials if the token is valid and create a new one if needed.
HTTP-403ForbiddenThe ClientID set on the X-IBM-Client-Id HTTP header is not valid or does not possess a valid subscription to the API.Please check in SIBS Backoffice under the SPG APP 2.0 if the ClientID is correct. If the problem persists contact SIBS Gateway support for a ClientID reset.
HTTP-405Method Not AllowedThe HTTP Method used is not matching any of the API definitions available.Please check in API Market for the correct HTTP Method.
HTTP-429Too Many RequestsThe API calls rate limit has been exceeded.Please check in API Market for information on the rate limits that apply to the API.
HTTP-500Internal Server ErrorThe API call has failed… and its most likely on our side.You should retry the operation, and if the problem persists contact SIBS Gateway support for assistance.
HTTP-503Service UnavailableThe API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.You should wait and try again later.