Skip to main content
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

The flows for creating external accounts in sandbox are the same as in production. The last 3 digits of an external account’s primary identifier (account number, IBAN, CLABE, Spark wallet address, etc.) determine the test scenario when that account is used in transfers or quotes. For identifiers with a domain part (e.g. PIX email keys), append the test digits to the username portion — for example, testuser.002@pix.com.br.

​
Beneficiary name verification

For account types that support beneficiary name verification, you can simulate different verification outcomes in sandbox. Use account identifiers with a 1xx suffix to trigger verification scenarios (this range is reserved for verification and does not conflict with transfer or quote test patterns):
SuffixbeneficiaryVerificationStatusBehavior
102NOT_MATCHEDAccount is valid but name does not match
103PARTIAL_MATCHAccount is valid, name is a fuzzy match
104PENDINGVerification still in progress
105(error)Returns 400 — invalid account
109(error)Returns 500 — simulated API error
Any otherMATCHEDAccount is valid, name matches exactly

​
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:
SuffixBehavior
002Insufficient funds — transfer fails immediately
003Account closed/invalid — transfer fails immediately
004Transfer rejected — bank rejects the transfer
005Timeout/delayed failure — stays pending ~30s, then fails
Any otherSuccess — transfer completes normally

​
Sandbox fund endpoint

Instantly add funds to any internal account using /sandbox/internal-accounts/{accountId}/fund: 
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)

When creating a quote with an external account destination, the account number suffix determines the payment outcome after quote execution:
SuffixBehavior
002Quote execution failed
003Long payment — completes after approximately 6 minutes
004Counterparty delivery failed
005Receiving bank returned payment (completes then transitions to failed)
006User cancellation
007Payout and refund failed
Any otherSuccessful payment
These patterns apply whether you use a pre-created external account as the destination or provide externalAccountDetails inline in the quote request.

​
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, then call the quote execute endpoint to trigger the transaction: 
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: 
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.

​
Sending to a UMA address

For UMA-based payments, use these sandbox addresses to simulate different scenarios:
UMA AddressBehavior
$success.usd@sandbox.uma.moneyPayment succeeds (USD)
$success.eur@sandbox.uma.moneyPayment succeeds (EUR)
$success.mxn@sandbox.uma.moneyPayment succeeds (MXN)
$pending.long.usd@sandbox.uma.moneySimulates a long-pending payment
$fail.compliance.usd@sandbox.uma.moneySimulates a compliance check failure

​
Simulating incoming UMA payments

Use the sandbox receive endpoint to simulate an incoming UMA payment to one of your platform’s users: 
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
  }'