/ Payouts v1 Dashboard ↗
Docs / Sandbox Testing / Sandbox Overview

Sandbox Overview

Avvio Sandbox is an isolated environment for developing and testing payout integrations without moving real funds or interacting with live payment networks.

Both sandbox and production share the same API architecture, endpoint schemas, signature validation logic, and webhook event structures. The only runtime change is your credential prefix and signing key.

text
Sandbox Environment
akid_test_* (Test Key ID)
        ↓
Avvio Sandbox Engine
        ↓
Simulated Rails (No real funds)

Production Environment
akid_live_* (Live Key ID)
        ↓
Avvio Production Engine
        ↓
Real-World Banking Rails (Real funds)

What You Can Test#

The Sandbox environment lets you simulate the full end-to-end lifecycle of your integration before submitting for production approval:

Getting Started Flow#

Follow this step-by-step sequence to complete your initial Sandbox testing:

  1. Create Sandbox Credentials: Issue a test key pair (akid_test_...) in the dashboard or via OpenSSL.
  2. Configure Request Signing: Set up automated client-side request signing with your private P-256 key.
  3. Discover Corridor Requirements: Call GET /recipients/{orgId}/corridors to dynamically inspect required fields.
  4. Create a Test Beneficiary: Register a recipient using POST /recipients/{orgId}.
  5. Create a Test Payout: Send funds using POST /payments/organizations/{orgId}/payouts.
  6. Track the Payout: Read state changes via GET /payments/organizations/{orgId}/orders/{payoutId}.
  7. Configure Webhooks: Register an endpoint to receive signed payout.completed or payout.failed payloads.

Sandbox Balance#

Unlike production accounts funded via actual USD bank wires, Sandbox balance is funded directly through an API endpoint:

bash
POST /payments/organizations/{orgId}/sandbox/fund
Idempotency-Key: <uuid>

{
  "amount": "10000.00"
}

Funding is an explicit call rather than a static default balance. This allows you to test both sufficient balance execution and 400 Insufficient USD balance for this payout failure handling.

NOTE

Sandbox balance is purely virtual and does not represent real money.

Test Scenarios & Account Suffixes#

The Sandbox uses the last four digits of the beneficiary account number to select the execution outcome deterministically. Same input, same outcome, every time:

Account Suffix What Happens Status Path failureCode
_anything else_ Completes normally (happy path) pending → processing → completed —
0001 Fails at the network due to invalid account pending → processing → failed account_invalid
0002 Settles slowly so you can watch status changes pending → processing → completed —
0003 Completes, then bank returns it days later completed → failed returned_by_bank
0004 Compliance block; funds are not returned pending → processing → failed compliance_rejected
0005 The quote expires before execution Request rejected; no payout is created —
0006 Waits for external wallet funding pending until funded, then processing → completed —

The Bank Return Flow (0003)#

The 0003 scenario is the most critical test before moving to production:

text
pending → processing → completed (Funds Sent)
                           ↓ (Days later)
                         failed  (failureCode: returned_by_bank, fundsReturned: true)

A receiving bank can return a settled payment days after it was marked completed. Ensure your ledger and event handlers never treat completed as immutable.

Sandbox vs Production#

Feature Sandbox Production
Key Prefix akid_test_* akid_live_*
Real Funds No (Virtual balance) Yes (Funded USD balance)
Payment Networks Simulated Real clearing houses & rails
Exchange Rates Fixed Live market rates
Settlement Speed Seconds Real-world banking timelines
Webhooks Supported (Standard Webhooks) Supported (Standard Webhooks)
Localhost Webhooks Accepted only when the Avvio backend itself runs locally; use a public tunnel against the hosted API HTTPS required

Important Sandbox Behaviors#

Fixed Exchange Rates#

Sandbox exchange rates are fixed so assertions on exact currency amounts continue passing reliably in automated test suites.

Accelerated Settlement#

Settlement completes within seconds rather than real-world clearing cycles (hours or days), allowing fast automated testing.

Standard Webhook Signatures#

Sandbox webhooks use the exact same HMAC-SHA256 signature scheme (svix-id, svix-timestamp, svix-signature) as production.

Localhost Receivers#

In Sandbox, http://localhost:... is accepted for a locally running Avvio backend. When calling the hosted API, use a public HTTPS tunnel because the remote backend cannot reach your laptop's loopback interface.

Pre-Production Checklist#

Before switching your configuration to live production credentials: