Handling payment returns

When you are making payments, you should expect to see some percentage get returned. A return can occur for various reasons and usually results in the funds movement being reversed and a notification with additional details. These additional details generate a Return in the Modern Treasury system.

The Modern Treasury Returns object represents a rejection of a returnable. This returnable can be a Payment Order, Reversal, or Incoming Payment Detail. When you are originating payments, your returns will received, as indicated by the return.role field being receiving. If you are originating returns to reject inbound debits or credits, then your return.role will be originating.

Return Webhooks

Return Webhooks corresponding to the return statuses can be received in varying orders depending on when you receive a return from the bank. Here are some important details on the returns lifecycle:

• return.created, payment_order.completed, payment_order.returned, and return.completed webhooks may be received in various orders. See return webhooks and payment order webhooks for more information.
• A Return may be created before or after the Payment Order has already been completed, depending on how early a return file is received and the return code type. The Payment Order’s transition to returned is not affected by the Return’s status. A Payment Order can be moved to returned even if the Return is pending. If the Return is created after the Payment Order is already completed, then the Payment Order will be immediately moved to returned.
• return.completed may be emitted either before or after payment_order.returned

Handling ACH Returns

ACH is a reversible payment rail. A payment can show as completed and still come back days later as a return. This guide covers the return types you'll see, the thresholds your bank partner monitors, and how to build a process that keeps you comfortably under them. It also covers how to think about return risk when you've already paid out funds tied to a payment that later reverses.

1. The Three Thresholds That Matter

NACHA's ACH Network Risk and Enforcement Rule sets return-rate limits that your bank partner is on the hook for. All three are calculated as returns divided by total debits (returns + completed debits) over a rolling 60-day window:

Unauthorized debits are the one to watch most closely.

2. Respond Differently by Return Type

Not all returns mean the same thing. Split your response into two tracks:

Unauthorized debits: R05, R07, R10, R11, R29, R51

• The account holder disputed the debit. Before doing anything else, restrict the ability to withdraw or transact tied to that account or user, then investigate.
• These carry a 60-calendar-day return window, far longer than administrative codes. A debit you consider "settled" after a few days can still come back weeks later.
• R11 is the exception worth handling separately: it means an authorization exists but the debit didn't match its terms (wrong date or wrong amount). It still counts toward the unauthorized rate, but the fix is usually correcting the error and re-debiting under the existing authorization rather than terminating it.

Administrative returns: R02 (account closed), R03 (no account), R04 (invalid account number)

• Usually bad bank details, not fraud. Block further debit attempts on that specific external account and prompt the user to fix or re-link it. There is no need to freeze the whole balance.
• These are good candidates for a single retry once the account information is corrected. Most resolve with an updated routing/account number.

In both cases, subscribe to the payment_order.returned and return.created webhooks, then branch your logic off the return code.

3. Reduce Returns Before They Happen

1. Verify external accounts before debiting. Microdeposits, Plaid, or a zero-dollar prenote all reduce administrative returns from bad account data.
2. Watch for account-type edge cases. Some verification providers return tokenized account numbers for certain specialty account types (e.g., attorney trust/IOLTA accounts) that can't actually ride the ACH network. These will bounce with an Invalid Account Number Structure return no matter how many times you retry. If you serve account types like this, add a manual or hosted account-entry fallback rather than relying on automated verification alone.
3. Ramp new debit flows gradually as you get to know your customers.
4. Keep Counterparty records linked to every External Account. This is what lets Notification of Change (NOC) updates apply automatically instead of the payment simply failing.

4. Proof of Authorization for ACH Debits

A properly documented authorization is your best defense against unauthorized-debit returns (R05, R07, R10, R11, R29, R51), and it is what your bank partner will ask to see if one is disputed.

What every ACH debit authorization needs (consumer debits)

The authorization must be clearly identifiable as an ACH debit authorization, in plain terms, and must capture:

• Whether it's a single, recurring, or standing authorization
• The amount, or how the amount will be determined
• The timing: start date, and frequency/number of debits
• The consumer's name
• The account to be debited (routing + account number)
• The date the consumer authorized it

Recurring and standing authorizations must also state how the consumer can revoke, and (for recurring) give at least 10 days' notice before any change in amount.

In all cases: give the consumer a copy, and retain the authorization for 2 years after it ends. WEB debits require account validation; business (CCD) debits only require an agreement, not the full element set above.

5. Notification of Change (NOC) Isn't a Return

A NOC means the payment succeeded. The bank is just flagging that something on the account (routing number, account number, transaction code) needs correcting for next time. It shows up as a $0.00 Return object with a C0x code and a corrections field.

Modern Treasury automatically applies the correction to the External Account, so future payments route correctly without any action from you. Worth a periodic review of your NOC log, but it's not something that needs an incident response.

6. Collect, Disburse, Then Get Returned: Managing Pass-Through Risk

This pattern comes up for any platform that receives a payment, takes a fee, and pays out the remainder before the original payment has had time to settle for good, such as marketplaces, broker-dealer commission flows, and disbursement platforms. The risk: the incoming payment reverses after you've already paid someone else with it.

A few things to build in given that:

• Treat incoming ACH as provisional until the return window has passed. Track an "available" balance separately from a "settled" one in your own ledger, rather than treating a completed payment as final immediately.
• Remember the window is asymmetric: administrative returns (bad account details) surface within 2 banking days, but unauthorized-debit returns (R05, R07, R10, R11, R29, R51) can land up to 60 calendar days later. If the incoming payment was a debit you originated against the payer's account, size your hold to the risk category, not just the shortest case.
• Hold back a reserve, or delay the downstream payout, for a defined period before releasing the full amount, long enough to cover your realistic return exposure for that payment type.
• Subscribe to return webhooks and reconcile at the sub-account level in real time, so a returned payment surfaces before you've relied on it rather than after.
• Decide your recovery path before you need it: reserve draw-down, clawback terms with the downstream payee, or absorbing it as a cost of doing business. This is a policy decision on your side, not a system behavior.

7. Reference Docs

• ACH Return Risk Thresholds
• ACH Return Codes
• Notification of Change (NOC)
• Return Webhooks