# Withdrawals

Two-step withdrawal flow: place a hold, then confirm or cancel when the upstream payout resolves.

URL: https://docs.shiwake.app/docs/banking/withdrawals



A **withdrawal** moves money out of a wallet. Unlike
[deposits](/docs/banking/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 [#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 |

<Callout type="info">
  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.
</Callout>

***

Initiate a withdrawal [#initiate-a-withdrawal]

<Endpoint method="POST" path="/api/v1/banking/wallets/{walletId}/withdraw" />

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 [#request-body]

<TypeTable
  type="{
  amount: { type: &#x22;long&#x22;, required: true, description: &#x22;Amount in minor units&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;Must match wallet currency&#x22; },
  channel: { type: &#x22;string&#x22;, required: true, description: <>e.g. <code>&#x22;momo&#x22;</code>, <code>&#x22;bank_transfer&#x22;</code></> },
  externalReference: { type: &#x22;string&#x22;, description: &#x22;Upstream reference&#x22; },
  description: { type: &#x22;string&#x22;, description: &#x22;Human-readable description&#x22; },
  metadata: { type: &#x22;object&#x22;, description: &#x22;Arbitrary JSON&#x22; },
}"
/>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    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"
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 201,
      "message": "Withdrawal initiated. Hold placed: call confirm or cancel when the upstream payout resolves.",
      "data": {
        "id": "btx_01HZ...",
        "walletId": "wal_01HZ...",
        "type": "Withdrawal",
        "status": "Processing",
        "amount": 30000,
        "feeAmount": 0,
        "netAmount": 30000,
        "currency": "GHS",
        "channel": "momo",
        "holdId": "hld_01HZ...",
        "journalEntryId": null,
        "createdAt": "2026-04-07T12:00:00Z"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#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 [#confirm-a-withdrawal]

<Endpoint method="POST" path="/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:**

| 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 [#request-body-1]

<TypeTable
  type="{
  externalReference: { type: &#x22;string&#x22;, description: &#x22;Attach provider reference at confirmation if not known at initiation&#x22; },
}"
/>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    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" }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 200,
      "message": "Withdrawal confirmed and settled.",
      "data": {
        "id": "btx_01HZ...",
        "type": "Withdrawal",
        "status": "Completed",
        "amount": 30000,
        "feeAmount": 300,
        "netAmount": 29700,
        "currency": "GHS",
        "journalEntryId": "jen_01HZ...",
        "settledAt": "2026-04-07T12:05:00Z",
        "completedAt": "2026-04-07T12:05:00Z"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes-1]

| Code  | When                        |
| ----- | --------------------------- |
| `200` | Confirmed and settled       |
| `404` | Transaction not found       |
| `409` | Already completed or failed |

***

Cancel a withdrawal [#cancel-a-withdrawal]

<Endpoint method="POST" path="/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 [#request-body-2]

<TypeTable
  type="{
  reason: { type: &#x22;string&#x22;, description: &#x22;Why the withdrawal was cancelled&#x22; },
}"
/>

```bash
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 [#status-codes-2]

| Code  | When                        |
| ----- | --------------------------- |
| `200` | Cancelled, hold released    |
| `404` | Transaction not found       |
| `409` | Already completed or failed |

***

Stale hold cleanup [#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).
