Add 'SETTLEMENT_RETURNED' as a `terminal` status when `transaction_settlement_declined` occurs

[nearapogee]

enum--paymentstatus appears to need another status, similar to 'SETTLEMENT_RETURNED', as ACH transactions can move to 'SETTLED' with terminal set to true, then when the bank declines it after settlement, there is now way to tell via the Graphql api that there is a problem with the transaction.

The only way to tell this state is a webhook: https://developers.braintreepayments.com/reference/general/webhooks/transaction/ruby#notification-type-transaction_settlement_declined

We are thankful for the webhook, but it is a bit ironic that the status remains SETTLED even when the transaction is returned and deducted out of Disbursements.

Much thanks!

[yagrawl]

Hi, @nearapogee thanks for the question. I am a developer on the bank payments team at Braintree. I understand your point and I agree that the settled state, even after the transaction has been returned by the bank, is confusing.

From a product perspective, transactions that are disbursed are marked as ‘settled’ which happens to be a terminal state for our transactions. We have considered moving it to settlement_declined after a return but that causes a host of issues in downstream services.

I’ll file a ticket to consider a new state for ACH transactions that are returned after the settled state (like you suggested) but since this problem is unique to ACH and we have a generic state machine for a variety of payment methods that Braintree supports, I can’t make any promises. Unfortunately, at the moment, the webhook is the only way to get notified about returns.