Sandbox

Sandbox is where you build. It runs the same code as production, but on its own servers and database, with simulated mobile money and bank rails and real crypto testnets. Nothing you do here moves real money. Your keys keep the two apart: a sk_test_ key only works in sandbox and a sk_live_ key only works in production, so you can’t send a test payout to a real customer by accident.

	Sandbox	Production
Base URL	`https://sandbox-api.platform.chipper.ai`	`https://api.platform.chipper.ai`
Keys	`sk_test_…`	`sk_live_…`
Fiat rails (mobile money, bank)	Simulated: instant, deterministic	Real aggregators
Crypto	Real testnets (Stellar testnet, Solana devnet, Ethereum testnets…)	Mainnets
Customer-facing ids	carry `_test_` (`pl_test_…`)	`pl_…`
Webhooks, pagination, errors	identical	identical

Funding a balance

Payouts and conversions spend from your balance, and a new sandbox account starts at zero. Use this endpoint to add test money to your sandbox balance so you have something to send. It’s sandbox only: no real money is involved, and it doesn’t exist in production.

curl -X POST https://sandbox-api.platform.chipper.ai/v1/simulations/fund-balance \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 5000, "currency": "NGN", "externalReference": "fund-1" }'

The money lands instantly in that currency’s balance. It works for fiat currencies (NGN, GHS, KES, USD and so on); for crypto, send testnet funds to your deposit address instead (see Stellar testnet). Reusing an externalReference replays the original top-up, so use a new one each time. Prefer clicking? Add test funds on the dashboard’s Home and Balances pages does the same thing.

Deterministic outcomes

Real rails fail in real ways: a wallet rejects, a bank times out, a customer never approves the prompt. Sandbox lets you trigger each one on purpose.

Payouts: the amount’s cents choose the outcome

Amount ends in	Outcome
`.01`	`rejected`: provider refuses immediately
`.02`	`beneficiary_unavailable`
`.03`	`timeout_then_reconciled`: no response, later found completed
`.04`	`retry_then_completed`: first attempt fails, retry succeeds
`.05`	`pending_then_completed`
`.06`	`connection_reset`
`.07`	`pending_then_failed`
anything else	`completed`

So 150.00 completes, 150.07 goes pending and then fails, the same code path your production integration will hit.

Collections: the amount’s cents choose the outcome

Amount ends in	Outcome
`.50`	`delayed_completion`
`.51`	`failed`: the payer declined
`.52`	`customer_timeout`: the prompt was never answered
`.99`	`transient_error_then_reconciled`
anything else	`completed`

Validation: the account number’s suffix chooses the outcome

Account number ends in	Result
`000000`	`account_not_found`
`000001`	`account_closed`
`000002`	`validation_timeout`
anything else	`valid`, with a deterministic account name

Simulated inflows

Money arriving has no natural trigger in sandbox, so there are endpoints for it:

POST /v1/simulations/virtual-account-deposit: a customer transferred into a virtual account (choose completed or failed).
POST /v1/simulations/checkout-deposit: a payer completed a bank-transfer checkout session.
Crypto deposits: send real testnet tokens to the address, or use the checkout page’s dev tools locally.

GET /v1/simulations returns this whole table as JSON, so your test suite can read the rules rather than hardcode them.

Stellar testnet

Sandbox runs on the real Stellar testnet. USDC is Circle’s testnet USDC, issuer GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5; XLM is testnet lumens. A testnet wallet to test with. Create a keypair with any Stellar wallet or SDK and fund it with 10,000 XLM from Friendbot:

curl "https://friendbot.stellar.org?addr=G..."

For USDC, add a trustline to the asset above, then take testnet USDC from Circle’s faucet or swap testnet XLM for it on the Stellar testnet exchange (a path payment). Money in. Create a deposit address:

curl $CHIPPER_API/v1/crypto-addresses \
  -H "Authorization: Bearer $CHIPPER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency": "USDC", "chain": "Stellar"}'

The response has an address and a tag. Send to the address with the tag as a memo ID. The memo is how the deposit is matched to your workspace, and a payment without it is held for manual review instead of being credited. Deposits credit within seconds of the ledger closing, net of the deposit fee, and send account.credited. Use "currency": "XLM" for lumens. Money out. A payout to any Stellar address:

curl $CHIPPER_API/v1/payouts \
  -H "Authorization: Bearer $CHIPPER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": {"code": "usdc_stellar", "address": "G...", "amount": 5, "currency": "USDC"}, "externalReference": "stellar-out-1"}'

Use xlm_stellar for XLM, and add "tag" when the destination needs a memo, as exchanges do. A USDC destination must hold a USDC trustline. Payouts complete within about a minute. Ramps. An order converts and delivers in one call, for example GHS from mobile money straight to USDC in a Stellar wallet:

curl $CHIPPER_API/v1/orders \
  -H "Authorization: Bearer $CHIPPER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": {"code": "gh_mtn", "accountNumber": "233559630374", "amount": 100, "currency": "GHS"}, "to": {"code": "usdc_stellar", "accountNumber": "G...", "currency": "USDC"}, "externalReference": "ramp-1"}'

What sandbox won’t tell you

Sandbox proves your integration: envelopes, idempotency, webhook handling, state machines. It doesn’t prove a specific rail’s behaviour on a Tuesday afternoon in Accra: real settlement times, real operator downtime, real limits. Treat the estimatedSettlement values in capabilities as the honest production guide.

Moving to production

You can create a sk_live_ key and use the production API from day one, changing nothing but the key and base URL. The one thing gated is sending payouts with real money: production access is enabled per organization. Email api-support@chippercash.com with your organization name and use case. If you create GHS virtual accounts, set your organization representative in production first. Sandbox fills one in from your owner’s name, but production doesn’t, and without one it returns 422.

Getting started

Concepts

Guides

Funding a balance

Deterministic outcomes

Payouts: the amount’s cents choose the outcome

Collections: the amount’s cents choose the outcome

Validation: the account number’s suffix chooses the outcome

Simulated inflows

Stellar testnet

What sandbox won’t tell you

Moving to production

​Funding a balance

​Deterministic outcomes

​Payouts: the amount’s cents choose the outcome

​Collections: the amount’s cents choose the outcome

​Validation: the account number’s suffix chooses the outcome

​Simulated inflows

​Stellar testnet

​What sandbox won’t tell you

​Moving to production

Funding a balance

Deterministic outcomes

Payouts: the amount’s cents choose the outcome

Collections: the amount’s cents choose the outcome

Validation: the account number’s suffix chooses the outcome

Simulated inflows

Stellar testnet

What sandbox won’t tell you

Moving to production