Vezmo App

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).

Request
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), amount in minor units (1–100,000,000).
  • payerName, payerCountry, rail (ach, wire, swift, sepa, local_transfer) — optional.
  • outcome — credited (default): incoming.received, then incoming.credited + transaction.posted. held: incoming.received, then incoming.held. returned: incoming.received, then incoming.returned.

Returns the incoming object (see the event object). Sandbox money has no fee.

A held arrival
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.”

Request
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=pdf with a test key is 400 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_failed with field.

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-Key is accepted and logged, not enforced, in this phase.