iDEAL

Home    APMs    iDEAL

On this page:
Attributes
  • METHOD TYPEReal-Time Bank Transfer
  • PAYMENTS
  • PAYOUTS
  • REFUNDS
  • RECURRING

Introduction

iDEAL is a real-time online bank transfer payment method in the Netherlands, where a consumer is redirected to a banking app to authenticate and approve payments, including request‑to‑pay links and P2P QR-based transfers. As part of the European Payments Initiative, iDEAL is transitioning into Wero—a pan‑EU wallet built on SEPA Instant—shifting from bank redirects to wallet-based push confirmations, expanding coverage beyond the Netherlands, and enabling instant payments, subscriptions, and event‑driven flows; merchants and PSPs will gradually migrate to Wero APIs during the coexistence period.

Supported Countries

  • Netherlands

Supported Currencies

  • EUR

REST API 1.0

Payment (Deposit) Flow

If you wish to perform a payout transaction in the future, you will need to use the same userTokenId and userPaymentOptionId values that are generated in this payment transaction.

Follow these steps to perform a payment using Nuvei REST API integration:

1. Generate a sessionToken

Press here for details.

2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters including:

  • userTokenId
  • amount
  • currency
  • paymentOption.alternativePaymentMethod class containing:
    • paymentMethod: “apmgw_iDeal“
    • BIC – Customer’s bank name. Not mandatory for iDEAL 2.0 flow.
  • deviceDetails class containing: ipAddress
  • billingAddress class containing: firstName, lastName, email, country
  • userDetails class containing: firstName, lastName, email, country

Marketplace merchants must also include the marketplace addendum with its mandatory parameters, including subMerchantId. With certain providers, if the request includes subMerchantName, Nuvei sends it to the provider as the point of sale (up to 50 characters). Otherwise, Nuvei sends subMerchantId.

