> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wealthyhood.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cash movement flow

> End-to-end guide for retrieving wallet details, linking a bank account, depositing funds, and withdrawing cash.

## Overview

This guide walks you through enabling users to move cash in and out of Wealthyhood: retrieve the wallet IBAN, link a bank account for ownership verification, deposit funds, and withdraw back to the bank.

<Info>
  All endpoints require an M2M bearer token and the `x-user-id` header to scope operations to the acting user.
</Info>

### Prerequisites

* API access and M2M credentials
* `x-user-id` value for the target user

***

## 1) Retrieve the wallet IBAN

When a user is created, a wallet is provisioned automatically. Use `GET /wallets` with the `owner`
query parameter to fetch the wallet, including its dedicated IBAN and current status.

<CodeGroup>
  ```javascript Node.js theme={null}
  const BASE = 'https://api.wealthyhood.com';

  async function getWallet({ token, userId }) {
    const url = new URL(`${BASE}/wallets`);
    url.searchParams.set('owner', userId);

    const res = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json'
      }
    });
    if (!res.ok) throw new Error(`Wallet lookup failed: ${res.status}`);
    return res.json();
  }
  ```

  ```bash cURL theme={null}
  curl -X GET 'https://api.wealthyhood.com/wallets?owner=bank-user-12345' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer YOUR_M2M_TOKEN'
  ```
</CodeGroup>

<Tip>
  Check the `status` field to ensure the wallet is `active` before initiating payments to the IBAN.
</Tip>

***

## 2) Link a bank account

Before users can deposit funds, they must link a bank account. This is required to verify account
ownership and match incoming payments to the correct user.

Use `POST /bank-accounts` to register a bank account for the user.

<CodeGroup>
  ```javascript Node.js theme={null}
  async function createBankAccount({ token, userId, accountName, accountNumber, bankName, holderName }) {
    const res = await fetch(`${BASE}/bank-accounts`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'x-user-id': userId,
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ accountName, accountNumber, bankName, holderName })
    });
    if (!res.ok) throw new Error(`Create failed: ${res.status}`);
    return res.json();
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.wealthyhood.com/bank-accounts' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
    -H 'x-user-id: bank-user-12345' \
    -d '{
      "accountName": "Primary Current Account",
      "accountNumber": "GR1601101250000000012300695",
      "bankName": "Acme Bank",
      "holderName": "Jane Doe"
    }'
  ```
</CodeGroup>

<Warning>
  **Bank account linking is mandatory for deposits.** When a user sends funds to their wallet IBAN, the
  system verifies that the sending bank account matches a linked account to confirm ownership and prevent
  unauthorized deposits.
</Warning>

<Tip>
  Persist the returned `id` (e.g., `ba_...`) to reference this account for deposits and withdrawals.
</Tip>

***

## 3) Create and track payments

Send funds to the IBAN returned by the wallet lookup. Include a unique payment reference (e.g.
`wallet-topup-${crypto.randomUUID()}`) in your bank transfer so that you can later reconcile the
movement.

Once the payment is executed, poll `GET /deposits` with the `bankReference` query parameter to detect
the matching deposit record:

```bash theme={null}
curl -X GET 'https://api.wealthyhood.com/deposits?bankReference=wallet-topup-5f91ce' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -H 'x-user-id: bank-user-12345'
```

Use a new random reference for each payment to simplify tracking. The deposit response indicates the
current `status`, allowing you to monitor when the funds become available to the user.

***

## 4) Withdraw funds

Use `POST /withdrawals` to send funds back to the user's bank account.

<CodeGroup>
  ```javascript Node.js theme={null}
  async function createWithdrawal({ token, userId, bankAccountId, amount, currency, reference }) {
    const res = await fetch(`${BASE}/withdrawals`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'x-user-id': userId,
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ bankAccountId, amount, currency, reference })
    });
    if (!res.ok) throw new Error(`Withdrawal failed: ${res.status}`);
    return res.json();
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.wealthyhood.com/withdrawals' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
    -H 'x-user-id: bank-user-12345' \
    -d '{
      "bankAccountId": "ba_64f0c51e7fb3fc001234abcd",
      "amount": "50.00",
      "currency": "EUR",
      "reference": "Withdraw to bank"
    }'
  ```
</CodeGroup>

<Warning>
  Validate sufficient available balance and supported currencies before creating withdrawals.
</Warning>