Cash movement flow

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.

All endpoints require an M2M bearer token and the x-user-id header to scope operations to the acting user.

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.

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();
}

curl -X GET 'https://api.wealthyhood.com/wallets?owner=bank-user-12345' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN'

Check the status field to ensure the wallet is active before initiating payments to the IBAN.

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.

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();
}

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"
  }'

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.

Persist the returned id (e.g., ba_...) to reference this account for deposits and withdrawals.

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:

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.

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();
}

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"
  }'

Validate sufficient available balance and supported currencies before creating withdrawals.

Getting started

Screens

Flows

Sandbox Flows

Overview

Prerequisites

1) Retrieve the wallet IBAN

2) Link a bank account

3) Create and track payments

4) Withdraw funds

​Overview

​Prerequisites

​1) Retrieve the wallet IBAN

​2) Link a bank account

​3) Create and track payments

​4) Withdraw funds

Overview

Prerequisites

1) Retrieve the wallet IBAN

2) Link a bank account

3) Create and track payments

4) Withdraw funds