Bank Transfer (and Wallet) Deposit Returns

When PXP Financial is notified by the Bank of a return or cancellation of an already processed Offline Bank Transfer Deposit, a new payment of method "BankTransferDepositReturn" is created.

The following method IDs are covered in this section:

Payment method interaction type: Offline Execution without any user interaction (see Interaction Types).

📘

Bank Transfer Deposit Returns can apply to multiple payment methods

The information below is applicable to all payment methods in the table above. Please take this into consideration for the details provided in the handlePaymentStateChangedNotificationRequest.payment.paymentMethod collection in the sample Notification below and adapt your integration accordingly.

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 for Bank Transfer Deposit Return in ReturnedProvider state:

<?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 xmlns:="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
    <merchantID>KalixaAcceptDEMO</merchantID>
    <shopID>KalixaAcceptDEMO</shopID>
    <paymentMethod>
      <key>239</key>
      <value>BankTransferDepositReturn</value>
    </paymentMethod>
    <merchantTransactionID>15c727a2-9739-4cbd-bb29-0706d8f21066-226</merchantTransactionID>
    <paymentID>b5439f7d-2e08-4f6d-a913-95e498fc66a0</paymentID>
    <userID>277b2743-df05-498f-a6c3-eb5d02</userID>
    <paymentProvider>
      <key>90</key>
      <value>Envoy</value>
    </paymentProvider>
    <amount currencyCode="EUR">50.0000</amount>
    <creationType>
      <key>6</key>
      <value>Provider</value>
    </creationType>
    <state>
      <id>239c6477-973e-443c-9ba1-d227d43ccbe8</id>
      <definition>
        <key>279</key>
        <value>ReturnedByProvider</value>
      </definition>
      <createdOn>2016-11-21T09:47:34.437</createdOn>
      <paymentStateDetails xsi:nil="true" />
    </state>
    <isExecuted>true</isExecuted>
    <baseAmount currencyCode="EUR">50.0000</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>d8b61956-0862-45c5-9878-2a22322ee811</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentID</key>
        <value>317082f3-8062-42f3-b8b8-42c551f50e1c</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMerchantTransactionID</key>
        <value>ShTest_ECMC_1811_03</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodID</key>
        <value>23</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodName</key>
        <value>BankTransferDeposit</value>
      </detail>
    </paymentDetails>
    <paymentAccount>
      <paymentAccountID>0</paymentAccountID>
    </paymentAccount>
  </payment>
</handlePaymentStateChangedNotificationRequest>

👍

Linking a Deposit Return notification to the original Deposit Payment

The original Deposit to which a Deposit Return is related will be provided in the standard notification through the following details in the handlePaymentStateChangedNotificationRequest.payment.paymentDetails collection:
OriginalPaymentID
OriginalPaymentMerchantTransactionID
OriginalPaymentMethodID
OriginalPaymentMethodName

Notifications for Backwards Compatibility only

🚧

Payment Methods for which backwards-compatibility does not apply

The information in the following section only applies to a limited number of payment methods, detailed in the table below. The following methods are not covered:
EPSDeposit
DirectEBankingDeposit

For these methods, the Notification format in the first section above only, will apply.

The following methods are covered by this section:

Previous Process

Previously Bank Transfer Deposit Return payments were not standalone payments, but were represented only by the Cancelled (113) state of the original Bank Transfer Deposit payment. So a "normal" Bank Transfer Deposit reached the DepositedByProvider (29) state when the deposits got executed, and after that the same payment used to get moved to Cancelled (113)) state when it was returned by the bank. Respectively, the notification triggered for Cancelled (113) state contained the original PaymentID, and the Cancelled (113). This is different compared to the processing described above where there is a new separate payment for the Return, and the notification is for the Return payment using the ReturnedByProvider (279) state.

Possible issues for merchants with the new process

So in the new process, when a new Bank Transfer Deposit Return is created and notified to the merchant, the notification will contain the identifiers of the Return, which are different from those of the original Deposit (contained in OriginalPaymentID, OriginalPaymentMerchantTransactionID, OriginalPaymentMethodID and OriginalPaymentMethodName details). Moreover, the notified state is different to what was previously notified, having been Cancelled (113) and now being ReturnedByProvider (279).

This will cause issues for merchants who are not able to prepare their systems for the new notification format. Therefore PXP Financial will optionally offer a workaround notification option for the newly created Bank Transfer Deposit Return.

Temporary Workaround for new process

Instead of sending a notification with the information of the newly created Bank Transfer Deposit Return, PXP Financial will send a fake notification retaining the original format. This simulates the existing behaviour for the original Bank Transfer Deposit, as if it is in the Cancelled (113) state.

See below for more information and important notes on the limitations of this.

❗️

Workaround: Limitations and Warnings

When a new Return payment is created, the Payment ID, Merchant Transaction ID and Payment Method key and value notified to the merchant will be those of the original Deposit payment.

This is actually not correct, and if this notified payment is searched for using the [getpayments reference] method, only the original Deposit will be returned, and it will be in a completely different state than that which was notified (Cancelled(113)).

This means that the new Deposit Return will not identifiable by the information in the workaround notification, and can only be viewed in the Merchant Reconciliation or Settlement Reports, or directly in the Front-end Admin Interface by using a link in the original Deposit.

Due to these limitations, use of this approach is strongly discouraged.

Please note that this is a temporary measure which will be decommissioned and only made available for a limited period of time for merchants who cannot change their listener in the required time period. PXP Financial strongly recommends that merchants prepare for the new notification as soon as possible.

Example handlePaymentStateChangedNotificationRequest for Bank Transfer Deposit Return in ReturnedProvider state (original Notification format):

<?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 xmlns:q1="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
    <merchantID>KalixaAcceptDEMO</merchantID>
    <shopID>KalixaAcceptDEMO</shopID>
    <paymentMethod>
      <key>23</key>
      <value>BankTransferDeposit</value>
    </paymentMethod>
    <merchantTransactionID>26c757a2-9769-4cbd-bb29-0706d8f21066-223</merchantTransactionID>
    <paymentID>317082f3-8062-42f3-b8b8-42c551f50e1c</paymentID>
    <userID>277b2743-df05-498f-a6c3-eb5d02</userID>
    <paymentProvider>
      <key>90</key>
      <value>Envoy</value>
    </paymentProvider>
    <amount currencyCode="EUR">50.0000</amount>
    <creationType>
      <key>6</key>
      <value>Provider</value>
    </creationType>
   <state>
      <id>239c6477-973e-443c-9ba1-d227d43ccbe8</id>
      <definition>
        <key>113</key>
        <value>Cancelled</value>
      </definition>
      <createdOn>2016-11-21T09:47:34.437</createdOn>
      <paymentStateDetails xsi:nil="true" />
    </state>
    <isExecuted>true</isExecuted>
    <baseAmount currencyCode="EUR">50.0000</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>481720</value>
      </detail>
    </paymentDetails>
    <paymentAccount>
      <paymentAccountID>db66a7e0-9e85-47e2-8bc6-e6c34bef273c</paymentAccountID>
    </paymentAccount>
  </payment>
</handlePaymentStateChangedNotificationRequest>