[akanter]

Summary

Adds two fields to AchRailDetails so platforms can tell why an ACH entry came back:

• returnCode: the NACHA return reason code the receiving bank returned the entry under, such as R01 or R10.
• returnCategory: the Nacha return-rate category that code counts toward, ADMINISTRATIVE or UNAUTHORIZED.

railDetails already reports that an entry was returned (status: RETURNED, returnedAt), but not why. Platforms need the code to track their return rate per reason. Nacha sets separate return-rate thresholds for unauthorized returns and administrative returns, so a platform also needs to know which threshold a return counts toward.

Changes

• AchRailDetails.returnCode: an optional string matching ^R[0-9]{2}$, present with returnedAt. It is a pattern-checked string rather than an enum, because NACHA adds codes and clients shouldn't fail to parse a new one.
• AchRailDetails.returnCategory: an optional new AchReturnCategory enum.
  • ADMINISTRATIVE covers R02, R03 and R04.
  • UNAUTHORIZED covers R05, R07, R10, R11, R29 and R51.
  • It is absent for codes in neither category, such as R01 (insufficient funds), which still carry returnCode.
• A changelog entry, and the bank-return lifecycle step now mentions returnCode.
• Rebundled openapi.yaml and mintlify/openapi.yaml.

Both fields are additive and optional, so there is no version bump.

Test plan

• make build
• make lint: 0 errors; warning and info counts unchanged

Requested by @akanter

Original PR: #1190

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Actions	Updated
grid-cards-demo	Ignored	Preview	Oct 20, 2026 12:14pm UTC
grid-flow-builder	Ignored	Preview	Oct 20, 2026 12:14pm UTC
grid-wallet-demo	Ignored	Preview	Oct 20, 2026 12:14pm UTC

[lightspark-bot]

• feat(transactions): add returnCode and returnCategory to ACH railDetails #1196 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[ls-bolt]

Those 64 breaks were the branch being 11 commits behind main, so oasdiff read main's newer agents, config and webhook changes as removals. I restacked onto main in 8134c2ff, and the bundled spec now differs from main only by the additive returnCode/returnCategory fields and the AchReturnCategory enum.

---

🤖 pulsing-zircon-tb-7(#7) | Feedback

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Oct 20, 2026, 12:15 PM

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge.

Summary

Adds optional returnCode and returnCategory fields to AchRailDetails.

• Returned ACH details show the bank’s reason and rate group.

No actionable issues found.

_{Reviews (2) · Last reviewed commit: "docs(transactions): returnCode is always..." · Reviewed by Greptile}

[ls-bolt]

📌 Bolt Status

2026-10-21 06:46:47 UTC — ⚡ Agent pulsing-zircon-tb-10(#10) started

---

Feedback