Example /payment Request
{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "amount":"200",
  "currency":"EUR",
  "userTokenId":"<unique customer identifier in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "paymentOption":{
    "alternativePaymentMethod":{
      "paymentMethod":"apmgw_iDeal",
      "BIC":"<bank name>"
    }
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "billingAddress":{
    "firstName":"John",
    "lastName":"Smith",
    "email":"[email protected]",
    "country":"NL"
  },
  "userDetails":{
    "firstName":"John",
    "lastName":"Smith",
    "email":"[email protected]",
    "country":"NL"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

The response generates and returns a redirect URL (redirectUrl) to redirect the customer to the payment page, as well as a UPO (userPaymentOptionId) for use in future transactions.

Example /payment Response
{
  "orderId":"350728608",
  "userTokenId":"Johnsmith01",
  "paymentOption":{
    "redirectUrl":"https://gw-apm-globalpayapi.nuvei.com/Home?PaymentToken=B21D7637BE0E42610920EB59833AEC0F.15101944",
    "userPaymentOptionId":"86068558",
  },
  "transactionStatus":"REDIRECT",
  "sessionToken":"1b72ddb6-f451-4aa5-b166-ce10dfd530cd",
  "clientUniqueId":"20180327175242",
  "internalRequestId":593943808,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20230117061727"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to the URL provided in urlDetails.notification, which Nuvei recommends including in the /payment request.

Example /payment DMN with status=PENDING
...'ppp_status=PENDING&Status=PENDING&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=348002578&userid=F477C7B214207674&merchant_unique_id=100127996A1014481279&customData=&productId=&first_name=PhbTexacztRGiYO&last_name=NTxtTCxzomvtUAz&email=Spec466153608%40168.com&currency=EUR&clientUniqueId=100127996A1014481279&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=OKsWqiYERSZVKDHhxMcrSNkGlcolgJ+466153609&address2=&country=Netherlands&state=&city=VXWwujwuYT&zip=123456789&phone1=31466153611&phone2=&phone3=&client_ip=95.129.32.18&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=PPRO-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=205956&merchant_status=&action=&requestVersion=&message=PENDING&merchantLocale=&unknownParameters=&payment_method=apmgw_iDeal&ID=&merchant_id=9077335539861697843&responseTimeStamp=2022-12-22.08%3A03%3A24&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=F477C7B214207674&userPaymentOptionId=85260368&TransactionID=811000000000741898&externalAccountDescription=payer_name%3APhbTexacztRGiYO+NTxtTCxzomvtUAz&externalTransactionId=140019237155&APMReferenceID=F07C9062DE61AA710C3ADA8D7A66AF07&orderTransactionId=1173059918&totalAmount=10.00&dynamicDescriptor=test&item_name_1=www.devcode.se&item_number_1=&item_amount_1=10.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20221222&type=DEPOSIT&clientRequestId=3910c128-2613-4b02-b7d3-112c48df0656&relatedTransactionId=&apmPayerInfo=SRCCOUNTRY%3ANL%3B&sessionId=879e38f2b077cae7d0e3d37a1fff&responsechecksum=de0b8ffd42af07888b991f47e05202fc69f5b4ca4108266e7ced8944fff911ab&advanceResponseChecksum=c6d5e46c7f65835b08f4adc7c538f29222df14faf81d29007c1fd052119ea1fd',
Example /payment DMN with status=APPROVED
...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=350763428&userid=Johnsmith01&merchant_unique_id=20180327175242&customData=&productId=&first_name=John&last_name=Smith&email=JohnS%40test.com&currency=EUR&clientUniqueId=20180327175242&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Test+Street&address2=&country=Netherlands&state=&city=Yambol&zip=80410100&phone1=11111122200&phone2=&phone3=&client_ip=127.0.0.1&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Nuvei-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=NL96SNSB0115541241&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=224428&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_iDeal&ID=&merchant_id=2439523627382132721&responseTimeStamp=2023-01-17.14%3A36%3A59&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Johnsmith01&userPaymentOptionId=86068558&TransactionID=711000000019066750&externalTransactionId=15135257&APMReferenceID=0EB03ABD418AA8EC8D2F0954946C8080&orderTransactionId=1177415928&totalAmount=100.00&dynamicDescriptor=test&item_name_1=NA&item_number_1=&item_amount_1=100.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20230117&type=DEPOSIT&clientRequestId=20230117093549&relatedTransactionId=&apmPayerInfo=%7B%22StatusInfo%22%3A%22%7B+StatusCode%3A+%2C+info%3A+%2C+originalAmount%3A+100.0000%2C+ProcessedAmount%3A+100%7D%22%2C%22AccountNumber%22%3A%22NL96SNSB0115541241%22%2C%22AccountHolder%22%3A%22Hr+E+G+H+K%C3%BCppers+en%2Fof+MW+M.J.+K%C3%BCppers-Veeneman%22%7D&sessionId=027ad1c105e3f9ae06ca3b464c0e&responsechecksum=de9a2addf8c6191824e549e5b6e9a1c1d58df1ed28c5b46c0f966b139ce15afa&advanceResponseChecksum=8337eda0641cff8c340ec6037adb092f27cf37dcbd8943ed7a30cc777acbcc26',
Example /payment DMN with status=DECLINED
...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=9999&errScDescription=Default&Reason=Default&ReasonCode=9999&PPP_TransactionID=348002578&userid=F477C7B214207674&merchant_unique_id=100127996A1014481279&customData=&productId=&first_name=PhbTexacztRGiYO&last_name=NTxtTCxzomvtUAz&email=Spec466153608%40168.com&currency=EUR&clientUniqueId=100127996A1014481279&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=OKsWqiYERSZVKDHhxMcrSNkGlcolgJ+466153609&address2=&country=Netherlands&state=&city=VXWwujwuYT&zip=123456789&phone1=31466153611&phone2=&phone3=&client_ip=95.129.32.18&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=PPRO-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=205956&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=&unknownParameters=&payment_method=apmgw_iDeal&ID=&merchant_id=9077335539861697843&responseTimeStamp=2022-12-23.10%3A57%3A41&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=F477C7B214207674&userPaymentOptionId=85260368&TransactionID=811000000000741898&externalAccountDescription=payer_name%3APhbTexacztRGiYO+NTxtTCxzomvtUAz&externalTransactionId=140019237155&APMReferenceID=F07C9062DE61AA710C3ADA8D7A66AF07&orderTransactionId=1173059918&totalAmount=10.00&dynamicDescriptor=test&item_name_1=www.devcode.se&item_number_1=&item_amount_1=10.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20221222&type=DEPOSIT&clientRequestId=3910c128-2613-4b02-b7d3-112c48df0656&relatedTransactionId=&apmPayerInfo=SRCCOUNTRY%3ANL%3B&sessionId=879e38f2b077cae7d0e3d37a1fff&responsechecksum=9a5e1735e3f80033798b74051e91bcd4d451d2ee18b5d8547e34061b525aa15c&advanceResponseChecksum=b1975b4960accaf10c88e01c6e3e31b121513f42feb04b77af6c5baab26e9499',

Payout (Withdrawal) Flow

You have two options to perform a payout:

  • Use the apmgw_iDeal UPO for processing the payouts as described below.
  • Collect account details from the deposit and use them via another payment method such as SEPA Payouts; for example, take the IBAN from the DMN and create a SEPA Payouts /payout request.

A payout can only be performed after userTokenId and  userPaymentOptionId were generated from a previous payment transaction.

Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.

After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in urlDetails.notification, which Nuvei recommends including in the /payout request.

Example /payout DMN with status=APPROVED
...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=&PPP_TransactionID=350729388&userid=Johnsmith01&merchant_unique_id=20180327175242&customData=Jake+Test+Account&productId=&first_name=&last_name=&email=&currency=EUR&clientUniqueId=20180327175242&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=224428&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_iDeal&ID=&merchant_id=2439523627382132721&responseTimeStamp=2023-01-17.11%3A41%3A06&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&user_token_id=Johnsmith01&userPaymentOptionId=86068558&TransactionID=711000000019056819&externalTransactionId=21388&totalAmount=100.0&dynamicDescriptor=test&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20230117&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=27e197fa1aa87b94a3b8e9406c1f5c613d8d7dad70296d8d3861f7e1d0c43a67&advanceResponseChecksum=4fea038b4f55080669af024731b43342e43c75581555c518842a1e64add8692c',
Example /payout DMN with status=DECLINED
...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=null&errScCode=9999&errScDescription=Default&Reason=&ReasonCode=&PPP_TransactionID=349320188&userid=johndoe_02&merchant_unique_id=20180327175242&customData=Jake+Test+Account&productId=&first_name=&last_name=&email=&currency=EUR&clientUniqueId=20180327175242&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=224428&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=&unknownParameters=&payment_method=apmgw_iDeal&ID=&merchant_id=2439523627382132721&responseTimeStamp=2023-01-05.04%3A58%3A10&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&userPaymentOptionId=85667308&TransactionID=811000000001240444&externalTransactionId=140023294587&totalAmount=1.0&dynamicDescriptor=test&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20230104&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=9932f219ede74800efe25c0976d4b3180e7a2ab2d67fddbf016b473428be831d&advanceResponseChecksum=dee29d667467c4d21efd7ca61882b089c55ddb5d6d4f99be25d592fd67b330cb',

REST API 2.0

Payment (Deposit) Flow

Perform the payment by sending a /payments request with the mandatory parameters including:

  • buyerDetails.buyerId
  • paymentOption.alternativePaymentMethod containing:
    • name: "iDeal"
    • data.bic: Customer’s bank name. Not mandatory for iDEAL 2.0 flow.
  • amount
  • currency
  • deviceDetails.ipAddress
  • buyerDetails with:
    • firstName, lastName, email, country
  • billingAddress.countryCode

REST API 2.0 does not support Marketplace.

Example /payments Request
{
    "processingEntityId": "<processingEntityId>",
    "amount": 60,
    "currency": "EUR",
    "paymentOption": {
        "alternativePaymentMethod": {
            "name": "iDeal",
         "data": {
            "bic": "INGBNL2A"
      },

        }
    },
    "deviceDetails": {
        "ipAddress": "145.89.23.67"
    },
    "buyerDetails": {
        "buyerId": "NL-BUYER-9876",
        "firstName": "Sven",
        "lastName": "Van Dijk",
        "companyName": "Holland Retail BV",
        "locale": "nl-NL",
        "dateOfBirth": "1985-06-15",
        "email": "[email protected]",
        "phone": "+31-612345678",
        "billingAddress": {
            "address": "Damrak 45",
            "zip": "1012LG",
            "city": "Amsterdam",
            "countryCode": "NL",
            "phone": "+31-612345678",
            "addressMatch": true
        },
        "shippingAddress": {
            "sameAsBilling": true,
            "address": "Damrak 45",
            "zip": "1012LG",
            "city": "Amsterdam",
            "countryCode": "NL",
            "phone": "+31-612345678"
        }
    }
}

The response generates and returns a redirect URL (redirectUrl) to redirect the customer to the payment page, as well as a UPO (userPaymentOptionId) for use in future transactions.

Example /payments Response
{
"paymentId": "7194b6a90bcb4929a5838e392daedc0b",
"amount": 60,
"currency": "EUR",
"transactionType": "Sale",
"result": {
"status": "redirect"
},
"redirectUrl": "https://authman.sandbox.lp-pl.ppro.com/v1/redirections/eu-central-1/forward?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfMmRYVGR3UnpqbDRuMTlsSjR2RGhxIn19 ",
"paymentOption": {
"alternativePaymentMethod": {
"name": "iDeal",
"paymentTokenId": "6e4019f5b0984e289ee786bc66e29f00"
}
}
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) (webhook) that includes the result of the transaction to the URL provided in urlDetails.notification, which Nuvei recommends including in the /payment request.

Example /payments Webhook Transaction with status=APPROVED
{
  "authorizingEntityId": "<authorizingEntityId>",
  "processingEntityId": "<processingEntityId>",
    "buyerId": "NL-BUYER-9876",
  "transactionId": "6612733797119789611",
  "paymentId": "7194b6a90bcb4929a5838e392daedc0b",
  "version": "2.0",
  "amount": 60,
  "currency": "EUR",
  "transactionType": "Sale",
  "result": {
    "status": "approved"
  },
  "timeStamp": "2026-01-13T11:53:34.191273119Z",
  "partialApproval": {
    "requestedAmount": 60,
    "requestedCurrency": "EUR"
  },
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "iDeal",
      "data": {
        "bic": "INGBNL2A"
      },
          "paymentTokenId": "6e4019f5b0984e289ee786bc66e29f00"
    }
  },
  "merchantTransactionId": "<merchantTransactionId>",
}
Example /payments Webhook Transaction with status=DECLINED
{
  "authorizingEntityId": "<authorizingEntityId>",
  "processingEntityId": "<processingEntityId>",
  "buyerId": "JohnSmith12443",
  "paymentId": "17d87cb814df4b979ed116b8b5efa45d",
  "version": "2.0",
  "amount": 10.5,
  "currency": "EUR",
  "transactionType": "Sale",
  "result": {
    "status": "declined",
    "errors": {
      "code": "8400.9999",
      "reason": "Generic Decline"
    }
  },
  "timeStamp": "2026-01-14T10:37:20.478363632Z",
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "iDeal",
      "data": {
        "bic": "ABNANL2A"
      },
      "paymentTokenId": "d2f5ebe7cd2d4d44945659df673d9e13"
    }
  }
}

