GuidesAPI ReferenceDiscussions

eCheckSelect DepositReturn (ACHeCheckDepositReturn)

Suggest Edits

Payment Method ACHeCheckDeposit (provider naming Instant Bank Transfer, formerly eCheckSelect) is bank transfer for the US combined with online banking.

The following method IDs are covered in this section:

IDNameCredit/Debit State
352ACHeCheckDepositReturnReturnedByProvider

Payment method interaction type: Notification from External Payment Provider (see Interaction Types).

Redirect Integration

Currently not supported.

Backend2BackendIntegration

PXP is being notified by provider Mazooma in the event of a return or representment.

The following flow is being applied by PXP:

641

The following states can be reached:

Payment stateDescription
ReturnedByProvider (279)This state is set for a return notification from Mazooma with action = D (dispose).

The return code is saved as payment state detail ProviderReturnCode (see below for the list ACH Return Codes).
PendingOnConfirmation (612)This state is set for a return notification from Mazooma with action = R (re-present).

The return code is saved as payment state detail ProviderReturnCode.
The next_action (date) is saved as ExternalDate. The ProviderResponseCode value is "R".

Representment only applies for the return codes R01 (NSF) or R09 (uncollected funds).
ExpiredThis state is set 6 business days after the NextActionDate for payments in state PendingOnConfirmation .

It indicates that a representment has been successful and funds were retrieved by Mazooma from the customer´s bank account.

Return & Representment Process

In the Representment Process Mazooma will attempt to request the payment again if the first attempt has failed. This process is triggered only when the Return Codes are R01 (NSF / Insufficient funds) or R09 (uncollected funds).

📘

R01 / R09 error message descriptions

  • R01: Insufficient Funds
    The available balance is not sufficient to cover the debit transaction.

  • R09: Uncollected Funds
    The available balance is sufficient but there are transactions in the process of collection, bringing the available balance down.

PXP will notify you in the case of an representment with state PendingOnConfirmation. The notification for the state PendingOnConfirmation will include the detail ExternalDate on which the payment will be represented to the bank.

First return - without a representment possibility

If there is a return with return codes other than R01 or R09, then PXP will send a notification for state ReturnedByProvider. This state is final and payments will not be represented. In the state ReturnedByProvider the ExternalDatevalue will be empty.

First return triggering representment

If there is a return with return code R01 (Insufficient Funds) or R09 (Uncollected Funds), the representment process will be triggered by Mazooma:

  • PXP will send a notification for state PendingOnConfirmation with ProviderResponseCode being "R" and the detail ExternalDate. This indicates the payment is being represented and the date when the Pay-In will be represented will be 3 business days after the Return Notification.

  • Mazooma will re-submit payment to bank (1st Representment) on the date indicated.

  • Mazooma recommends that the merchant waits for 5 business days to confirm if the representment was successful. If there is no return from the 1st Representment, then the Pay-In may be considered successfully processed.

Optionally, on configuration PXP will move the payment to state Expired after 6 business days. We move the payment after 6 business days by default as we cannot include US bank holidays into the calculation.

Second representment

  • PXP will send another notification with state PendingOnConfirmation with ProviderResponseCode being "R", meaning another representment is going to happen. The notification will include the date when the Pay-in will be represented. The date will be either the 15th or the last day of the month, whichever comes first. The date will be available in the notification as ExternalDate.

  • Mazooma will re-submit the payment to bank (2nd Representment) on the date indicated in the notification.

  • Mazooma recommends that the Merchant waits for 5 business days to confirm if the representment was successful. If there is no return from the 2nd Representment, then the Pay-In may be considered successfully processed.

Again, optionally PXP will move the payment to state Expired after 6 business days.

Final return after second representment

If there is a return on the 2nd Representment, then the Pay-In is considered as Returned and a notification will be sent with state ReturnedByProvider and ProviderResponseCode being "D" (Disposed). ExternalDate will be empty and a ProviderReturnCode (of R01 or R09) will be provided.

Notifications

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

📘

Notification Details

The notification payment details, such as ExternalDate, can be activated or deactivated, on request from the merchant.

