This site requires javascript to be enabled.

iDEAL

Results for

Results for Searching

Backend only integration

Go for this option if you have your own checkout page UI, and you only need to use our Server APIs to accept payment whether it's through website or an app.

Before you begin

  • Make sure you've been boarded with iDEAL
  • Build your server integration
  • Build your payment product selection form
  • Build your payment product details form

Make a payment

Make POST /{merchantId}/payments API call, submitting the required properties.

Below, you'll find an example API call with the essential data. To add more information with additional properties, please visit to our API Reference.

Property Data type Required
order object yes
amountOfMoney object yes
currencyCode string yes
amount integer yes
customer object yes
billdingAddress object yes
countryCode string yes
redirectPaymentMethodSpecificInput object yes
paymentProductId integer yes
paymentProduct809SpecificInput object yes
issuerId string yes
redirectionData object yes
returnUrl string yes

Create payment
AmountOfMoney amountOfMoney = new AmountOfMoney();
amountOfMoney.setAmount(100L);
amountOfMoney.setCurrencyCode("EUR");

Address address = new Address();
address.setCountryCode("NL");

Customer customer = new Customer();
customer.setBillingAddress(address);

Order order = new Order();
order.setAmountOfMoney(amountOfMoney);
order.setCustomer(customer);

RedirectionData redirectionData = new RedirectionData();
redirectionData.setReturnUrl("https://www.example.com");

RedirectPaymentMethodSpecificInput redirectPaymentMethodSpecificInput = new RedirectPaymentMethodSpecificInput();
redirectPaymentMethodSpecificInput.setPaymentProductId(809);
redirectPaymentMethodSpecificInput.setRedirectionData(redirectionData);

CreatePaymentRequest createPaymentRequest = new CreatePaymentRequest();
createPaymentRequest.setRedirectPaymentMethodSpecificInput(redirectPaymentMethodSpecificInput);
createPaymentRequest.setOrder(order);

CreatePaymentResponse createPaymentResponse = client.merchant("merchantId").payments().create(createPaymentRequest);
var amountOfMoney = new AmountOfMoney();
amountOfMoney.Amount = 100L;
amountOfMoney.CurrencyCode = "EUR";

var address = new Address();
address.CountryCode = "NL";

var customer = new Customer();
customer.BillingAddress = address;

var order = new Order();
order.AmountOfMoney = amountOfMoney;
order.Customer = customer;

var redirectionData = new RedirectionData();
redirectionData.ReturnUrl = "https://www.example.com"

var redirectPaymentMethodSpecificInput = new RedirectPaymentMethodSpecificInput();
redirectPaymentMethodSpecificInput.PaymentProductId = 809;
redirectPaymentMethodSpecificInput.RedirectionData = redirectionData;

var createPaymentRequest = new CreatePaymentRequest();
createPaymentRequest.RedirectPaymentMethodSpecificInput = redirectPaymentMethodSpecificInput;
createPaymentRequest.Order = order;

var response = await client.V1.WithNewMerchant("merchantId").Payments.Create(createPaymentRequest);
var body = {
  "order": {
    "amountOfMoney": {
      "amount": 1,
      "currencyCode": "EUR"
    },
    "customer": {
      "billingAddress": {
        "countryCode": "NL"
      }
    }
  },
  "redirectPaymentMethodSpecificInput": {
    "paymentProductId": 809,
    "redirectionData": {
      "returnUrl": "https://example.org/return"
    }
  }
}

const sdkResponse = await client.v1.payments.create("merchantId", body);
$amountOfMoney = new AmountOfMoney();
$amountOfMoney->amount = 100;
$amountOfMoney->currencyCode = 'EUR';

$address = new Address();
$address->countryCode = 'NL';

$customer = new Customer();
$customer->billingAddress = $address;

$order = new Order();
$order->amountOfMoney = $amountOfMoney;
$order->customer = $customer;

$redirectionData = new RedirectionData();
$redirectionData->returnUrl = 'https://www.example.com';

$redirectPaymentMethodSpecificInput = new RedirectPaymentMethodSpecificInput();
$redirectPaymentMethodSpecificInput->paymentProductId = 809;
$redirectPaymentMethodSpecificInput->redirectionData = $redirectionData;