Payout (Withdrawal) Flow

To initiate a payout with iDEAL, submit a request using one of the following methods:

  • Include the paymentOption,alternativePaymentMethod and all mandatory parameters as listed in the Payment (Deposit) Flow section of this document.

OR

  • Include the paymentToken.paymentTokenId, which uses a stored Alternative Payment Method (APM) account, with the associated buyerDetails.buyerID for the payment token.
Example /payouts Request Using paymentOption.alternativePaymentMethod
{
  "processingEntityId": "<processingEntityId>",
  "amount": 60,
  "currency": "EUR",
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "iDeal"
    }
  },
  "deviceDetails": {
    "ipAddress": "145.89.23.67"
  },
  "buyerDetails": {
    "buyerId": "NL-BUYER-456",
    "firstName": "Sven",
    "lastName": "De Vries",
    "companyName": "Holland Commerce BV",
    "locale": "nl-NL",
    "dateOfBirth": "1988-03-22",
    "email": "[email protected]",
    "phone": "+31-612345678",
    "billingAddress": {
      "state": "Noord-Holland",
      "city": "Amsterdam",
      "zip": "1012AB",
      "countryCode": "NL"
    },
    "shippingAddress": {
      "sameAsBilling": true
    }
  }
}
Example /payouts Response Using paymentOption.alternativePaymentMethod
{
    "processingEntityId": "<processingEntityId>",
    "amount": 60,
    "currency": "EUR",
    "isMoto": true,
    "paymentOption": {
        "alternativePaymentMethod": {
            "name": "iDeal"
        }
    },
    "buyerDetails": {
        "buyerId": "test1233ssw2",
        "firstName": "John",
        "lastName": "JSmith",
        "companyName": "Nuvei Corp",
        "locale": "bg-BG",
        "dateOfBirth": "1978-01-01",
        "email": "[email protected]",
        "phone": "+1234567889",
        "billingAddress": {
            "state": "TX",
            "city": "Austin",
            "zip": "78652",
            "countryCode": "NL"
        },
        "shippingAddress": {
            "sameAsBilling": true
        }
    }
}
Example /payouts Request Using paymentToken.paymentTokenId

