Withdrawals
Two-step withdrawal flow: place a hold, then confirm or cancel when the upstream payout resolves.
A withdrawal moves money out of a wallet. Unlike deposits (which are synchronous), withdrawals use a two-step hold/capture pattern:
- Initiate: a hold is placed on the wallet, reserving funds
- Confirm or Cancel: once the upstream payout succeeds or fails
This pattern prevents money from being spent twice while waiting for an external provider to process a payout.
Lifecycle
POST /wallets/{id}/withdraw → status: Processing (hold placed)
↓
POST /transactions/{id}/confirm → status: Completed (hold captured, money moved)
or
POST /transactions/{id}/cancel → status: Failed (hold released, funds restored)| Status | Meaning |
|---|---|
Processing | Hold placed, waiting for upstream result |
Completed | Payout succeeded, journal entry posted |
Failed | Payout failed or cancelled, hold released |
The fee is calculated at confirmation time, not at initiation. This means the exact fee reflects the schedule active at the moment money actually moves.
Initiate a withdrawal
/api/v1/banking/wallets/{walletId}/withdrawIdempotency-KeyPlaces a hold on the wallet and creates a Processing transaction. The
wallet's availableBalance decreases immediately, but ledgerBalance
remains unchanged until confirmation.
Request body
Prop
Type
curl -X POST "https://api.shiwake.example.com/api/v1/banking/wallets/wal_01HZ.../withdraw" \
-H "X-Api-Key: sk_live_..." \
-H "Idempotency-Key: withdrawal_req_001" \
-H "X-Created-By: payout-service" \
-H "Content-Type: application/json" \
-d '{
"amount": 30000,
"currency": "GHS",
"channel": "momo",
"description": "Cash out to MoMo"
}'Status codes
| Code | When |
|---|---|
201 | Withdrawal initiated, hold placed |
200 | Idempotent replay |
404 | Wallet not found |
422 | Insufficient balance, wallet frozen/closed, currency mismatch, limit exceeded |
Confirm a withdrawal
/api/v1/banking/transactions/{id}/confirmCall this when the upstream payout succeeds. The hold is captured, the journal entry posts, and the fee (if any) is deducted.
Journal entry at confirmation:
| Account | Side | Amount | Note |
|---|---|---|---|
CLIENT-{ownerId} | Debit | amount | Liability decreases |
PLATFORM-FLOAT-{CCY} | Credit | amount | Asset decreases (money left) |
CLIENT-{ownerId} | Debit | fee | Fee taken from wallet |
FEE-REVENUE-{CCY} | Credit | fee | Revenue earned |
Request body
Prop
Type
curl -X POST "https://api.shiwake.example.com/api/v1/banking/transactions/btx_01HZ.../confirm" \
-H "X-Api-Key: sk_live_..." \
-H "X-Created-By: payout-service" \
-H "Content-Type: application/json" \
-d '{ "externalReference": "momo_ref_xyz789" }'Status codes
| Code | When |
|---|---|
200 | Confirmed and settled |
404 | Transaction not found |
409 | Already completed or failed |
Cancel a withdrawal
/api/v1/banking/transactions/{id}/cancelCall this when the upstream payout fails. The hold is released and the wallet's available balance is restored.
Request body
Prop
Type
curl -X POST "https://api.shiwake.example.com/api/v1/banking/transactions/btx_01HZ.../cancel" \
-H "X-Api-Key: sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "reason": "MoMo payout timed out" }'Status codes
| Code | When |
|---|---|
200 | Cancelled, hold released |
404 | Transaction not found |
409 | Already completed or failed |
Stale hold cleanup
If a withdrawal is initiated but never confirmed or cancelled, the hold remains active indefinitely. A scheduled job endpoint is available for platform administrators to clean up expired holds:
POST /api/v1/platform/jobs/stale-hold-cleanupThis iterates all tenants, finds holds past their expiresAt, releases
them, and marks their associated banking transactions as Failed. See
your cron service for scheduling (recommended: every 15 minutes).
Last updated on