docs(sandbox): document the late-return account suffix - #1052
Closed
ls-bolt[bot] wants to merge 1 commit into
Closed
ls-bolt[bot] wants to merge 1 commit into
ls-bolt[bot] wants to merge 1 commit into
Conversation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Adds suffix 006 to the transfer pattern table: a deposit that settles and completes, then is returned about 30 seconds later. The existing table stopped at 005, so there was no documented way to test money arriving and then being taken back. Names the failure reason a returned payout now reports on the quote table's 005 row, and says which table applies to which account role, since 006 means a late inbound return for a funding account and a user cancellation for a quote destination. Co-Authored-By: akanter <akanter@users.noreply.github.com>
ls-bolt
Bot
force-pushed
the
09-23-sandbox-late-return-suffix
branch
from
September 23, 2026 00:40
af5c4fc to
3a52ea5
Compare
akanter
added a commit
that referenced
this pull request
Sep 30, 2026
…ix (#1054) ## Summary The sandbox suffix tables had no documented way to test the case that most often surprises an integration: money that arrives, settles, looks final, and is then taken back by the originating bank. Adds **`009`** to the quote patterns as a **source-side** suffix. When a quote pulls funds from an external account ending in `009`, the pull settles and the transaction completes. About 30 seconds later the originating bank returns it, the credited balance is taken back, and the transaction moves to `FAILED`. The note explains why that ordering matters: the deposit completes first, so any logic treating a completed incoming payment as final runs before the return arrives. It also names the two webhooks you receive, in order: `INCOMING_PAYMENT.COMPLETED`, then `INCOMING_PAYMENT.FAILED`. Embedded Wallet destinations are excluded, since sandbox does not simulate the return for them. It is a new number because every quote suffix from `002` to `008` already means something for a payout destination. ## The suffix tables apply to different account roles A single set of suffixes means **two different things** depending on which side of a quote the account sits on, and nothing in the docs said so. - The transfer table covers an account that **funds an incoming transfer**. The quote table covers one that is the **destination of a payout**, plus the `009` source suffix. - Both tables now state their role up front, and the two pages that introduced the transfer table no longer claim it applies "whether you are pushing funds to it or pulling funds from it" — which was wrong for `002`–`005`. - The ramps page renders the quote table too, so the off-ramp destination case is documented where a reader needs it. The error-scenario walkthroughs had the same confusion, using an account as a quote **destination** while labelling it with transfer meanings: - **Ramps "Failed conversions"** — `002` is a quote execution failure (and it fails on the way to settlement, not on the execute call as the page claimed), `003` is the ~6-minute long payment. - **Payouts "Testing Error Scenarios"** — its pull scenario was correct; its two push scenarios were not. Those now use `004` and `005` with the outcomes a payout destination produces. - **Payouts "Sandbox Limitations"** — the instant-settlement bullet now lists each delayed outcome with its table, including `009`. Also names `PAYOUT_RETURNED` on the quote table's `005` row. ## Terminology `009` is described as **"Return after settlement"**, not "late return". "Late return" is a NACHA term for a return sent past the two-business-day window, which generally requires a warranty claim. This suffix simulates a return arriving after the deposit settled, with no deadline modelled either way. ## Test plan Prose and table changes only — no OpenAPI edits, so no rebundle. - Verified the `009` outcome against the sandbox implementation: the suffix is read from the quote's source account, the return fails the transaction, and a quote crediting an internal account emits `INCOMING_PAYMENT.COMPLETED` then `INCOMING_PAYMENT.FAILED`. - Verified the `002`/`003` quote-destination behaviour against the sandbox suffix map. - `mint broken-links` reports the same results with and without this change. Original PR: #1052
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The sandbox transfer pattern table stopped at
005, so there was no documented way to test the case that most often surprises an integration: money that arrives, settles, looks final for days, and is then taken back by the originating bank.Adds
006to the transfer table — the deposit completes, then is returned about 30 seconds later, moving the transaction toREFUNDEDand reversing the credited balance. The note explains why that ordering matters: the deposit completes first, so any logic treating a completed incoming payment as final gets exercised before the return arrives. It also names the two webhooks you receive, in order.Two smaller corrections while here:
005row said "completes then transitions to failed" without naming the reason. It now namesPAYOUT_RETURNED, which is what a returned payout reports.006means different things depending on the account's role — a late inbound return when the account funds a transfer, a user cancellation when it's a quote destination. Both tables now say which one applies, since nothing previously distinguished them.Also updates the inline suffix list on the ramps sandbox page, which enumerates the same values outside the shared snippet.
Test plan
Prose and table changes only — no OpenAPI edits, so no rebundle. The
make lint-markdowntarget fails in this checkout withMissing script: "lint:markdown", which is pre-existing and unrelated to these files.Reviewed how the snippets compose on every page that imports them (
api-reference,payouts-and-b2b,ramps) and kept the cross-reference positional-independent, so it stays correct if a page reorders them.Checked the rendered Mintlify preview: the new
006row and its explanatory note appear in the transfer table, and the updated inline suffix list reads correctly in context.