# Transfers

Atomic wallet-to-wallet transfers: one journal entry, no intermediate state.

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



A **transfer** moves money between two wallets in a single atomic
operation. Unlike withdrawals, there is no hold/capture step: the journal
entry posts immediately and both balances update in the same request.

How it works [#how-it-works]

```
Client → POST /banking/transfers
         ↓
     Validate sender ≠ receiver
     Validate both wallets active, same currency
         ↓
     Post journal entry:
       Debit  CLIENT-{senderId}     (sender owes less)
       Credit CLIENT-{receiverId}   (receiver owed more)
         ↓
     Return completed transfer
```

The platform float is not touched: money moves directly between liability
accounts.

<Callout type="info">
  Transfers are currently fee-free. The `feeAmount` field is always `0`.
</Callout>

The Transfer object [#the-transfer-object]

```json
{
  "id": "txf_01HZ...",
  "senderWalletId": "wal_01HZ...",
  "receiverWalletId": "wal_02HZ...",
  "amount": 15000,
  "feeAmount": 0,
  "netAmount": 15000,
  "currency": "GHS",
  "status": "Completed",
  "journalEntryId": "jen_01HZ...",
  "reference": "rent-april-2026",
  "description": "Monthly rent payment",
  "idempotencyKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "metadata": null,
  "createdAt": "2026-04-07T12:00:00Z",
  "updatedAt": null
}
```

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, required: true, description: &#x22;Transfer identifier&#x22; },
  senderWalletId: { type: &#x22;string&#x22;, required: true, description: &#x22;Wallet money is leaving&#x22; },
  receiverWalletId: { type: &#x22;string&#x22;, required: true, description: &#x22;Wallet money is entering&#x22; },
  amount: { type: &#x22;long&#x22;, required: true, description: &#x22;Amount in minor units&#x22; },
  feeAmount: { type: &#x22;long&#x22;, required: true, description: <>Always <code>0</code> (reserved for future use)</> },
  netAmount: { type: &#x22;long&#x22;, required: true, description: <>Same as <code>amount</code></> },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;ISO 4217 code&#x22; },
  status: { type: &#x22;string&#x22;, required: true, description: <><code>Completed</code> or <code>Reversed</code></> },
  journalEntryId: { type: &#x22;string&#x22;, required: true, description: &#x22;The ledger entry that moved the money&#x22; },
  reference: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Client-supplied correlation id&#x22; },
  description: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Human-readable description&#x22; },
  idempotencyKey: { type: &#x22;string&#x22;, required: true, description: &#x22;Deduplication key&#x22; },
}"
/>

***

Create a transfer [#create-a-transfer]

<Endpoint method="POST" path="/api/v1/banking/transfers" />

Request body [#request-body]

<TypeTable
  type="{
  senderWalletId: { type: &#x22;string&#x22;, required: true, description: &#x22;Wallet to debit&#x22; },
  receiverWalletId: { type: &#x22;string&#x22;, required: true, description: &#x22;Wallet to credit&#x22; },
  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 both wallets&#x22; },
  reference: { type: &#x22;string&#x22;, description: &#x22;Your correlation id&#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/transfers" \
      -H "X-Api-Key: sk_live_..." \
      -H "Idempotency-Key: rent-april-2026" \
      -H "X-Created-By: payment-service" \
      -H "Content-Type: application/json" \
      -d '{
        "senderWalletId": "wal_01HZ...",
        "receiverWalletId": "wal_02HZ...",
        "amount": 15000,
        "currency": "GHS",
        "reference": "rent-april-2026",
        "description": "Monthly rent payment"
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 201,
      "message": "Created successfully",
      "data": {
        "id": "txf_01HZ...",
        "senderWalletId": "wal_01HZ...",
        "receiverWalletId": "wal_02HZ...",
        "amount": 15000,
        "feeAmount": 0,
        "netAmount": 15000,
        "currency": "GHS",
        "status": "Completed",
        "journalEntryId": "jen_01HZ...",
        "reference": "rent-april-2026",
        "createdAt": "2026-04-07T12:00:00Z"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes]

| Code  | When                                                                       |
| ----- | -------------------------------------------------------------------------- |
| `201` | Transfer completed                                                         |
| `200` | Idempotent replay                                                          |
| `404` | Sender or receiver wallet not found                                        |
| `422` | Same wallet, wallet frozen/closed, currency mismatch, insufficient balance |

***

List transfers [#list-transfers]

<Endpoint method="GET" path="/api/v1/banking/transfers" />

<TypeTable
  type="{
  walletId: { type: &#x22;string&#x22;, description: &#x22;Show transfers involving this wallet (as sender or receiver)&#x22; },
  take: { type: &#x22;int&#x22;, description: &#x22;Page size (default 100)&#x22; },
}"
/>

***

Get a transfer [#get-a-transfer]

<Endpoint method="GET" path="/api/v1/banking/transfers/{id}" />
