GuidesAPI ReferenceDiscussions

Ideal Deposit (via Hipay)

Suggest Edits

Payment method Ideal is a popular online banking methods in the Netherlands.

The following method IDs are covered in this section:

IDNameCredit/Debit StateReversal State
111IdealDepositDepositedByProvider (13)

Payment method interaction type: Redirection to External Payment Provider (see Interaction Types).

📘

Ideal Deposit Returns

Refer to Bank Transfer (and Wallet) Deposit Returns for information on how to correctly handle the notifications for Ideal Deposit Returns

Redirect Integration

Currently not supported.

Backend2BackendIntegration

There are no specificPaymentAccountData.

Please provide the user´s firstname and lastname on the user.

specificPaymentData:

key (value type, account type, required)value
SuccessPageUrl
(string)		URL of the merchant´s success page
ErrorPageUrl (string)URL of the merchant´s error page
PendingPageUrl (string)URL of the merchant's pending page
CancelPageUrl (string)URL of the merchant´s cancel page
MerchantNotificationUrl (string)URL that combines Success & ErrorURL
PaymentDescriptionDescription of the payment
CountryCode2 (string, mandatory)CountryCode of the user
PaymentProviderID (Int, optional)Fixed value set to 132.

Example initiatePaymentRequest:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<merchantID>XXX</merchantID>
	<shopID>XXX</shopID>
	<merchantTransactionID>019b9df6-98b3-4f53-8037-ef29844796e2</merchantTransactionID>
	<paymentMethodID>111</paymentMethodID>
	<amount currencyCode="EUR">38.90</amount>
	<userID>3ebb551a-b66f-4030-b75c-fe2229</userID>
	<userData>
		<username>3ebb551a-b66f-4030-b75c-fe2229</username>
		<firstname xsi:nil="true" />
		<lastname xsi:nil="true" />
		<currencyCode xsi:nil="true" />
		<languageCode xsi:nil="true" />
		<email xsi:nil="true" />
		<address>
			<street xsi:nil="true" />
			<houseName xsi:nil="true" />
			<houseNumber xsi:nil="true" />
			<houseNumberExtension xsi:nil="true" />
			<postalCode xsi:nil="true" />
			<city xsi:nil="true" />
			<state xsi:nil="true" />
			<countryCode2>DE</countryCode2>
			<telephoneNumber xsi:nil="true" />
		</address>
		<gender>Male</gender>
		<identificationNumberType xsi:nil="true" />
		<drivingLicenseNumber xsi:nil="true" />
		<drivingLicenseIssuingState xsi:nil="true" />
	</userData>
	<userIP>127.0.0.1</userIP>
	<userSessionID>93183fb4-f5f1-4405-b9fa-5a60394a7e8d</userSessionID>
	<creationTypeID>1</creationTypeID>
	<specificPaymentData>
		<data xsi:type="keyStringValuePair">
			<key>SuccessPageUrl</key>
			<value>https://returnurl.com</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>CancelPageUrl</key>
			<value>http://cancel/?a=b&amp;c=d</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>ErrorPageUrl</key>
			<value>https://errorurl.com</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>MerchantNotificationUrl</key>
			<value>https://merchantnotification</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>HomePageUrl</key>
			<value>http://home/</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>PendingPageUrl</key>
			<value>http://pending/</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>wise description</value>
		</data>
	</specificPaymentData>
</initiatePaymentRequest>

Alternative request with providerID and FirstName, Lastname in specificPaymentData:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
       <merchantID>B2BTestMerchant</merchantID>
       <shopID>150001</shopID>
       <merchantTransactionID>ecb159ee-3ce0-447f-8732-78cfdbbd4e4-0121</merchantTransactionID>
       <paymentMethodID>111</paymentMethodID>
       <amount currencyCode="EUR">94</amount>
       <userID>1233456</userID>
       <userData>
             <username>1233456</username>
       </userData>
       <userIP>127.0.0.1</userIP>
       <userSessionID>aa27a625-1b3d-425a-a689-5431af914cdf</userSessionID>
       <creationTypeID>1</creationTypeID>
       <specificPaymentData>
             <data xsi:type="keyStringValuePair">
                    <key>SuccessPageUrl</key>
                    <value>http://success/?a=b&amp;c=d</value>
             </data>
             <data xsi:type="keyStringValuePair">
                    <key>CancelPageUrl</key>
                    <value>http://cancel/?a=b&amp;c=d</value>
             </data>
             <data xsi:type="keyStringValuePair">
                    <key>ErrorPageUrl</key>
                    <value>http://error/</value>
             </data>
             <data xsi:type="keyStringValuePair">
                    <key>MerchantNotificationUrl</key>
                    <value>https://merchant.com/notification.html</value>
             </data>
             <data xsi:type="keyStringValuePair">
                    <key>HomePageUrl</key>
                    <value>http://home/</value>
             </data>
             <data xsi:type="keyStringValuePair">
                    <key>PendingPageUrl</key>
                    <value>http://pending/</value>
             </data>
             <data xsi:type="keyStringValuePair">
                    <key>UserFirstname</key>
                    <value>Fred</value>
             </data>
             <data xsi:type="keyStringValuePair">
                    <key>UserLastname</key>
                    <value>Flintstone</value>
             </data>
             <data xsi:type="keyStringValuePair">
                    <key>CountryCode2</key>
                    <value>NL</value>
             </data>
             <data xsi:type="keyIntValuePair">
                    <key>PaymentProviderID</key>
                    <value>132</value>
             </data>
       </specificPaymentData>
