Payouts
Withdraw settled wallet balance to your settlement path. Routes live under /api/v1/payout and require a dashboard JWT. The API checks wallet balance for the given currency, creates a payout in pending status, then debits the wallet.
Settlement account setup is separate (/api/v1/settings/settlement-accounts). Customer charges use Accept Payment; refunds use Refunds.
Track: wallet balance (currency) → POST /payout → pending payout → GET /payout/:id.
Why a screenshot helps: Makes the balance check and debit step visible before integrators hit Insufficient Fund errors.
Authentication
Login (get JWT)
1curl -X POST https://api.spoutpay.com/api/v1/auth/login \
2 -H "Content-Type: application/json" \
3 -d '{
4 "email": "merchant@example.com",
5 "password": "••••••••"
6 }'
7# → { "status": 200, "data": { "token": "<jwt>", "user": { ... } } }Use Authorization: Bearer <token>. Send Idempotency-Key on create — without it, idempotency is skipped for payouts (retries may double-debit). Also send X-Request-Id for log correlation.
Create payout — POST /api/v1/payout
| Field | Required? | Description |
|---|---|---|
amount | Yes | Withdrawal amount; must be ≤ wallet balance for the currency |
currency | Yes | Wallet currency to debit (e.g. NGN) |
Request body
1{
2 "amount": 25000,
3 "currency": "NGN"
4}1curl -X POST https://api.spoutpay.com/api/v1/payout \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer <dashboard_jwt>" \
4 -H "Idempotency-Key: payout-2026-11-18-001" \
5 -H "X-Request-Id: 9c3e...." \
6 -d '{
7 "amount": 25000,
8 "currency": "NGN"
9 }'Success response (200)
Message text matches the live API spelling (Withdrwal created successfully.). A debit ledger entry is created against the payout id.
1{
2 "status": 200,
3 "data": {
4 "message": "Withdrwal created successfully."
5 },
6 "requestId": "...",
7 "responseId": "..."
8}Insufficient funds (403)
1{
2 "status": 403,
3 "error": "Insufficient Fund",
4 "code": "ABORT",
5 "requestId": "..."
6}No wallet / balance (404)
1{
2 "status": 404,
3 "error": "Insufficient Balance",
4 "code": "ABORT",
5 "requestId": "..."
6}List and get
| Method | Path | Notes |
|---|---|---|
GET | /api/v1/payout | All payouts (admin/list style) |
GET | /api/v1/payout/user | Payouts for the authenticated user |
GET | /api/v1/payout/:id | Single payout by id |
GET /user sample
1{
2 "status": 200,
3 "data": [
4 {
5 "_id": "66b2...",
6 "user_id": "65e9...",
7 "amount": "25000",
8 "status": "pending",
9 "createdAt": "2026-11-18T17:05:00.000Z"
10 }
11 ],
12 "requestId": "..."
13}GET /:id sample
1{
2 "status": 200,
3 "data": {
4 "_id": "66b2...",
5 "user_id": "65e9...",
6 "amount": "25000",
7 "status": "pending",
8 "createdAt": "2026-11-18T17:05:00.000Z",
9 "updatedAt": "2026-11-18T17:05:00.000Z"
10 },
11 "requestId": "..."
12}How to track a payout
- Confirm wallet balance for
currencybefore calling create. - Create with a stable
Idempotency-Key; saverequestIdfrom the response. - List via
GET /api/v1/payout/userand match byamount/createdAt, or store the payout id from your own persistence if you extend the API later. - Watch
status(pendingat create) until settlement completes on the ops side.