Last Updated: 09 July 2025 | Change Log

iDeal

iDEAL is an online bank transfer and is the most common payment method in the Netherlands. It allows customers to pay for goods or services through their bank account.

Note

Make yourself familiar with our API Principles to ensure a resilient integration.

Product overview

Why use iDeal?

iDeal is a popular, secure and reliable online bank transfer that requires no pre-registration or enrolment. It's easy to use as your customers use their own online bank banking to complete transactions.

Feature summary

Payment type	Countries	Currencies	Recurring	Reversals	Partial Reversals	Disputes	Auth and Settlement (Sale)
Bank transfer	NL	EUR	✅	Refund - yes Cancel- No	Partial refund - yes Partial cancel- No	❌	✅

The minimum amount for a single transaction is: 0.01 EUR
The maximum amount for a single transaction is: 50.000 EUR

Payment flows

There are two ways to make an Ideal payment:

one time payments
recurring direct debits payments with payment token. You can send a recurring payment request that will create a SEPA token. You can use the token to make SEPA follow-up payments.

Get started

Get started using our API Reference and set your headers.

Request

POST https://try.access.worldpay.com/apmPayments

Example requests

application/json

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "method": "ideal",
    "value": {
      "amount": 250,
      "currency": "GBP"
    },
    "narrative": {
      "line1": "Mind Palace"
    },
    "paymentInstrument": {
      "type": "direct"
    },
    "resultUrls": {
      "failure": "https://worldpay.com/failure",
      "success": "https://worldpay.com/success",
      "cancel": "https://worldpay.com/cancel"
    },
    "shipping": {
      "firstName": "John",
      "lastName": "Smitt",
      "address": {
        "address1": "221B Baker Street",
        "address2": "221B Baker Street",
        "address3": "221B Baker Street",
        "postalCode": "NW1 6XE",
        "city": "London",
        "state": "Greater London",
        "countryCode": "GB"
      }
    },
    "customer": {
      "email": "moriarty@example.com"
    }
  }
}

Parameters

transactionReferencestring[ 1 .. 64 ] characters^[a-zA-Z0-9\-_/!@#$%()*=.:;?\[\]{}~+]*$required

merchantobject(MerchantV2)required

merchant.entitystring[ 3 .. 32 ] characters^([a-zA-Z0-9\- ]*)$required

Used to route the request in Access Worldpay, created as part of on-boarding.

Example: "default"

instructionobject(InstructionV2)required

Object that contains the payment type and details.

instruction.methodstringrequired

Type of payment method

Value"alipay_cn"

Discriminator

instruction.valueobject(Value)required

The value of the payment.

instruction.value.amountinteger(int64)[ 1 .. 2147483647 ]required

The amount in the lowest denomination of the currency e.g. pennies for GBP, cents for USD.

Example: 12

instruction.value.currencystringrequired

The supported ISO 4217 currency codes.

Enum"AED""AFN""ANG""AOA""ARS""AUD""AWG""AZN""BAM""BBD"

instruction.narrativeobject(NarrativeBase)required

instruction.narrative.line1string[ 1 .. 24 ] characters^[a-zA-Z0-9-., ]*$required

The description shown on your customer's bank statement for the payment.

Example: "MindPalace"

instruction.paymentInstrumentobject(AlipayCnInstrumentV2)required

instruction.paymentInstrument.typestringrequired

Type of instruction

Value"direct"

instruction.paymentInstrument.languagestring

Your customer's language.

Enum"aa""ab""ae""af""ak""am""an""ar""as""av"

instruction.resultUrlsobject(ResultUrlsAlipay)required

instruction.resultUrls.cancelstring

The URL your customer is redirected to, after a cancelled payment outcome.

Example: "https://worldpay.com/cancel"

instruction.resultUrls.failurestringrequired

The URL your customer is redirected to, after a failed payment outcome.

Example: "https://worldpay.com/failure"

instruction.resultUrls.pendingstringrequired

The URL your customer is redirected to, after a pending payment outcome.

Example: "https://worldpay.com/pending"

instruction.resultUrls.successstringrequired

The URL your customer is redirected to, after a successful payment outcome.

Example: "https://worldpay.com/success"

instruction.deviceDataobject(DeviceData)

instruction.customerobject(CustomerWithName)

Response

Successful request response

an HTTP code 201
a paymentId which is unique to the payment - we recommend storing the "id", as you can use it to manage the payment later
a url to redirect your customer to the APM provider to complete the payment
a link to query the payment status
an object which will give flow information such as method (e.g. ideal) and type (direct)
a commandId generated by us identifying a single merchant interaction (e.g. cmdYNdIHBPJwbkjLiykzTx0)

Example response

{
  "paymentId": "uK9Oh5zz4yKhGuFofhhnC7KnABEsnvjTFefo7uUYYarwh_KRcHUrrs1qJtQso9gjnhxT5oAgkJfCp1iX6U1upLOpzqHmhG8uXdBKXQ0rnmce4brW4F54BCV6GtAu0zUbgUZHQIK3iu8VcHfOiFVHyN-y7ZDRr24t7o6s_bHlZxo9g_WHOCgZdL-FywMmqkQA",
  "lastEvent": "pending",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apmPayments/uK9Oh5zz4yKhGuFofhhnC7KnABEsnvjTFefo7uUYYarwh_KRcHUrrs1qJtQso9gjnhxT5oAgkJfCp1iX6U1upLOpzqHmhG8uXdBKXQ0rnmce4brW4F54BCV6GtAu0zUbgUZHQIK3iu8VcHfOiFVHyN-y7ZDRr24t7o6s_bHlZxo9g_WHOCgZdL-FywMmqkQA"
    }
  },
  "_actions": {},
  "redirect": "https://secure-test.worldpay.com/wcc/simulator?op=iDEALv2-AuthInit&trxId=205914553129935",
  "paymentInstrument": {
    "method": "ideal",
    "type": "direct"
  },
  "commandId": "cmdEy5vwB0krLe9eMwAcE66c0"
}

Errors

Check out our API reference for the full error code schema.

Next steps

Manage your iDeal payment/products/access/apms/@20240701/manage.md)