</initiatePaymentRequest>

Example initiatePaymentResponse:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>XXX</merchantID>
		<shopID>XXX</shopID>
		<paymentMethod>
			<key>111</key>
			<value>IdealDeposit</value>
		</paymentMethod>
		<merchantTransactionID>019b9df6-98b3-4f53-8037-ef29844796e2</merchantTransactionID>
		<paymentID>0439e1aa-5c46-431e-b39a-a696c9f1ed17</paymentID>
		<userID>3ebb551a-b66f-4030-b75c-fe2229</userID>
		<paymentProvider>
			<key>132</key>
			<value>Hipay</value>
		</paymentProvider>
		<amount currencyCode="EUR">38.90</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>4049da46-018a-4bb0-a0a2-1cb491ce1e14</id>
			<definition>
				<key>30</key>
				<value>RedirectURLCreated</value>
			</definition>
			<createdOn>2021-03-12T10:46:46.6567523Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>RedirectionUrl</key>
					<value>https://api.test2.kalixa.com/WebMockProviders/HipayFrontend/Index?orderId=121725&amp;paymentProduct=ideal</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">38.9</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>121725</value>
			</detail>
		</paymentDetails>
	</payment>
</initiatePaymentResponse>

Possible payment states in initiatePaymentResponse:

Payment StatesDescription
RedirectDataCreated (287)OK state; Redirect user to the URL
ProviderCommunicationErrorOccurred (233)Error state; Communication error during payment finalization
InitiateErrorReportedByProvider (4)Error state; Technical error during payment initialization. See below table for list of error codes.
InitiateRequestProviderCommunicationErrorOccurred (325)Error state; Technical error during payment initialization
BlockedByPaymentScoring (202)Error state; Refused by the PXP Financial Risk System
RefusedByPaymentScoring (121)Error state; Refused by the PXP Financial Risk System

Notifications

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.

