docs: describe rule-based accounts in sandbox

[bsiaotickchong]

Summary

Documents rule-based accounts in sandbox. Stacked on #835, which adds the endpoint and the sweep schemas.

No new paths, and no schema changes. Sandbox reuses the same surface: creation goes through POST /internal-accounts, and POST /sandbox/internal-accounts/{accountId}/fund already exists to stand in for a settled deposit. What was missing is a statement of which half of the flow is real, so an integrator knows what a green sandbox run has actually proved.

What changed

Two description blocks, +18 lines total:

• POST /internal-accounts — notes that sandbox platforms can create rule-based accounts, that the account number is generated locally rather than issued by a partner bank, and that funding via the sandbox endpoint stands in for a deposit.
• POST /sandbox/internal-accounts/{accountId}/fund — a "Funding a rule-based account" section: funding triggers the sweep exactly as a settled deposit does, and funding below the corridor minimum rehearses the BELOW_MINIMUM path that returns the deposit and delivers SWEEP.FAILED.

That second one is the point of the change. Below-minimum is the behaviour an integrator is most likely to hit without meaning to, and the one whose consequence — the deposit going back to the payer rather than onward — is least guessable from the happy path.

Edited at source, not in the bundle

openapi.yaml and mintlify/openapi.yaml are bundler output — make build regenerates them from the openapi/ directory. The two description blocks therefore live in their source files:

• openapi/paths/sandbox/sandbox_internal_accounts_{accountId}_fund.yaml
• openapi/paths/internal_accounts.yaml

with both bundles rebuilt. An earlier revision of this PR edited the bundle directly, which would have been silently reverted by the next make build — worth knowing if you review the diff and wonder why three files carry the same prose.

The boundary this draws

Sandbox simulates the API contract and the routing decision, not the banking rails. The quote, the corridor bounds, the destination checks and the webhook are all real; the settlement legs behind them are not, so timings and failure modes that originate at a partner bank cannot be reproduced here.

This is a deliberate boundary rather than a shortfall. The alternative — registering real partner-bank entities for fictional sandbox customers — is precisely what the platform eligibility rules exist to prevent. Everything above the rails genuinely runs: the same rule lookup, balance read, corridor bounds, destination and rail validation, quote path and webhook that production uses.

Original PR: #889

[vercel]

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

2 Skipped Deployments

Project	Deployment	Actions	Updated
grid-flow-builder	Ignored	Preview	Sep 2, 2026 11:46pm UTC
grid-wallet-demo	Ignored	Preview	Sep 2, 2026 11:46pm UTC

[lightspark-bot]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• docs: describe rule-based accounts in sandbox #892 👈 (View in Graphite)
• feat: add rule-based internal accounts and the sweep failure webhook #891
• main

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

[github-actions]

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

chore(internal): regenerate SDK with no functional changes

go

docs(api): document rule-based account funding in sandbox internal account fund

kotlin

docs(api): document rule-based accounts in sandbox internal accounts fund

openapi

docs(api): document rule-based account sweep behavior in sandbox fund method

php

docs(api): add rule-based account funding details to sandbox internal_accounts fund method

python

docs(api): document rule-based account funding in sandbox add_balance method

ruby

docs(api): document rule-based account funding in sandbox internal_accounts

typescript

docs(api): expand sandbox internal_accounts fund method documentation

Edit this comment to update them. They will appear in their respective SDK's changelogs.

✅ grid-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ❗ → test ✅

npm install https://pkg.stainless.com/s/grid-typescript/0d0d32e90f588dadf61ac8b76ee0f62d2181a5b4/dist.tar.gz

✅ grid-openapi studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️

✅ grid-ruby studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

✅ grid-kotlin studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ✅ → lint ✅ → test ❗

✅ grid-go studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@03600548ae34718c7460cc98ec92594f904dbd45

✅ grid-python studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ❗ → test ❗

pip install https://pkg.stainless.com/s/grid-python/df7adc497d7d2bb5e01124000b7eb4bb50545a64/grid-0.0.1-py3-none-any.whl

✅ grid-php studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → lint ✅ → test ✅

✅ grid-cli studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ❗ → lint ❗ → test ❗

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-09-02 23:53:25 UTC

[greptile-apps]

Greptile Summary

This PR expands the OpenAPI descriptions for creating and funding rule-based accounts in sandbox.

• Explains that sandbox account numbers are generated locally and sandbox funding substitutes for a settled deposit.
• Documents successful sweep behavior, the BELOW_MINIMUM path, webhook delivery, and the boundary between simulated API behavior and banking rails.
• Rebuilds both published OpenAPI bundles from the modular source descriptions.

Confidence Score: 4/5

The PR should not merge until the below-minimum guidance identifies the customer’s canonical account, rather than the payer, as the destination of the funds.

The new text contradicts the sweep failure schema and BELOW_MINIMUM webhook example, which consistently describe MOVED_TO_CANONICAL_ACCOUNT and expose canonicalAccountId.

Files Needing Attention: openapi/paths/sandbox/sandbox_internal_accounts_{accountId}_fund.yaml, openapi.yaml, mintlify/openapi.yaml

Important Files Changed

Filename	Overview
openapi/paths/internal_accounts.yaml	Adds sandbox-specific creation and funding guidance consistent with the generated bundles.
openapi/paths/sandbox/sandbox_internal_accounts_{accountId}_fund.yaml	Documents rule-based sweep behavior but incorrectly says below-minimum funds return to the payer instead of moving to the customer’s canonical account.
openapi.yaml	Correctly mirrors the source descriptions, including the inaccurate below-minimum destination.
mintlify/openapi.yaml	Correctly mirrors the generated contract but publishes the same inaccurate below-minimum destination.

Prompt To Fix All With AI

### Issue 1
openapi/paths/sandbox/sandbox_internal_accounts_{accountId}_fund.yaml:17-19
**Below-minimum destination is incorrect**

When an integrator rehearses the `BELOW_MINIMUM` path, this text says the funds return to the payer, but the sweep contract moves them to the customer’s same-currency canonical account using `MOVED_TO_CANONICAL_ACCOUNT` and `canonicalAccountId`, causing the integration to expect a refund state or event that is never produced.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "docs: describe rule-based accounts in sa..." | Re-trigger Greptile}

[ls-bolt]

⚡ Revision log — updated in place, latest first.

Revision 1

• Restacked onto the rebased parent branch; no conflicts of its own.
• Corrected the sandbox funding note: an out-of-corridor balance moves to the customer's canonical account in the same currency, not back to the payer. SWEEP.FAILED carries outcome: MOVED_TO_CANONICAL_ACCOUNT with reason: BELOW_MINIMUM or ABOVE_MAXIMUM, and the rule-based account is left at zero either way.
• make lint clean; bundles regenerated with make build.

[ls-bolt]

⚡ Review ledger

Round 1

1. Sandbox note says a below-minimum balance is returned to the payer, contradicting SweepFailureOutcome → FIXED: ddde7a19 — the note now describes the canonical-account divert and covers ABOVE_MAXIMUM as well.