GuidesAPI ReferenceDiscussions
Guides
Start typing to search…

Ideal Deposit (via Hipay)

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

The following method IDs are covered in this section:

ID

Name

Credit/Debit State

Reversal State

111

IdealDeposit

DepositedByProvider (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

PaymentDescription

Description 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 States

Description

  • *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 Mock

Value

Details

Password

mandatory

  • *do not change prefilled value**, should remain with value signature as shown in the screenshot

IBAN

optional
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!

SWIFT

optional
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 Name

optional
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 Code

optional
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 Message

optional
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 )

State

completed = 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 17 days ago