This method uses a previously stored APM account via a payment token.

{
  "processingEntityId": "<processingEntityId>",
  "amount": 60,
  "currency": "EUR",
  "paymentOption": {
    "paymentToken": {
      "paymentTokenId": "<paymentTokenId>"
    }
  },
  "deviceDetails": {
    "ipAddress": "145.89.23.67"
  },
  "buyerDetails": {
    "buyerId": "NL-BUYER-456",
    "firstName": "Sven",
    "lastName": "De Vries",
    "companyName": "Holland Commerce BV",
    "locale": "nl-NL",
    "dateOfBirth": "1988-03-22",
    "email": "[email protected]",
    "phone": "+31-612345678",
    "billingAddress": {
      "state": "Noord-Holland",
      "city": "Amsterdam",
      "zip": "1012AB",
      "countryCode": "NL"
    },
    "shippingAddress": {
      "sameAsBilling": true
    }
  }
}

User Experience

Production – Mobile Browser and Banking App Payment (Payment Page Integration)

  1. On the payment page, the user selects the iDEAL payment method.
  2. The user is redirected to the iDeal website where the user scans the QR code directly with a banking app or manually selects the bank.
  3. The user proceeds to the next screen where the user selects a preferred bank from the bank list.
  4. The user is redirected to the online bank to complete the deposit.

    The user-interface differs per bank. Examples from the Revolut user interface are used for this section of the document.

  5. The user logs into to the bank account.
  6. The payment details are displayed and the user authorizes the payment.
  7. The user confirms the payment on the mobile app.
  8. The user is redirected to the merchant screen which displays a confirmation message.

