Accounts API · Accounts API
Sandbox
A test key (vzm_test_…) reads a built-in simulator: test accounts and simulated money, no real money. Balances, transactions, statements and events all work from it, and its events (livemode: false) go to test webhook endpoints. Every simulation route answers 404 “No such endpoint.” to a live key.
Open a test account — POST /simulations/accounts
Scope accounts.read. Body { currency }: USD, EUR, GBP or AED. Returns the account as GET /accounts/{id} does. One per currency: asking again returns the same account (200).
curl -X POST https://api.vezmo.com/api/v1/simulations/accounts \
-H "Authorization: Bearer $TEST_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "currency": "USD" }'Make money arrive — POST /simulations/incoming
accountId(required),amountin minor units (1–100,000,000).payerName,payerCountry,rail(ach,wire,swift,sepa,local_transfer) — optional.outcome—credited(default):incoming.received, thenincoming.credited+transaction.posted.held:incoming.received, thenincoming.held.returned:incoming.received, thenincoming.returned.
Returns the incoming object (see the event object). Sandbox money has no fee.
curl -X POST https://api.vezmo.com/api/v1/simulations/incoming \
-H "Authorization: Bearer $TEST_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"accountId": "acct_cm3s1m0000001",
"amount": 125000,
"payerName": "Harbor & Co.",
"payerCountry": "US",
"rail": "ach",
"outcome": "held"
}'Move a held arrival on — POST /simulations/incoming/{id}/advance
Body { to: "credited" | "returned" }; fires that event. An arrival that isn't held, or was already moved on, answers 409 conflict “Only a held arrival can be moved on, and only once.”
curl -X POST https://api.vezmo.com/api/v1/simulations/incoming/inc_cm3s1n0000002/advance \
-H "Authorization: Bearer $TEST_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "to": "credited" }'What differs from live
- Statements are JSON or CSV only:
format=pdfwith a test key is400 validation_failed(field: "format"). A made-up balance must never look like a real statement. - A test account has
bankName: null. Sandbox money has no fee. - A sandbox unused for 90 days is deleted, with its test accounts and simulated money. TEST webhook endpoints get 5 s per attempt and 3 attempts.
- A test key whose secret was found in public code can't simulate:
403 key_leaked. It still reads test data until you revoke it; make a new test key. - Errors:
404“No such account.” (not a test account of this business) or “No such arrival.”;400 validation_failedwithfield.
Limits
- 5 requests a second and 60 a minute per key on each simulation route.
- 500 simulated arrivals a day per business: past that,
429 rate_limited(Vezmo-RateLimit-Reason: business). Idempotency-Keyis accepted and logged, not enforced, in this phase.