ACH return flow improvements
When an ACH payin is returned before it is available for a deposit, the current flow will move the payin status from Processing to Succeeded when the ACH return is created (explained here).
The current webhooks that trigger within minutes of each other in this flow are:
payin.succeededach_return.created
This flow has caused confusion if your platform listens to the payin.succeeded webhook to update the status of the payment in your platform and potentially resulting in communication to your merchant of the "successful" payin. But, ultimately it did not succeed and an ACH return was created. The next deposit includes the fees for the payin and the ACH return.
Rainforest will be making the following changes to help you handle this ACH return flow better.
New fields in the payin.succeeded webhook
payin.succeeded webhookIn the payin.succeeded webhook payload, the following fields will be included:
| Field | Type | Description |
|---|---|---|
has_ach_return | boolean | Boolean indicating that the payin has an ACH return. |
ach_return | object | The ACH return details including the ach_return_id and return_code. |
The API contract for these values can be found in the get payin endpoint.
When listening to the payin.succeeded webhook, if the method_type is ACH, then you should check the has_ach_return boolean to know if the payin moved to this status due to an ACH return.
This change will be released on Monday, July 29th.
New Returned payin status
Returned payin statusIn a new version of the Rainforest API coming soon, a new Returned payin status will be available.
In this new flow, when a payin is returned before is it available for a deposit, the payin will move from the status Processing to Returned and will include the fields,has_ach_return and ach_return, to associate this payin to the ACH Return created.
The webhooks that will trigger within minutes of each other in this flow are:
payin.returnedach_return.created
However, if the payin was funded in a previous deposit, the payin will stay in the Succeeded status and an ACH return will be created (explained here). This can occur on late returns when the time frame of the ACH return is after the payin has been deposited to the merchant.
Introducing a new payin status is a breaking change to the Rainforest integration. Therefore, this new status will only be available on the latest Rainforest API Version not yet released.
The release date of the new API version has not been set.