Sandbox Guide

The Avvio Sandbox environment provides deterministic simulation for every payment rail, failure condition, and webhook event.

Connecting to Sandbox

Use your test key (akid_test_...) and your server-side private P-256 key against the standard base URL:

Base URL: https://api.avvio.xyz/business/api/v1
Key Prefix: akid_test_*

Only the credential changes between Sandbox and Production. Endpoint paths, request bodies, and signature headers are identical.

Funding Your Test Balance

Fund your virtual USD balance using the Sandbox funding endpoint:

POST /payments/organizations/{orgId}/sandbox/fund
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "amount": "10000.00"
}

Check your balance and ledger entries at any time:

GET /payments/organizations/{orgId}/balance
GET /payments/organizations/{orgId}/balance/history

Deterministic Account Suffixes

Select your desired payout test outcome by configuring the last four digits of the beneficiary account number:

Account Suffix	Simulated Outcome	Status Progression	failureCode
any other digits	Normal successful execution	`pending` → `processing` → `completed`	—
`0001`	Invalid destination account	`pending` → `processing` → `failed`	`account_invalid`
`0002`	Delayed settlement	`pending` → `processing` → `completed`	—
`0003`	Post-settlement bank return	`completed` → `failed`	`returned_by_bank`
`0004`	Sanctions / compliance block	`pending` → `processing` → `failed`	`compliance_rejected`
`0005`	Quote expired before execution	Request rejected; no payout is created	—
`0006`	Requires external wallet funding	Stays `pending` until funding is confirmed, then `processing` → `completed`	—

👍
Tip
Always run scenario 0003 in your test suite to ensure your accounting and ledger workers handle post-settlement reversals.

Sandbox Webhook Endpoints & Deliveries

When using the hosted Avvio API, register a publicly reachable HTTPS receiver
(a development tunnel is fine):

POST /payments/organizations/{orgId}/sandbox/webhook-endpoints
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "url": "https://example.ngrok-free.app/api/webhooks",
  "events": ["payout.completed", "payout.failed", "payout.returned"]
}

http://localhost is accepted by the sandbox route only for a locally running
Avvio backend. A hosted backend resolves localhost to itself, not to your
laptop, so use a tunnel when testing against api.avvio.xyz.

Inspect recent deliveries and payload status codes:

GET /payments/organizations/{orgId}/sandbox/webhook-endpoints/ep_991823/deliveries