Guides

Testing & sandbox

Build and verify your integration against stage before you touch production. Stage mirrors the production API surface — same endpoints, same schemas — but moves no real money, so you can drive orders end to end safely. When these docs say "sandbox", they mean stage: there is no separate sandbox server.

Stage uses separate credentials from production. Request a stage workspace and keys from integrations@virtuabroker.com.

Environments

Two isolated environments, each with its own credentials, data, and balances. Point your base URL at stage while you build, then switch it to production for go-live.

Environment	Base URL	Use it for
`production`	https://api.virtuabroker.com	Live traffic that moves real funds. Use only after you pass the go-live checklist.
`stage`	https://api-stage.virtuabroker.com	Integration and testing. No real money moves; safe to create orders freely.

Stage credentials never work against production and vice versa. Keep them in separate config and request stage access from integrations@virtuabroker.com.

A test run

Run the full Quickstart flow — quote → order → track — but point every request at the stage base URL. Nothing here settles real money, so you can repeat it as often as you like.

POST /v1/quotes · stage

curl https://api-stage.virtuabroker.com/v1/quotes \
  -H "Authorization: Bearer $VB_STAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "originCurrency": "EUR",
    "destinationCurrency": "BRL",
    "originAmount": 1000
  }'

Take the returned quoteId, create an order against https://api-stage.virtuabroker.com/v1/orders, then poll GET /v1/orders/{orderId} to watch it advance. The endpoints, payloads, and responses are identical to production — see the Quickstart for the complete walkthrough.

Simulating flows

On stage you can drive a payment through its states without moving real money. Because no real funding reaches stage, an order would otherwise sit in Pending waiting for a transfer that never arrives — so on stage, inbound transfers can be simulated to stand in for the money movement your integration is waiting on.

Simulate the incoming transfer yourself with POST /v1/simulate/incoming-transfer/deposit or POST /v1/simulate/incoming-transfer/order, passing the depositId or orderId, the amount, and the scenario you want to exercise. The simulated funds advance it exactly as a real transfer would — the deposit is credited, the order continues its lifecycle, and the corresponding webhooks fire — so you can drive the success and failure paths on demand, with your normal stage credentials.

Pending Processing Success Failed

The simulation endpoints exist only on stage — they are not mounted on production, where the same call returns 401. Use scenario to choose the outcome: success (default), processing, compliance_review or failed. For fiat, pass a counterparty (name and iban) so the transfer matches the way a real one would.

Webhooks locally

To receive webhooks on your machine during development, your local endpoint needs a public URL. Expose it with an HTTP tunnel and register the tunnel URL as your webhook endpoint on stage.

Run your endpoint locally

Start your webhook handler on a local port and confirm it verifies the signature and responds 2xx.

Expose it with an HTTP tunnel

Start a tunnel to that port. It gives you a public HTTPS URL that forwards to your local handler.

Register the tunnel URL

Set the tunnel URL as your webhook endpoint for the stage workspace.

Trigger events

Use simulated funding to advance an order and fire order_status_updated / deposit_completed at your local handler.

Tunnel URLs usually change each time you restart the tunnel — re-register the new URL when it rotates. Delivery, retries, and signature verification are covered in the Webhooks guide.

Go-live checklist

Confirm each of these on stage before you switch your base URL to production.

Check	What to confirm
`Production credentials`	Swap stage keys for production keys and switch the base URL to https://api.virtuabroker.com. Never ship stage credentials.
`Webhook endpoint`	A stable production webhook URL is registered and verifies the signature on every event before acting on it.
`Retrying a write`	Writes (orders, deposits, withdrawals) are not de-duplicated — a retry creates a second resource. Exercise your reconcile-before-resend path here, not in production.
`Error handling`	Your code branches on the error `type` — validation, state, funds, authorization — not just the HTTP status.
`Amounts & statuses`	Monetary amounts are JSON numbers (send `1000`, never a string), and statuses are PascalCase — branch on `Success` / `Failed` / `Canceled`.

Run one full stage payment end to end — quote, order, simulated funding, and the resulting webhook — the day before go-live. If it passes on stage, only the base URL and credentials change in production.