Introduction

iDEAL is a reliable and secure e-payment solution, which enables customers to pay by instant bank transfer. Customers can make payments either with a mobile banking app or by using the online banking environment of their own bank.

iDEAL holds the market leading position for online payment methods in the Netherlands, and is supported by all major Dutch banks.

Supported Countries

• Netherlands

Supported Currencies

• EUR

Payment (Deposit) Flow

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.

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',

User Experience

Desktop Browser and Payment

1. The user is redirected to the iDEAL page.
   
2. The user presses Select your bank and selects the bank.
   
3. The user is redirected to the bank’s website.
   The user experience varies according to bank. An example of the ABN AMRO bank user experience appears below.
4. The user enters their account information.
5. The user enters their confirmation code.
   
6. The user authorizes the payment.
   
7. The user confirms the payment.
   A confirmation is displayed.

Desktop Browser and Mobile Banking App Payment

1. The user is redirected to the iDEAL page.
   
2. The user opens the banking application and taps Scan QR.
   The user experience varies according to bank. An example of the 123 Bank user experience appears below.
   
3. The user scans the QR code on the iDEAL page.
   
4. The user logs in to the banking application.
   
5. The user confirms the payment.
   
   A confirmation is displayed.
   

Mobile Browser and Banking App Payment

1. The user is redirected to the iDEAL page.
   
2. The banking application opens and the user logs in.
   The user experience varies according to bank. An example of the 123 Bank user experience appears below.
   
3. The user confirms the payment.
   
   A confirmation is displayed.

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
N26	NTSBDEB1
Nationale-Nederlanden (NN)	NNBANL2G
Rabobank	RABONL2U
RegioBank	RBRBNL21
Revolut	REVOLT21
SNS Bank	SNSBNL2A
Triodos Bank	TRIONL2U
Van Lanschot Bankiers	FVLBNL22
Yoursafe	BITSNL2A