Docs / Sandbox Testing / Testing & Scenarios

Testing & Scenarios

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:

http

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:

http

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):

http

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:

http

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