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.

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:

• Authentication & Signing: Verify P-256 ECDSA signature generation, nonce uniqueness, and timestamp drift validation.
• Idempotency & Replays: Validate duplicate request handling, in-progress request backoff, and replay recovery on timeouts.
• Corridor Discovery: Read real-time field specifications per currency.
• Beneficiary Management: Register test recipients and scope them by endUserId.
• Payout Creation: Execute instant single-call payouts or two-step quote-and-accept flows.
• Status Progression: Observe transition pathways (pending → processing → completed).
• Deterministic Edge Cases: Trigger payment rejections, slow settlement, quote expirations, and compliance blocks using account number suffixes.
• Bank Returns: Test the critical post-settlement reversal flow (completed → failed with returned_by_bank).
• Webhooks & Deliveries: Receive signed webhook events and inspect webhook delivery logs.
• Event Reconciliation: Pull sequence-based feeds from /events to reconcile your internal database.
• Balance Limits: Simulate insufficient USD balance rejections.

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:

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:

The Bank Return Flow (0003)

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

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

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:

• Successful happy-path payout tested
• Invalid beneficiary account error handled (0001)
• Slow settlement observed and verified (0002)
• Bank return flow handled correctly (0003)
• Compliance rejection handled (0004)
• Quote expiration handled (0005)
• Insufficient balance handling verified
• Idempotent retries tested with duplicate keys
• Webhook signature verification implemented
• Webhook deduplication implemented (svix-id)
• Sequence-based event log reconciliation active (GET /events?since=)
• Production signing key stored securely server-side