Example handlePaymentStateChangedNotificationRequest for a ReturnedPayment in state PendingOnConfirmation (non-final):

<?xml version="1.0" encoding="UTF-8"?>
<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></merchantID>
      <shopID></shopID>
      <paymentMethod>
         <key>352</key>
         <value>ACHeCheckDepositReturn</value>
      </paymentMethod>
      <merchantTransactionID>89f40798-a22e-4d57-83ac-820b969c897a</merchantTransactionID>
      <paymentID>d61ac9a1-7d39-4f33-8d66-6df82556eb3b</paymentID>
      <userID>077e1a2d-4de0-4bf8-8214-2b48c4</userID>
      <paymentProvider>
         <key>122</key>
         <value>Mazooma</value>
      </paymentProvider>
      <amount currencyCode="USD">22.1100</amount>
      <creationType>
         <key>1</key>
         <value>User</value>
      </creationType>
      <state>
         <id>f0371a2a-9cb0-40dd-96dc-ff9d8a2cf762</id>
         <definition>
            <key>612</key>
            <value>PendingOnConfirmation</value>
         </definition>
         <createdOn>2020-08-10T15:38:42.64</createdOn>
         <paymentStateDetails>
            <detail xsi:type="keyStringValuePair">
               <key>ProviderResponseCode</key>
               <value>R</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
               <key>ProviderReturnCode</key>
               <value>R01</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
               <key>ExternalDate</key>
               <value>20191004</value>
            </detail>
            <detail xsi:type="keyIntValuePair">
               <key>PaymentStateReasonID</key>
               <value>1</value>
            </detail>
         </paymentStateDetails>
      </state>
      <isExecuted>false</isExecuted>
      <baseAmount currencyCode="EUR">16.6100</baseAmount>
      <paymentDetails>
         <detail xsi:type="keyStringValuePair">
            <key>ProviderExternalID</key>
            <value>cb840e24-b74c-4280-8da1-09855ed82e77</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentID</key>
            <value>9b3547ef-34d6-49ed-8b54-fb122be8fb9e</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentMerchantTransactionID</key>
            <value>89f40798-a22e-4d57-83ac-820b969c897a</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentMethodID</key>
            <value>206</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentMethodName</key>
            <value>ACHeCheckDeposit</value>
         </detail>
      </paymentDetails>
      <paymentAccount>
         <paymentAccountID>0</paymentAccountID>
      </paymentAccount>
   </payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest for a ReturnedPayment in state ReturnedByProvider (final!):

