ShiwakeDocs

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:

  1. Initiate: a hold is placed on the wallet, reserving funds
  2. 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)
StatusMeaning
ProcessingHold placed, waiting for upstream result
CompletedPayout succeeded, journal entry posted
FailedPayout 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

POST/api/v1/banking/wallets/{walletId}/withdrawIdempotency-Key

Places 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

CodeWhen
201Withdrawal initiated, hold placed
200Idempotent replay
404Wallet not found
422Insufficient balance, wallet frozen/closed, currency mismatch, limit exceeded

Confirm a withdrawal

POST/api/v1/banking/transactions/{id}/confirm

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

AccountSideAmountNote
CLIENT-{ownerId}DebitamountLiability decreases
PLATFORM-FLOAT-{CCY}CreditamountAsset decreases (money left)
CLIENT-{ownerId}DebitfeeFee taken from wallet
FEE-REVENUE-{CCY}CreditfeeRevenue 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

CodeWhen
200Confirmed and settled
404Transaction not found
409Already completed or failed

Cancel a withdrawal

POST/api/v1/banking/transactions/{id}/cancel

Call 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

CodeWhen
200Cancelled, hold released
404Transaction not found
409Already 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-cleanup

This 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).

Edit on GitHub

Last updated on

On this page