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.succeeded
ach_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.returned
ach_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.