Example handlePaymentStateChangedNotificationRequest (DepositedByProvider with payment account data):

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>HipayGiropayDepositProviderTesting</shopID>
		<paymentMethod>
			<key>111</key>
			<value>IdealDeposit</value>
		</paymentMethod>
		<merchantTransactionID>b70f1dee-9d61-4339-8f3b-9bd62c8t2</merchantTransactionID>
		<paymentID>d544768a-8b92-4b98-8f95-d58dcfa92f7f</paymentID>
		<userID>954abca7-fedc-40c6-9cf4-4c57fc</userID>
		<paymentProvider>
			<key>132</key>
			<value>Hipay</value>
		</paymentProvider>
		<amount currencyCode="EUR">94.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>0d090f67-1bdb-4649-ac86-5c4a274b7389</id>
			<definition>
				<key>29</key>
				<value>DepositedByProvider</value>
			</definition>
			<createdOn>2021-12-29T15:16:03.867</createdOn>
			<paymentStateDetails xsi:nil="true" />
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">94.0000</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>152697</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>800145032093</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>e4469409-6c0d-4145-a508-9f32914a39d9</paymentAccountID>
			<details>
				<detail xsi:type="keyStringValuePair">
					<key>IBAN</key>
					<value>NL18ABNA0484869868</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountOwner</key>
					<value>Confidence Lead</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>SWIFT</key>
					<value>ABNANL2A</value>
				</detail>
			</details>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest (DepositedByProvider without payment account:

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>HipayIdealDeposit</shopID>
		<paymentMethod>
			<key>111</key>
			<value>IdealDeposit</value>
		</paymentMethod>
		<merchantTransactionID>060bc646-2c59-4be2-8be8-a6a76518ed6d</merchantTransactionID>
		<paymentID>03267f6a-a211-4e85-b465-bd0c34f8c7a0</paymentID>
		<userID>954abca7-fedc-40c6-9cf4-4c57fc</userID>
		<paymentProvider>
			<key>132</key>
			<value>Hipay</value>
		</paymentProvider>
		<amount currencyCode="EUR">94.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>c98bc4f7-d98e-4bfc-844b-03431076a3a5</id>
			<definition>
				<key>29</key>
				<value>DepositedByProvider</value>
			</definition>
			<createdOn>2021-12-29T15:18:59.54</createdOn>
			<paymentStateDetails xsi:nil="true" />
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">94.0000</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>152699</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>388997073285</value>
			</detail>
		</paymentDetails>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest (RefusedByProvider):

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>HipayGiropayDepositProviderTesting</shopID>
		<paymentMethod>
			<key>111</key>
			<value>IdealDeposit</value>
		</paymentMethod>
		<merchantTransactionID>b70f1dee-9d61-4339-8f3b-9bd62c8t3</merchantTransactionID>
		<paymentID>c9d7b748-8cb4-496e-b2f7-fbb2e2f8ee86</paymentID>
		<userID>954abca7-fedc-40c6-9cf4-4c57fc</userID>
		<paymentProvider>
			<key>132</key>
			<value>Hipay</value>
		</paymentProvider>
		<amount currencyCode="EUR">94.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>e1c8dffc-2cab-4649-a331-2921e280d08f</id>
			<definition>
				<key>100</key>
				<value>RefusedByProvider</value>
			</definition>
			<createdOn>2021-12-29T15:17:06.203</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>4000001</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseMessage</key>
					<value>Declined</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">94.0000</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>152698</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>800145032113</value>
			</detail>
		</paymentDetails>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Testing using the PXP Mock

The PXP test system provides a mock page for testing and simulating the provider behaviour.
This can be used for simulating certain test scenarios.

After sending the initiatePaymentRequest, the URL returned will be a URL that redirects to the PXP mock page rather than the provider page.

Example Redirection URL to the PXP mock:

<paymentStateDetails> 
  <detail xsi:type="keyStringValuePair">
    <key>RedirectionUrl</key>
    <value>https://api.test.kalixa.com/WebMockProviders/HipayFrontend/Index?orderId=121725&amp;paymentProduct=ideal</value> 
  </detail>

📘

Testing against provider test system

This mock is provided by PXP test system. It is NOT testing against provider system!
If a merchant wants to test against the provider (Hipay) test system, this needs to be requested to be configured via the PXP Support team. But please note that the below scenarios cannot be simulated with the Provider test system, this is why PXP provides that mock page.

The mock page contains the below listed fields which can be used by the merchant test team to simulate the different cases:

  • successful (DepositedByProvider)
  • refused (RefusedByProvider)

Additionally if values are entered for the optional fields, they will be used and stored on the created IdealDeposit payment and returned to the merchant as part of the handlePaymentStateChangedNotificationRequest. Examples for those requests can be found in the Notifications chapter above.

Field in MockValueDetails
Passwordmandatory
do not change prefilled value, should remain with value signature as shown in the screenshot
IBANoptional
the field is prefilled with a valid IBAN, can be changed, but there will be validation applied in the backend so it must be a valid IBAN to simulate a real case

applicable only if state "completed" is selected in the mock

More Examples of the valid IBANs: NL91ABNA0417164300 NL18ABNA0484869868		If a value is provided, then it will be returned in handlePaymentStateChangedNotificationRequest to the merchant as part of paymentAccount.details
key = IBAN
value = NL18ABNA0484869868 (for example )

Note: this will only be provided if a valid IBAN was inserted on the mock page!
SWIFToptional
applicable only if state "completed" is selected in the mock		If a value is provided, then it will be returned in handlePaymentStateChangedNotificationRequest to the merchant as part of paymentAccount.details
key = SWIFT
value = ABNANL2A (for example )
Account Holder Nameoptional
applicable only if state "completed" is selected in the mock		If a value is provided, then it will be returned in handlePaymentStateChangedNotificationRequest to the merchant as part of paymentAccount.details
key = AccountOwner
value = John Doe (for example )
Reason Codeoptional
applicable only if state "declined" is selected in the mock		In case of a RefusedByProvider scenario, if a value is provided, then it will be returned in handlePaymentStateChangedNotificationRequest to the merchant as part of paymentStateDetails
key = ProviderResponseCode
value = 4000001 (for example )
Reason Messageoptional
applicable only if state "declined" is selected in the mock		In case of a RefusedByProvider scenario, if a value is provided, then it will be returned in handlePaymentStateChangedNotificationRequest to the merchant as part of paymentStateDetails
key = ProviderResponseMessage
value = Declined (for example )
Statecompleted = will simulate a successful payment

declined = will simulate a refused payment		handlePaymentStateChangedNotificationRequest to the merchant will show

if "declined", then state.definition
key = 100
value = RefusedByProvider

if "completed", then state.definition
key = 29
value = DepositedByProvider

📘

Details

  • IBAN, SWIFT and Account Holder Name are stored to the paymentAccount and returned to the merchant only for successful payments; because in case of a refused transaction, the paymentAccount is not created therefore those details cannot be stored

  • Reason Code and Reason Message are stored and returned to the merchant only for refused payments

Example screenshot of the Ideal Deposit mock page, simulating Provider Hipay

1222

Updated almost 2 years ago