docs: sync documentation with recent OpenAPI schema changes

[claude]

Summary

• Add COLLECTION_FAILED to incoming payment failure reasons in error handling guide
• Document INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED webhook for internal accounts
• Add note pointing to recommended client-held-key flow in session refresh docs

Context

These updates sync the documentation with recent OpenAPI schema changes from the past 24 hours:

• SWIFT pay-in changes added COLLECTION_FAILED failure reason and new webhook type
• Auth session deprecation of encryptedSessionSigningKey in favor of client-held-key flow

Files Changed

File	Change
mintlify/snippets/error-handling.mdx	Added COLLECTION_FAILED incoming failure reason
mintlify/snippets/internal-accounts.mdx	Added INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED webhook mention
mintlify/snippets/global-accounts/managing-sessions.mdx	Added note about client-held-key flow

Test plan

• Verify docs render correctly with make mint
• Confirm new failure reason matches OpenAPI schema
• Confirm webhook type matches OpenAPI schema

🤖 Generated with Claude Code

[vercel]

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

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored		Aug 20, 2026 8:17am
grid-wallet-demo	Ignored		Aug 20, 2026 8:17am

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Aug 20, 2026, 8:18 AM

[greptile-apps]

Greptile Summary

This PR synchronizes Mintlify guidance with recent transaction, webhook, and authentication schema changes.

• Adds the COLLECTION_FAILED incoming-payment reason.
• Documents funding-instruction update webhooks for internal accounts.
• Directs new session-refresh integrations toward client-held keys.

Confidence Score: 4/5

The PR needs the client-held-key documentation link corrected before merging; the cache-refresh and wording concerns are non-blocking.

The new session guidance points readers to an unregistered snippet route rather than the published client-keys page, while the other changes accurately reflect the schema but would benefit from explicit cache invalidation guidance and clearer active phrasing.

Files Needing Attention: mintlify/snippets/global-accounts/managing-sessions.mdx, mintlify/snippets/internal-accounts.mdx, mintlify/snippets/error-handling.mdx

Important Files Changed

Filename	Overview
mintlify/snippets/error-handling.mdx	Adds the schema-backed COLLECTION_FAILED reason, with a minor active-voice violation.
mintlify/snippets/global-accounts/managing-sessions.mdx	Correctly describes the client-held-key model but links to a snippet import path instead of the published page.
mintlify/snippets/internal-accounts.mdx	Adds the valid funding-instructions webhook but leaves the documented caching lifecycle incomplete and uses passive voice.

Prompt To Fix All With AI

### Issue 1
mintlify/snippets/global-accounts/managing-sessions.mdx:44
**Broken client-key documentation link**
When a reader follows the new client-held-key recommendation, the link targets the snippet import path rather than the registered public page, causing navigation to a missing route instead of the session-key instructions.
```suggestion The examples below show the legacy flow with `encryptedSessionSigningKey`. For new integrations, use the recommended [client-held-key flow](/global-accounts/client-keys#client-held-session-key) by sending a compressed `clientPublicKey` (66 hex characters), which avoids the decrypt step entirely.```### Issue 2
mintlify/snippets/internal-accounts.mdx:374
**Missing cache invalidation guidance**
The new webhook guidance does not tell readers to refresh cached `fundingPaymentInstructions`; integrations following the same snippet's caching advice can continue displaying withdrawn or outdated deposit coordinates after receiving this event.
```suggestionYou'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes. When `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` reports new or withdrawn funding instructions, invalidate any cached `fundingPaymentInstructions` and fetch the account again.```### Issue 3
mintlify/snippets/error-handling.mdx:234
**Passive descriptions obscure actors**
The new phrases “funds returned to sender” here and “funding instructions are added or modified” in `internal-accounts.mdx` use passive voice, contrary to the Mintlify writing standard, and obscure who performs these operational actions.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "docs: sync documentation with recent Ope..." | Re-trigger Greptile}

[greptile-apps]

Broken client-key documentation link

When a reader follows the new client-held-key recommendation, the link targets the snippet import path rather than the registered public page, causing navigation to a missing route instead of the session-key instructions.

Suggested change

	The examples below show the legacy flow with `encryptedSessionSigningKey`. For new integrations, use the recommended [client-held-key flow](/snippets/global-accounts/client-keys#client-held-session-key) by sending a compressed `clientPublicKey` (66 hex characters), which avoids the decrypt step entirely.
	The examples below show the legacy flow with `encryptedSessionSigningKey`. For new integrations, use the recommended [client-held-key flow](/global-accounts/client-keys#client-held-session-key) by sending a compressed `clientPublicKey` (66 hex characters), which avoids the decrypt step entirely.

Knowledge Base Used:Mintlify Documentation Site

Prompt To Fix With AI

This is a comment left during a code review.
Path: mintlify/snippets/global-accounts/managing-sessions.mdx
Line: 44
Comment:
**Broken client-key documentation link**
When a reader follows the new client-held-key recommendation, the link targets the snippet import path rather than the registered public page, causing navigation to a missing route instead of the session-key instructions.
```suggestion The examples below show the legacy flow with `encryptedSessionSigningKey`. For new integrations, use the recommended [client-held-key flow](/global-accounts/client-keys#client-held-session-key) by sending a compressed `clientPublicKey` (66 hex characters), which avoids the decrypt step entirely.```**Knowledge Base Used:**[Mintlify Documentation Site](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/mintlify-docs-site.md)---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Missing cache invalidation guidance

The new webhook guidance does not tell readers to refresh cached fundingPaymentInstructions; integrations following the same snippet's caching advice can continue displaying withdrawn or outdated deposit coordinates after receiving this event.

Suggested change

	You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes, and`INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED`when funding instructions are added or modified.
	You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes. When`INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED`reports new or withdrawn funding instructions, invalidate any cached `fundingPaymentInstructions` and fetch the account again.

Prompt To Fix With AI

This is a comment left during a code review.
Path: mintlify/snippets/internal-accounts.mdx
Line: 374
Comment:
**Missing cache invalidation guidance**
The new webhook guidance does not tell readers to refresh cached `fundingPaymentInstructions`; integrations following the same snippet's caching advice can continue displaying withdrawn or outdated deposit coordinates after receiving this event.
```suggestionYou'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes. When `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` reports new or withdrawn funding instructions, invalidate any cached `fundingPaymentInstructions` and fetch the account again.```---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Passive descriptions obscure actors

The new phrases “funds returned to sender” here and “funding instructions are added or modified” in internal-accounts.mdx use passive voice, contrary to the Mintlify writing standard, and obscure who performs these operational actions.

Context Used: mintlify/AGENTS.md (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: mintlify/snippets/error-handling.mdx
Line: 234
Comment:
**Passive descriptions obscure actors**
The new phrases “funds returned to sender” here and “funding instructions are added or modified” in `internal-accounts.mdx` use passive voice, contrary to the Mintlify writing standard, and obscure who performs these operational actions.
**Context Used:** mintlify/AGENTS.md ([source](https://github.com/lightsparkdev/grid-api/blob/main/mintlify/AGENTS.md))
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!