Creating an iDEAL order

The following details are required when creating a new order:

  • Currency
  • Amount
  • Payment method

For an iDEAL order the following extra details are required:

  • BIC of the chosen bank (the “issuer ID”)
  • URL to redirect the customer to after payment (return_url – optional, but recommended)

This information should be sent to the API’s /orders/ resource using an HTTP POST containing a JSON body. The API response will contain, in the payment_url field, the URL the customer should be redirected to in order to start the payment.

Example order request:

POST /v1/orders/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=
Content-Type: application/json

{
  "merchant_order_id": "EXAMPLE001",
  "amount": 995,
  "currency": "EUR",
  "description": "Example order #1",
  "return_url": "http://www.example.com/",
  "transactions": [
    {
      "payment_method": "ideal",
      "payment_method_details": {
        "issuer_id": "INGBNL2A"
      }
    }
  ]
}

API reponse:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "amount": 995,
  "client": {
    "user_agent": "Testing API"
  },
  "created": "2016-07-04T11:41:55.635115+00:00",
  "currency": "EUR",
  "description": "Example order #1",
  "id": "0125e02b-557c-4fb5-956a-d22662d71ad9",
  "last_transaction_added": "2016-07-04T11:41:55.831655+00:00",
  "merchant_id": "7131b462-1b7d-489f-aba9-de2f0eadc9dc",
  "merchant_order_id": "EXAMPLE001",
  "modified": "2016-07-04T11:41:56.215543+00:00",
  "project_id": "1ef558ed-d77d-470d-b43b-c0f4a131bcef",
  "return_url": "http://www.example.com/",
  "status": "new",
  "transactions": [
    {
      "amount": 995,
      "balance": "internal",
      "created": "2016-07-04T11:41:55.831655+00:00",
      "credit_debit": "credit",
      "currency": "EUR",
      "description": "Example order #1",
      "events": [
        {
          "event": "new",
          "id": "0c4bd0cd-f197-446b-b218-39cbeb028290",
          "noticed": "2016-07-04T11:41:55.987468+00:00",
          "occurred": "2016-07-04T11:41:55.831655+00:00",
          "source": "set_status"
        }
      ],
      "expiration_period": "PT60M",
      "id": "6c81499c-14e4-4974-99e5-fe72ce019411",
      "merchant_id": "7131b462-1b7d-489f-aba9-de2f0eadc9dc",
      "modified": "2016-07-04T11:41:56.065147+00:00",
      "order_id": "0125e02b-557c-4fb5-956a-d22662d71ad9",
      "payment_method": "ideal",
      "payment_method_details": {
        "issuer_id": "INGBNL2A"
      },
      "payment_url": "api.online.emspay.eu/redirect/6c81499c-14e4-4974-99e5-fe72ce019411/to/payment/",
      "project_id": "1ef558ed-d77d-470d-b43b-c0f4a131bcef",
      "status": "new"
    }
  ]
}

Listing of all available issuers for iDEAL

To get a list of all available issuers for iDEAL, do the following request:

GET /v1/ideal/issuers/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=

As a response, you will get something like:

[
  {
    "id": "INGBNL2A",
    "list_type": "Deutschland",
    "name": "Issuer Simulation V3 - ING"
  },
  {
    "id": "RABONL2U",
    "list_type": "Deutschland",
    "name": "Issuer Simulation V3 - RABO"
  }
]

Performing the iDEAL redirect

To make the actual payment, the customer needs to visit the URL supplied in the payment_url field. This should be accomplished by using an HTTP redirect.

As soon as the customer visits the payment link, the order status will change from new to processing.

Handling the payment result

After payment, the iDEAL service will redirect the customer to the URL supplied in the return_url, whether the payment was successful or not. The order and project details will be supplied in GET variables (order_id and project_id).

For example:

http://www.example.com/?order_id=4c6afd74-a840-4aab-b411-1e6e0636d341&project_id=b5f39273-44e7-4385-8e08-44612ef3e117

The merchant can either display a generic “thank you” page, or request the status of the order and use this information to perform a custom action.