Sandbox – Desktop Browser and Payment

  1. On the payment page, the user selects the iDEAL payment method.
  2. The user is redirected to the iDeal website where the user scans the QR code directly with a banking app or manually selects a bank.
  3. The user continues to the next screen and then from the bank list selects a preferred bank.

    For testing purposes, use the test bank ‘TESTNL2A’.


  4. The user presses a test simulation option.
  5. The user is redirected to the merchant screen which displays a confirmation message.

Testing

The merchant should contact Nuvei to complete the deposit testing.

Presentation

  • The iDEAL payment method must be presented in the list of payment methods in such a way that it receives at least the same amount of attention as other payment methods.
  • The iDEAL logo can be found here: https://www.ideal.nl/bedrijven/logos/ and it should be used according to the manual: https://www.ideal.nl/cms/files/Handleiding_iDEAL_logo.pdf
    • In cases where the iDEAL logo cannot be displayed at the required size on a mobile device, the mandatory free space of 15px around the logo may be reduced to accommodate the requirements of the mobile device.
  • If merchant has the iDEAL bank’s selection in place on its own environment, the following rules apply:
    • After selection by the Consumer of the bank, the Consumer should be immediately redirected to the Issuer redirectURL.
    • All iDEAL banks must be shown in a list (e.g. dropdown list or list of radio buttons) in alphabetic order.
    • The list should be accompanied by the instruction phrase “Kies uw bank” (UK: “Choose your bank”). In case of an HTML <SELECT>, the first element in the list states this instruction phrase and is selected by default (to prevent accidental bank selection).
    • It is not allowed to exclude or grey out any active banks from the banks list. When a new bank is added, the banks list must be updated within one month (preferably earlier).
    • The merchant may preselect a bank, but only to allow for an improved user experience (e.g. if the Consumer has previously initiated an iDEAL payment with a specific bank selected).
    • The Consumer must however always be offered the possibility to alter the preselected bank.

    Appendix

    The following values are accepted for BIC:

    Bank Name BIC
    ABN AMRO ABNANL2A
    ASN Bank ASNBNL21
    Bunq BUNQNL2A
    ING INGBNL2A
    Knab KNABNL2H
    N26NTSBDEB1
    Nationale-Nederlanden (NN)NNBANL2G
    Rabobank RABONL2U
    RegioBank RBRBNL21
    RevolutREVOLT21
    SNS BankSNSBNL2A
    Triodos Bank TRIONL2U
    Van Lanschot BankiersFVLBNL22
    YoursafeBITSNL2A
Last update iconLast modified March 2026