Developer Sandbox & Simulation

Use the Verto Sandbox to authenticate, simulate inbound activity, trigger expected failures, and verify your webhook and idempotency handling before you request production access.

This guide is the primary testing runbook for Verto integrations.

Start here

Use this page as the main testing entry point if you are validating a new integration:

1. Configure sandbox and confirm authentication works.
2. Create the resources your flow depends on, such as wallets, beneficiaries, sub-accounts, or account details.
3. Validate the core money movement flows you actually support.
4. Confirm webhook and retry handling before you treat the integration as production-ready.

Related validation guides

✅ Before you start testing

Complete these steps before you rely on sandbox results:

1. Configure the sandbox base URLs for the services your flow uses.
2. Generate sandbox credentials and confirm you can authenticate successfully.
3. Register a webhook endpoint if your flow depends on event-driven updates.
4. Decide which flows you want to test: receive, wallet, beneficiary, payout, FX, or error handling.
5. Define how your sandbox workflow should behave when a transaction enters review or requires an RFI.

Recommended testing order

Run your sandbox validation in this sequence so failures are easier to isolate:

1. Authenticate first so you know your credentials and environment are correct.
2. Create or identify the resources your flow depends on, such as wallets, beneficiaries, or sub-accounts.
3. Simulate inbound or outbound activity to validate business logic.
4. Confirm webhook processing so asynchronous state changes are reflected in your app.
5. Test retries and failures only after the happy path works end to end.

This order applies whether you are building a direct integration, an Atlas platform flow, or a narrower feature like cards.

🔑 Step 1: Sandbox Environment Setup

Keep sandbox credentials and configuration separate from production values so you do not mix test traffic with live operations.

🧱 Step 2: Create the resources your flow depends on

Before you simulate money movement, create or identify the objects your flow needs.

Use this step to validate resource setup such as:

• wallets for direct integrations using Create wallet and Get all Wallets
• sub-accounts and wallets for platform integrations using Create a sub-account (New)
• beneficiaries for payout testing using Create beneficiary
• beneficiary validation using Get account name where supported
• FX prerequisites using Get FX rate and Create FX trade

If this setup does not work in sandbox, later payment and reconciliation tests will not be meaningful.

🏦 Step 3: Simulate inbound and outbound activity

Use sandbox to validate the core money movement flows your integration actually depends on:

• Receive: simulate or observe inbound wallet credits and reconcile them correctly
• Payout: create outbound requests and confirm their state transitions
• Beneficiary: create or update beneficiaries, then check verificationState, isAccountActive, and isUpdateRequired before payment selection
• FX: request a rate, use the short-lived vfx_token, create the FX trade, and wait for settlement before using converted funds downstream

To credit a sandbox wallet without real capital, use the Simulator API (Sandbox Only).

curl -X POST https://api.sandbox.vertofx.com/v2/simulator/credit \
  -d '{
    "wallet_id": "wal_gbp_11",
    "amount": "50000.00"
  }'

Use this flow to validate wallet credit handling, webhook processing, and downstream reconciliation without waiting for real settlement rails.

🔔 Step 4: Verify webhook handling

Webhook validation is a required part of sandbox testing for any asynchronous flow.

Use this step to confirm that:

• your endpoint is publicly reachable
• your app acknowledges events quickly
• duplicate events do not create duplicate internal updates
• your ledger changes only when the expected final or usable event state is received

🛑 Step 5: Simulate failures and retry behavior

Append the X-Verto-Simulation header to any request to force a specific error code.

• X-Verto-Simulation: error_insufficient_funds
• X-Verto-Simulation: error_compliance_hold

Use simulated failures to verify that your retry logic, user-facing messaging, and alerting behave correctly when the API does not return a normal success response.

When simulating error_compliance_hold, verify that your application follows Handle RFIs and Compliance Exceptions: pause automated retries, move the item into an exception queue, and show a review or information-required state instead of marking the transaction as failed.

🎯 Debugging Checklist

1. Webhook Deliverability: Use Webhook.site to verify Verto signals reach your app.
2. Idempotency: Re-send the same request with the same key to verify the 200/201 response is identical.
3. Latency: Sandbox handles requests in ~200ms; production may vary based on bank rail connectivity.

Validation matrix

Use this matrix to confirm each part of your integration behaves as expected.

What a successful sandbox run looks like

Before you move toward production, you should be able to say all of the following are true:

• Your app authenticates reliably in sandbox.
• The wallets, beneficiaries, sub-accounts, or receiving accounts your flow needs can be created successfully.
• Your app uses service-specific sandbox hosts for Login, Wallet, Beneficiary, Exchange, and Onboarding APIs.
• Your webhook endpoint receives and acknowledges events quickly.
• Your internal ledger updates only after the expected final or usable state.
• Your payout or transfer retry logic reuses the same idempotency key for uncertain outcomes.
• Your RFI workflow can pause review-blocked items, assign an owner, and resume only after the next valid status update.
• Your team can distinguish a sandbox logic success from a production-readiness success.

Optional: What sandbox does not prove

Sandbox is useful for logic validation, but it does not fully reproduce live operating conditions:

• Production settlement timing can differ by corridor and bank rail.
• Compliance review timing in live flows can delay downstream actions.
• Live webhook volume and retry patterns may differ from low-volume sandbox testing.

Next steps