spout

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.

Wallet → payoutScreenshot
Wallet balance to payout request

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

FieldRequired?Description
amountYesWithdrawal amount; must be ≤ wallet balance for the currency
currencyYesWallet 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

MethodPathNotes
GET/api/v1/payoutAll payouts (admin/list style)
GET/api/v1/payout/userPayouts for the authenticated user
GET/api/v1/payout/:idSingle 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

  1. Confirm wallet balance for currency before calling create.
  2. Create with a stable Idempotency-Key; save requestId from the response.
  3. List via GET /api/v1/payout/user and match by amount / createdAt, or store the payout id from your own persistence if you extend the API later.
  4. Watch status (pending at create) until settlement completes on the ops side.