Bancontact/Mister Cash Deposit (via WorldPay)
Payment Method Bancontact, formerly known as Mister Cash till April 2016, is the market leader in electronic payments in Belgium.
The following method IDs are covered in this section:
| ID | Name | Credit/Debit State | Reversal State |
|---|---|---|---|
| 112 | MisterCashDeposit | DepositedByProvider (13) |
Payment method interaction type: Redirection to External Payment Provider (see Interaction Types).
After a payment has been initiated by PXP Financial with provider Worldpay, users are redirected to Worldpay and then to a local service provider (paybox.net) and the users bank`s 3DSecure page.
Redirect Integration
This payment method is supported in the PXP Financial cashier.
Backend2BackendIntegration
There are no specific PaymentAccountData as payment account data are enter after the user´s redirect.
The following parameters can be provided in initiatePaymentRequest.specificPaymentData:
| key (value type, account type, required) | value |
|---|---|
| PaymentProviderID (Int, required) | Value 90 for provider Worldpay (formerly known as Envoy). |
| EmailAddress (String, required) | User eMail address |
| UserFirstname (String) | User first name |
| UserLastname (String) | User last name |
| AddressLine1 (String) | User address line 1 |
| AddressLine2 (String) | User address line 2 |
| UserCity (String) | User city |
| UserPostalCode (String) | User postal code |
| UserCountry (String) | User country |
| MerchantNotificationUrl (String, conditional) | The URL to redirect users back to. The field is required when at least one of SucessPageUrl, ErrorPageUrl or CancelPageUrl is missing. |
| SuccessPageUrl (String, conditional) | The URL to redirect user in case of successful payment. Required only if MerchantNotificationUrl is missing. |
| ErrorPageUrl (String, conditional) | The URL to redirect user in case of unsuccessful payment Required only if MerchantNotificationUrl is missing. |
| CancelPageUrl (String, conditional) | The URL to redirect user in case of cancellation Required only if MerchantNotificationUrl is missing. |
| PendingPageUrl (String) | The URL to redirect user in case of pending payment |
| HomePageUrl (String) | The URL of merchant |
| LanguageCode (String, required) | The language of the user on the merchant side, used for localizing the UI displayed to the user. It has to be "NL". |
Example initiatePaymentRequest`` with *MerchantNotificationUrl:
<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing">
<merchantID>YourMerchantID</merchantID>
<shopID>YourShopID</shopID>
<merchantTransactionID>1897cbdd-ab15-49fe-a474-bd270ee9490d</merchantTransactionID>
<paymentMethodID>112</paymentMethodID>
<amount currencyCode="EUR">20.00</amount>
<userID>4fd67d11-d12c-46c7-8255-d6a228</userID>
<userData>
<username>4fd67d11-d12c-46c7-8255-d6a228</username>
<firstname xsi:nil="true"/>
<lastname xsi:nil="true"/>
<currencyCode xsi:nil="true"/>
<languageCode xsi:nil="true"/>
<email xsi:nil="true"/>
<address xsi:nil="true"/>
</userData>
<userIP>127.0.0.1</userIP>
<userSessionID>ed790214-18fa-444d-b9e0-f480f8d44a57</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>MerchantNotificationUrl</key>
<value>https://merchantnotification</value>
</data>
<data xsi:type="keyStringValuePair">
<key>EmailAddress</key>
<value>[email protected]</value>
</data>
<data xsi:type="keyStringValuePair">
<key>UserFirstname</key>
<value>John</value>
</data>
<data xsi:type="keyStringValuePair">
<key>UserLastname</key>
<value>Doe</value>
</data>
<data xsi:type="keyStringValuePair">
<key>AddressLine1</key>
<value>Test Avenue 1</value>
</data>
<data xsi:type="keyStringValuePair">
<key>UserCity</key>
<value>Brussels</value>
</data>
<data xsi:type="keyStringValuePair">
<key>UserPostalCode</key>
<value>1234</value>
</data>
<data xsi:type="keyStringValuePair">
<key>UserCountry</key>
<value>Belgium</value>
</data>
<data xsi:type="keyIntValuePair">
<key>PaymentProviderID</key>
<value>90</value>
</data>
</specificPaymentData>
</initiatePaymentRequest>
Example initiatePaymentResponse - with *MerchantNotificationUrl:
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing">
<payment xsi:type="paymentWithPaymentAccount" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<merchantID>YourMerchantID</merchantID>
<shopID>YourShopID</shopID>
<paymentMethod>
<key>112</key>
<value>MisterCashDeposit</value>
</paymentMethod>
<merchantTransactionID>1897cbdd-ab15-49fe-a474-bd270ee9490d</merchantTransactionID>
<paymentID>7978012e-7d5f-4cb7-acf8-2e7efcb66b9c</paymentID>
<userID>4fd67d11-d12c-46c7-8255-d6a228</userID>
<paymentProvider>
<key>90</key>
<value>Envoy</value>
</paymentProvider>
<amount currencyCode="EUR">20.00</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>32c5f245-00cb-486b-9de7-6cdba8922a99</id>
<definition>
<key>30</key>
<value>RedirectURLCreated</value>
</definition>
<createdOn>2012-10-08T08:30:32.0386388Z</createdOn>
<description>http://test.envoytransfers.com/?tokenID=541d1cdf-3a53-4b20-8cde-0b488f1447a8</description>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>RedirectionUrl</key>
<value>http://test.envoytransfers.com/?tokenID=541d1cdf-3a53-4b20-8cde-0b488f1447a8</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">20</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>UserFirstname</key>
<value>John</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>UserLastname</key>
<value>Doe</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>Token</key>
<value>541d1cdf-3a53-4b20-8cde-0b488f1447a8</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>D4453</value>
</detail>
</paymentDetails>
<paymentAccount>
<paymentAccountID>0</paymentAccountID>
</paymentAccount>
</payment>
</initiatePaymentResponse>
Possible payment states in 'initiatePaymentResponse`:
| Payment States | Description |
|---|---|
| RedirectURLCreated (30) | OK state; Redirect user to the URL. |
| DuplicatePaymentValidationFailed (369) | The payment with same merchantTransactionID already exists. |
| InitiateErrorReportedByProvider (4) | Error state; Provider reported error when trying to initiate payment. |
Following field is returned in paymentDetails of InitiatePaymentResponse:
| Field name | Description |
|---|---|
| Token | Envoy (Worldpay) ID. An unique URL-encoded string. |
Error Codes
| ProviderResponseCode | ProviderResponseMessage |
|---|---|
| -100 | An unexpected error occurred |
| -101 | Unexpected system error |
| -103 | The operation timed out |
| -200 | Authentication failed |
| -519 | Invalid epacsReference |
| -520 | -epacsReference could not be found |
| -800 | There was a problem processing the payment instructions |
| -835 | BankCode field cannot exceed 50 characters in length |
| -836 | AccountNumber field cannot exceed 255 characters in length |
| -837 | AccountPassword field cannot exceed 255 characters in length |
| -838 | PaymentChannel field cannot exceed 50 characters in length |
| -839 | LanguageCode field should be 2 characters in length |
| -840 | FirstName field cannot exceed 50 characters in length |
| -841 | LastName field cannot exceed 50 characters in length |
| -842 | Phone field cannot exceed 20 characters in length |
| -843 | Address1 field cannot exceed 100 characters in length |
| -844 | Address2 field cannot exceed 100 characters in length |
| -845 | City field cannot exceed 50 characters in length |
| -846 | State field cannot exceed 50 characters in length |
| -847 | Customer Country field should be empty or 2 characters in length |
| -848 | Postcode field cannot exceed 20 characters in length |
| -849 | CustomerRef field cannot exceed 50 characters in length |
| -841 | LastName field cannot exceed 50 characters in length |
| -842 | Phone field cannot exceed 20 characters in length |
| -843 | Address1 field cannot exceed 100 characters inlength |
| -844 | Address2 field cannot exceed 100 characters in length |
| -845 | City field cannot exceed 50 characters in length |
| -846 | State field cannot exceed 50 characters in length |
| -847 | Customer Country field should be empty or 2 characters in length |
| -848 | Postcode field cannot exceed 20 characters in length |
| -849 | CustomerRef field cannot exceed 50 characters in length |
| -868 | Authentication field is required |
| -869 | Username field is required |
| -870 | Password field is required |
| -871 | OneClickServiceInfo field is required |
| -872 | ServiceName field is required |
| -873 | ServiceName field failed validation check |
| -874 | PaymentData field is required |
| -875 | CustomerRef field is required |
| -876 | Country field is required |
| -877 | Country field should be 2 characters in length |
| -878 | Country field failed validation check |
| -879 | Amount and ReceiveAmount should be zero or a positive value |
| -880 | Only one of Amount or ReceiveAmount fields should have a value |
| -881 | Currency field is required |
| -882 | Currency field should be 3 characters in length |
| -883 | Currency field failed validation check |
| -884 | ReceiveCurrency field is required |
| -885 | ReceiveCurrency field should be 3 characters in length |
| -886 | ReceiveCurrency field failed validation check |
| -887 | CustomerData field is required |
| -888 | Email field is required |
| -889 | Email field failed validation check |
| -890 | Email field should be between 5 and 255 characters in length |
| -891 | SuccessUrl field is required |
| -892 | CancelUrl field is required |
| -893 | ErrorUrl field is required |
| -894 | CustomerLevel field cannot exceed 50 characters in length |
| -895 | CustomerId field cannot exceed 50 characters in length |
| -896 | ServiceName field cannot exceed 50 characters in length |
| -897 | successUrl field cannot exceed 300 characters in length |
| -898 | cancelUrl field cannot exceed 300 characters in length |
| -899 | errorUrl field cannot exceed 300 characters in length |
Notifications
The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.
The final execution status about the payment will come within a payment state change notification to the merchant.
The possible payment states are listed below:
| Payment States | Description |
|---|---|
| RefusedByProvider (100) | Error state, payment was not accepted by provider; redirect user to ErrorPageUrl |
| DepositedByProvider (29) | Success state; Payment has been executed |
| QueryPaymentStateCommunicationErrorOccurred (321) | Error state; Communication error with provider occurred. |
| Cancelled (113) | Payment reversal state |
Example handlePaymentStateChangedNotificationRequest:
Updated almost 6 years ago