Sandbox
Test-only helpers: top up your test balance and force a test payout into any status. They answer NOT_FOUND to live keys.
POSTAdd test funds/api/v1/sandbox/faucetPOSTSimulate a payout outcome/api/v1/sandbox/payouts/{id}/simulate
Send your API key as Authorization: Bearer apk_test_… (sandbox) or apk_live_… (live). Each endpoint lists the scope the key needs. See API keys.
Add test funds
POST
/api/v1/sandbox/faucet API key
Adds free test USDC to your sandbox balance, which test payouts are paid from. Not real money.
Body (JSON)
amount_usdcnumberoptionalHow much to add, up to 10,000. Default 1,000.
Request
curl -X POST "https://api.autopayke.com/api/v1/sandbox/faucet" \
-H "Authorization: Bearer $AUTOPAYKE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_usdc": 1000
}'Response200 application/json
{
"ok": true,
"data": {
"object": "balance",
"livemode": false,
"usdc": "2000.000000"
}
}Simulate a payout outcome
POST
/api/v1/sandbox/payouts/{id}/simulate API key
Move a test payout to the status you want, now, and fire its webhooks. Use it to test how your code handles each outcome without waiting.
Path parameters
idstringrequiredA test payout id.
Body (JSON)
outcomestringrequiredThe status to move to. failed and reversed return the money to your sandbox balance.
processingsucceededfailedreversedin_review
Request
curl -X POST "https://api.autopayke.com/api/v1/sandbox/payouts/po_8Fq2mZx7Lk3Rt9Vb/simulate" \
-H "Authorization: Bearer $AUTOPAYKE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"outcome": "failed"
}'Response200 application/json
{
"ok": true,
"data": {
"id": "po_8Fq2mZx7Lk3Rt9Vb",
"object": "payout",
"livemode": false,
"status": "failed",
"amount": 150000,
"currency": "KES",
"source_token": "USDC",
"debited_usdc": "11.948310",
"fee_usdc": "0.302310",
"rate": "128.80",
"destination": {
"type": "mobile_money",
"network": "safaricom",
"phone": "+254 700 ••• 001"
},
"recipient_name": "Jane Wanjiku",
"reference": "order_1042",
"description": "Rider payout, week 44",
"metadata": {
"rider_id": "r_5521"
},
"failure_code": "RECIPIENT_INVALID",
"failure_message": "The recipient's account can't receive this payout.",
"created": "2026-11-03T09:10:00.000Z",
"updated": "2026-11-03T09:10:00.000Z"
}
}