feat(transactions): add returnCode and returnCategory to ACH railDetails

[ls-bolt]

This PR has been claimed. The active PR is now #1196.

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

[mintlify]

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

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Oct 17, 2026, 2:03 AM

[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 17, 2026 2:03am UTC
grid-flow-builder	Ignored	Preview	Oct 17, 2026 2:03am UTC
grid-wallet-demo	Ignored	Preview	Oct 17, 2026 2:03am UTC

[ls-bolt]

@greptile review

[lightspark-bot]

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

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

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge.

Summary

Adds optional returnCode to AchRailDetails so clients can identify why an ACH entry was returned.

• Returned ACH details now show why the bank sent an entry back.

_{Reviews (1) · Last reviewed commit: "feat(transactions): add returnCode to AC..." · Reviewed by Greptile}