Bank Transfer (and Wallet) Withdrawal Returns

When PXP Financial is notified by the Bank of a return or cancellation of an already processed Bank Transfer Withdrawal, a payment of method "BankTransferWithdrawalReturn" is created.

The following method IDs are covered in this section:

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

📘

Providers for which Bank Transfer (and Wallet) Withdrawal Returns can apply

Citadel
Envoy
NetPay
Skrill
Minerva
GlobalPayments

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 Withdrawal 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>240</key>
      <value>BankTransferWithdrawalReturn</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>24</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodName</key>
        <value>BankTransferWithdrawal</value>
      </detail>
    </paymentDetails>
    <paymentAccount>
      <paymentAccountID>0</paymentAccountID>
    </paymentAccount>
  </payment>
</handlePaymentStateChangedNotificationRequest>

👍

Linking a Withdrawal Return notification to the original Withdrawal Payment

The original Withdrawal for which a Withdrawal Return is identified in the standard notification through the following details in handlePaymentStateChangedNotificationRequest.payment.paymentDetails collection:
OriginalPaymentID
OriginalPaymentMerchantTransactionID
OriginalPaymentMethodID
OriginalPaymentMethodName

Notifications for Backwards Compatibility only

Previous Process

Previously Bank Transfer Withdrawal Return payments were not standalone payments, but were represented only by the ReturnedByProvider (279) state of the original Bank Transfer Withdrawal payment. So a "normal" Bank Transfer Withdrawal reached the WithdrawnByProvider (20) state when the withdrawals got executed, and after that the same payment used to get moved to ReturnedByProvider (279) state when it was returned by the bank. Respectively, the notification triggered for ReturnedByProvider (279) state contained the original PaymentID, and the ReturnedByProvider (279). 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.

Possible issues for merchants with the new process

So in the new process, when a new Bank Transfer Withdrawal 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 Withdrawal (contained in OriginalPaymentID, OriginalPaymentMerchantTransactionID, OriginalPaymentMethodID and OriginalPaymentMethodName details).

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 Withdrawal Return.

Temporary Workaround for new process

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

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

❗️

Workaround: Limitations and Warnings

When a new Withdrawal 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 Bank Transfer Withdrawal.

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

This means that the new Withdrawal 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 Withdrawal.

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 Withdrawal 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>24</key>
      <value>BankTransferWithdrawal</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>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>481720</value>
      </detail>
    </paymentDetails>
    <paymentAccount>
      <paymentAccountID>db66a7e0-9e85-47e2-8bc6-e6c34bef273c</paymentAccountID>
    </paymentAccount>
  </payment>
</handlePaymentStateChangedNotificationRequest>