$createPaymentRequest = new CreatePaymentRequest();
$createPaymentRequest->redirectPaymentMethodSpecificInput = $redirectPaymentMethodSpecificInput
$createPaymentRequest->order = $order

org.tuckey.web.filters.urlrewrite.UrlRewriteWrappedResponse@4931cbc = $client->v1()->merchant('merchantId')->payments()->create($createPaymentRequest);
amount_of_money = AmountOfMoney()
amount_of_money.amount = 100
amount_of_money.currency_code = 'EUR'

address = Address()
address.country_code = 'NL'

customer = Customer()
customer.billing_address = address

order = Order()
order.amount_of_money = amount_of_money
order.customer = customer

redirection_data = RedirectionData()
redirection_data.return_url = 'https://www.example.com'

redirect_payment_method_specific_input = RedirectPaymentMethodSpecificInput()
redirect_payment_method_specific_input.payment_product_id = 809
redirect_payment_method_specific_input.redirection_data = redirection_data

create_payment_request = new CreatePaymentRequest()
create_payment_request.redirect_payment_method_specific_input = redirect_payment_method_specific_input
create_payment_request.order = order

response = client.v1().merchant('merchantId').payments().create(create_payment_request)
amount_of_money = Domain::AmountOfMoney.new
amount_of_money.amount = 100
amount_of_money.currency_code = 'EUR'

address = Domain::Address.new
address.country_code = 'NL'

customer = Domain::Customer.new
customer.billing_address = address

order = Domain::Order.new
order.amount_of_money = amount_of_money
order.customer = customer

redirection_data = Domain::RedirectionData.new
redirection_data.return_url = 'https://www.example.com'

redirect_payment_method_specific_input = 
Domain::RedirectPaymentMethodSpecificInput.new
redirect_payment_method_specific_input.payment_product_id = 809
redirect_payment_method_specific_input.redirection_data = redirection_data

create_payment_request = Domain::CreatePaymentRequest.new
create_payment_request.redirect_payment_method_specific_input = redirect_payment_method_specific_input
create_payment_request.order = order

response = client.v1.merchant('merchantId').payments.create(create_payment_request)
var amountOfMoney domain.AmountOfMoney
amountOfMoney.Amount = connectsdk.NewInt64(100)
amountOfMoney.CurrencyCode = connectsdk.newString("EUR")

var address domain.Address
address.CountryCode = connectsdk.newString("NL")

var customer domain.Customer
customer.BillingAddress = &address

var order domain.Order
order.AmountOfMoney = &amountOfMoney
order.Customer = &customer

var redirectionData domain.RedirectionData
redirectionData.ReturnUrl = connectsdk.newString("https://www.example.com")

var redirectPaymentMethodSpecificInput domain.RedirectPaymentMethodSpecificInput
redirectPaymentMethodSpecificInput.PaymentProductId = connectsdk.newInt64(809)
redirectPaymentMethodSpecificInput.RedirectionData = &redirectionData

var createPaymentRequest domain.CreatePaymentRequest
createPaymentRequest.RedirectPaymentMethodSpecificInput = &redirectPaymentMethodSpecificInput
createPaymentRequest.order = &order

response, err := client.V1().Merchant("merchantId").Payments().Create(createPaymentRequest, nil)
{
    "order": {
        "amountOfMoney": {
            "currencyCode": "EUR",
            "amount": "1000"
        },
        "customer": {
            "billingAddress": {
                "countryCode": "NL"
            }
        }
    },
    "redirectPaymentMethodSpecificInput": {
        "paymentProductId": "809",
        "paymentProduct809SpecificInput": {
            "issuerId": 3
        },
        "redirectionData": {
            "returnUrl": "https://www.example.com"
        }
    }
}

Create payment response

