organize sandbox test case information (#268)

Author: shreyav

mintlify/api-reference/environments.mdx

@@ -11,7 +11,7 @@ import { topLevelProductName } from '/snippets/variables.mdx'
  `https://api.lightspark.com/grid/2025-10-13`
 
 ## Sandbox
-Sandbox enables you to test your integration without making real payments.  In sandbox, we expose sandbox specific APIs to trigger specific test cases like incoming payments.  Additionally you'll find test UMA addresses to simulate different sending scenarios.  For more information, see [Sandbox Testing](../payouts-and-b2b/platform-tools/sandbox-testing).
+Sandbox enables you to test your integration without making real payments.  In sandbox, we expose sandbox specific APIs to trigger specific test cases like incoming payments.  Additionally you'll find test UMA addresses to simulate different sending scenarios.  For more information, see [Sandbox Testing](sandbox-testing).
 
 ## Production
 Production moves real money.  To get access to a production environment, please reach out to your Lightspark contact.

mintlify/api-reference/sandbox-testing.mdx

@@ -0,0 +1,94 @@
+---
+title: "Sandbox Testing"
+description: "Use Grid sandbox magic values to trigger specific API responses"
+icon: "/images/icons/hammer.svg"
+"og:image": "/images/og/og-api-reference.png"
+---
+
+import SandboxExternalAccounts from '/snippets/sandbox-external-accounts.mdx';
+import SandboxBeneficiaryVerification from '/snippets/sandbox-beneficiary-verification.mdx';
+import SandboxTransferPatterns from '/snippets/sandbox-transfer-patterns.mdx';
+import SandboxQuotePatterns from '/snippets/sandbox-quote-patterns.mdx';
+import SandboxUmaAddresses from '/snippets/sandbox-uma-addresses.mdx';
+
+The Grid sandbox environment simulates real payment flows without moving real money. You can control test outcomes using special account number patterns and test addresses.
+
+## Adding external accounts
+
+<SandboxExternalAccounts />
+
+### Beneficiary name verification
+
+<SandboxBeneficiaryVerification />
+
+## Transfer in
+
+In production, internal accounts are funded by sending a bank transfer to the account's payment instructions or by pulling from an external account. In sandbox, you have two options:
+
+### Transfer in from an external account
+
+Use the `/transfer-in` endpoint to pull funds from an external account into an internal account. The external account's number suffix determines the outcome:
+
+<SandboxTransferPatterns />
+
+### Sandbox fund endpoint
+
+Instantly add funds to any internal account using `/sandbox/internal-accounts/{accountId}/fund`:
+
+```bash
+curl -X POST https://api.lightspark.com/grid/2025-10-13/sandbox/internal-accounts/{accountId}/fund \
+  -u "$SANDBOX_CLIENT_ID:$SANDBOX_API_SECRET" \
+  -H "Content-Type: application/json" \
+  -d '{ "amount": 100000 }'
+```
+
+## Creating quotes (cross-currency transfers)
+
+<SandboxQuotePatterns />
+
+### Executing a quote
+
+After creating a quote, you need to fund it to trigger execution. There are two ways to do this in sandbox:
+
+**Prefunded internal account** — If your quote's source is an internal account, fund the account using one of the methods described in [transfer in](#transfer-in), then call the quote execute endpoint to trigger the transaction:
+
+```bash
+curl -X POST https://api.lightspark.com/grid/2025-10-13/quotes/{quoteId}/execute \
+  -u "$SANDBOX_CLIENT_ID:$SANDBOX_API_SECRET"
+```
+
+**Real-time funding via sandbox send** — If your quote uses real-time funding, the quote response includes payment instructions for you to transfer funds to. Use `/sandbox/send` to simulate this payment:
+
+```bash
+curl -X POST https://api.lightspark.com/grid/2025-10-13/sandbox/send \
+  -u "$SANDBOX_CLIENT_ID:$SANDBOX_API_SECRET" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
+    "currencyCode": "USD"
+  }'
+```
+
+## Transferring out funds
+
+Use the `/transfer-out` endpoint to push funds from an internal account to an external account in the same currency. The external account's number suffix controls the outcome using the same patterns as [transfer in](#transfer-in-from-an-external-account).
+
+## Sending to a UMA address
+
+<SandboxUmaAddresses />
+
+### Simulating incoming UMA payments
+
+Use the sandbox receive endpoint to simulate an incoming UMA payment to one of your platform's users:
+
+```bash
+curl -X POST https://api.lightspark.com/grid/2025-10-13/sandbox/uma/receive \
+  -u "$SANDBOX_CLIENT_ID:$SANDBOX_API_SECRET" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "senderUmaAddress": "$success.usd@sandbox.uma.money",
+    "receiverUmaAddress": "$your.user@your.domain",
+    "receivingCurrencyCode": "USD",
+    "receivingCurrencyAmount": 5000
+  }'
+```

mintlify/docs.json

@@ -265,7 +265,8 @@
               "api-reference/environments",
               "api-reference/terminology",
               "api-reference/authentication",
-              "api-reference/webhooks"
+              "api-reference/webhooks",
+              "api-reference/sandbox-testing"
             ]
           },
           {

mintlify/openapi.yaml

@@ -5,7 +5,10 @@ icon: "/images/icons/hammer.svg"
 "og:image": "/images/og/og-payouts-b2b.png"
 ---
 
-import SandboxVpaValidation from '/snippets/sandbox-vpa-validation.mdx';
+import SandboxBeneficiaryVerification from '/snippets/sandbox-beneficiary-verification.mdx';
+import SandboxExternalAccounts from '/snippets/sandbox-external-accounts.mdx';
+import SandboxTransferPatterns from '/snippets/sandbox-transfer-patterns.mdx';
+import SandboxQuotePatterns from '/snippets/sandbox-quote-patterns.mdx';
 
 ## Overview
 
@@ -55,55 +58,11 @@ Alternatively, you can also fund internal accounts using the `/quotes` or `/tran
 
 ### Adding Test External Accounts
 
-The flows for creating external accounts in sandbox are the same as in production.
-However, when creating external accounts in sandbox, you can use special account number patterns to simulate different
-transfer behaviors. The **last 3 digits** of the account number determine the test scenario:
+<SandboxExternalAccounts />
 
-| Last Digits | Behavior | Use Case |
-|-------------|----------|----------|
-| **002** | Insufficient funds | Transfer-in fails immediately |
-| **003** | Account closed/invalid | All transfers fail immediately |
-| **004** | Transfer rejected | Bank rejects the transfer |
-| **005** | Timeout/delayed failure | Transaction stays pending ~30s, then fails |
-| **Any other** | Success | All transfers complete normally |
+### Beneficiary name verification
 
-**Example - Creating a Test Account with Insufficient Funds:**
-
-```bash
-POST /customers/external-accounts
-
-{
-  "customerId": "Customer:123",
-  "currency": "USD",
-  "accountInfo": {
-    "accountType": "US_ACCOUNT",
-    "accountNumber": "000000002",  // Will trigger insufficient funds
-    "routingNumber": "110000000",
-    "accountCategory": "CHECKING",
-    "beneficiary": {
-      "beneficiaryType": "INDIVIDUAL",
-      "fullName": "Test User",
-      "address": {
-        "line1": "123 Test St",
-        "city": "San Francisco",
-        "state": "CA",
-        "postalCode": "94105",
-        "country": "US"
-      }
-    }
-  }
-}
-```
-
-<Note>
-These patterns apply to the primary identifier for any account type: US account numbers, IBANs, CLABEs, Spark wallet addresses, etc. Just ensure the identifier ends with the appropriate test digits.
-For scenarios like PIX and UPI, where there's a domain part involved, append the test digits to the user name part. For example, if testing email addresses as a PIX key, the full identifier would be
-"testuser.002@pix.com.br" to trigger the insufficient funds scenario.
-</Note>
-
-### INR UPI VPA validation simulation
-
-<SandboxVpaValidation />
+<SandboxBeneficiaryVerification />
 
 ### Testing Transfer-In (Pull from External Account)
 
@@ -123,13 +82,7 @@ POST /transfer-in
 }
 ```
 
-**Expected Behaviors:**
-
-- **Success (default)**: Transaction completes immediately with status `COMPLETED`
-- **Insufficient funds (002)**: Transaction fails immediately with appropriate error
-- **Account closed (003)**: Transaction fails immediately with account validation error
-- **Transfer rejected (004)**: Transaction fails immediately with rejection error
-- **Timeout (009)**: Transaction shows `PENDING` status for ~30 seconds, then transitions to `FAILED`
+<SandboxTransferPatterns />
 
 ### Testing Transfer-Out (Push to External Account)
 
@@ -153,6 +106,8 @@ The transfer will instantly simulate the bank transfer process and complete with
 
 ## Testing Cross-Currency Quotes
 
+<SandboxQuotePatterns />
+
 ### Creating Quotes with Test Accounts
 
 When creating quotes with the `externalAccountDetails` destination type, you can provide test account patterns inline:
@@ -172,7 +127,7 @@ POST /quotes
       "currency": "EUR",
       "accountInfo": {
         "accountType": "IBAN_ACCOUNT",
-        "iban": "DE89370400440532013003",  // Ends in 003 = account closed
+        "iban": "DE89370400440532013003",  // Ends in 003 = slow payment
         "beneficiary": {
           "beneficiaryType": "INDIVIDUAL",
           "fullName": "Test User"

mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx

@@ -192,12 +192,7 @@ Full-featured sandbox environment for development:
 
 ### Special Test Patterns
 
-Control sandbox behavior with magic account numbers:
-
-- Account ending in `002`: Insufficient funds
-- Account ending in `003`: Account closed/invalid
-- Account ending in `004`: Transfer rejected
-- Account ending in `005`: Timeout (pending → failed after 30s)
+Control sandbox behavior with magic account numbers. See the [Sandbox Testing](/api-reference/sandbox-testing) guide for the full list of test patterns for cross-currency quotes, same-currency transfers, account validation, and UMA addresses.
 
 ### Developer Tools