<?xml version="1.0" encoding="UTF-8"?>
<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></merchantID>
      <shopID></shopID>
      <paymentMethod>
         <key>352</key>
         <value>ACHeCheckDepositReturn</value>
      </paymentMethod>
      <merchantTransactionID>d99e738b-1249-4cba-87ca-dde9dbe12509</merchantTransactionID>
      <paymentID>f1329468-4695-48da-ab13-1495cf2e92fb</paymentID>
      <userID>ce841264-7497-4532-8d02-af07c7</userID>
      <paymentProvider>
         <key>122</key>
         <value>Mazooma</value>
      </paymentProvider>
      <amount currencyCode="USD">22.1100</amount>
      <creationType>
         <key>1</key>
         <value>User</value>
      </creationType>
      <state>
         <id>5c0f06b6-86d9-43cb-9002-f1c30d233479</id>
         <definition>
            <key>279</key>
            <value>ReturnedByProvider</value>
         </definition>
         <createdOn>2020-08-10T15:43:45.027</createdOn>
         <paymentStateDetails>
            <detail xsi:type="keyStringValuePair">
               <key>ProviderResponseCode</key>
               <value>D</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
               <key>ProviderReturnCode</key>
               <value>R01</value>
            </detail>
         </paymentStateDetails>
      </state>
      <isExecuted>true</isExecuted>
      <baseAmount currencyCode="EUR">16.6100</baseAmount>
      <paymentDetails>
         <detail xsi:type="keyStringValuePair">
            <key>ProviderExternalID</key>
            <value>261013e8-1754-45c9-9832-fd01825b48cc</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentID</key>
            <value>684b3804-b933-435e-877d-044d4a6eb5c9</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentMerchantTransactionID</key>
            <value>d99e738b-1249-4cba-87ca-dde9dbe12509</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentMethodID</key>
            <value>206</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentMethodName</key>
            <value>ACHeCheckDeposit</value>
         </detail>
      </paymentDetails>
      <paymentAccount>
         <paymentAccountID>0</paymentAccountID>
      </paymentAccount>
   </payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest for a eCheckSelectDepositReturn payment in state Expired(final!) - in notification style of Original payment

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest 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></merchantID>
        <shopID></shopID>
        <paymentMethod>
            <key>206</key>
            <value>ACHeCheckDeposit</value>
        </paymentMethod>
        <merchantTransactionID>4e5246e1-2f03-4dfe-ac71-2a8b7d70574f</merchantTransactionID>
        <paymentID>5b4da8d2-a3f0-4e91-81e4-6b612daece3d</paymentID>
        <userID>c5da5f73-47e0-4b52-bb89-1f69f1</userID>
        <paymentProvider>
            <key>122</key>
            <value>Mazooma</value>
        </paymentProvider>
        <amount currencyCode="USD">22.1100</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <state>
            <id>7e17bb7c-b075-40e0-8933-f4580c655fba</id>
            <definition>
                <key>102</key>
                <value>Expired</value>
            </definition>
            <createdOn>2020-12-04T14:31:19.893</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyIntValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">16.6100</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>106202</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalPaymentID</key>
                <value>5b4da8d2-a3f0-4e91-81e4-6b612daece3d</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalPaymentMerchantTransactionID</key>
                <value>4e5246e1-2f03-4dfe-ac71-2a8b7d70574f</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalPaymentMethodID</key>
                <value>206</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalPaymentMethodName</key>
                <value>ACHeCheckDeposit</value>
            </detail>
        </paymentDetails>
    </payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest for a ReturnedPayment in state Expired:

<?xml version="1.0" encoding="UTF-8"?>
<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></merchantID>
      <shopID></shopID>
      <paymentMethod>
         <key>352</key>
         <value>ACHeCheckDepositReturn</value>
      </paymentMethod>
      <merchantTransactionID>e0d2448a-8985-4c72-8efb-003e5e4253da</merchantTransactionID>
      <paymentID>1796cbe1-a673-43d7-932e-7a09bd47d076</paymentID>
      <userID>f1ce030e-9ac2-4980-ae9c-e0e586</userID>
      <paymentProvider>
         <key>122</key>
         <value>Mazooma</value>
      </paymentProvider>
      <amount currencyCode="USD">22.1100</amount>
      <creationType>
         <key>1</key>
         <value>User</value>
      </creationType>
      <state>
         <id>16b72371-5fdb-443a-aafe-205384494a6f</id>
         <definition>
            <key>102</key>
            <value>Expired</value>
         </definition>
         <createdOn>2020-12-10T12:44:16.98</createdOn>
         <description />
         <paymentStateDetails>
            <detail xsi:type="keyIntValuePair">
               <key>PaymentStateReasonID</key>
               <value>1</value>
            </detail>
         </paymentStateDetails>
      </state>
      <isExecuted>false</isExecuted>
      <baseAmount currencyCode="EUR">14.6800</baseAmount>
      <paymentDetails>
         <detail xsi:type="keyStringValuePair">
            <key>ProviderExternalID</key>
            <value>cec0a50b-ed3b-476c-8dd3-680d9be335b5</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentID</key>
            <value>0a5016c5-15e7-44ac-90e0-114a742cb43a</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentMerchantTransactionID</key>
            <value>e0d2448a-8985-4c72-8efb-003e5e4253da</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentMethodID</key>
            <value>206</value>
         </detail>
         <detail xsi:type="keyStringValuePair">
            <key>OriginalPaymentMethodName</key>
            <value>ACHeCheckDeposit</value>
         </detail>
      </paymentDetails>
   </payment>
</handlePaymentStateChangedNotificationRequest>

ACH Return Codes

ACH return codes and definitions commonly used by US financial institutions:

539 539 534

Updated almost 3 years ago