{
   "creationOutput" : {
      "additionalReference" : "00000099911009940168",
      "externalReference" : "000000999110099401680000100001"
   },
   "merchantAction" : {
      "actionType" : "REDIRECT",
      "redirectData" : {
         "RETURNMAC" : "bfccf850-6239-4f0d-8eeb-d935e37b1bad",
         "redirectURL" : "https://payment.pay1.preprod.checkout.worldline-solutions.com/redirector/return/066aa06e-3ea1-71ff-add3-7ce54ad1521c"
      },
      "showData" : [ ]
   },
   "payment" : {
      "id" : "000000999110099401680000100001",
      "paymentOutput" : {
         "amountOfMoney" : {
            "amount" : 100,
            "currencyCode" : "EUR"
         },
         "references" : {
            "paymentReference" : "999111455159"
         },
         "paymentMethod" : "redirect",
         "redirectPaymentMethodSpecificOutput" : {
            "paymentProductId" : 809
         }
      },
      "status" : "REDIRECTED",
      "statusOutput" : {
         "isCancellable" : false,
         "isRetriable" : false,
         "statusCategory" : "PENDING_PAYMENT",
         "statusCode" : 50,
         "statusCodeChangeDateTime" : "20240731114157",
         "isAuthorized" : false,
         "isRefundable" : false
      }
   }
}

Consumer redirection

If you use POST /{merchantId}/payments API call, you also need to take care of the consumer redirection (in the case of POST /{merchantId}/hostedcheckouts, we handle it ourselves). In the API response to this call we'll return a merchantAction object.

While there are several different actionType values, for iDEAL transactions, we consistently return the actionType value as REDIRECT. Along with this, a redirectData object is included, containing a redirectURL. You'll need to direct your consumer to this URL to complete their payment.

The merchantAction is only returned in the response to POST /{merchantId}/payments as shown in the following example:

Post payments response

    {
    "creationOutput": {
        "additionalReference": "00000880010000010166",
        "externalReference": "000008800100000101660000100001"
    },
    "merchantAction": {
        "actionType": "REDIRECT",
        "redirectData": {
            "RETURNMAC": "937037a1-8e39-40eb-9a57-94a6cfac****",
            "redirectURL": "https://openbanking1-int.worldline-solutions.com/bvn-idx-ideal-rs/issuerSim?hash=GR2VTxHspjjcJGaY8PZ9hqond****4ZFJtbJGhoMJKU&TRANSACTIONID=003000018487****"
        },
        "showData": []
    },
    "payment": {
        "id": "00000880010000010166000010****",
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 100,
                "currencyCode": "EUR"
            },
            "references": {
                "paymentReference": "133700297790"
            },
            "paymentMethod": "redirect",
            "redirectPaymentMethodSpecificOutput": {
                "paymentProductId": 809
            }
        },
        "status": "REDIRECTED",
        "statusOutput": {
            "isCancellable": false,
            "isRetriable": false,
            "statusCategory": "PENDING_PAYMENT",
            "statusCode": 50,
            "statusCodeChangeDateTime": "20231124150140",
            "isAuthorized": false,
            "isRefundable": false
        }
    }
}

The merchantAction is omitted from the GET /payments/{paymentId} API call and will return the following API response:

Get payments response

    {
    "creationOutput": {
        "additionalReference": "00000880010000010166",
        "externalReference": "000008800100000101660000100001"
    },
    "merchantAction": {
        "actionType": "REDIRECT",
        "redirectData": {
            "RETURNMAC": "937037a1-8e39-40eb-9a57-94a6cfac****",
            "redirectURL": "https://openbanking1-int.worldline-solutions.com/bvn-idx-ideal-rs/issuerSim?hash=GR2VTxHspjjcJGaY8PZ9hqond****4ZFJtbJGhoMJKU&TRANSACTIONID=003000018487****"
        },
        "showData": []
    },
    "payment": {
        "id": "000008800100000101660000100001",
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 100,
                "currencyCode": "EUR"
            },
            "references": {
                "paymentReference": "133700297790"
            },
            "paymentMethod": "redirect",
            "redirectPaymentMethodSpecificOutput": {
                "paymentProductId": 809
            }
        },
        "status": "REDIRECTED",
        "statusOutput": {
            "isCancellable": false,
            "isRetriable": false,
            "statusCategory": "PENDING_PAYMENT",
            "statusCode": 50,
            "statusCodeChangeDateTime": "20231124150140",
            "isAuthorized": false,
            "isRefundable": false
        }
    }
}

Next steps

Next Process flows