Cash movement flow

Overview

This guide walks you through enabling users to move cash in and out of Wealthyhood: link a bank account for ownership verification, register and track deposits, 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) 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. 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.

2) Create and track payments

Before the user sends a bank transfer, register a deposit expectation with POST /deposits/expectations, including a unique payment reference (e.g. wallet-topup-${crypto.randomUUID()}). Have the user include that same reference in their bank transfer so it can be reconciled automatically.

cURL

curl -X POST 'https://api.wealthyhood.com/deposits/expectations' \
  -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",
    "reference": "wallet-topup-5f91ce",
    "consideration": { "amount": "50.00" }
  }'

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.

3) 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) Link a bank account

2) Create and track payments

3) Withdraw funds

​Overview

​Prerequisites

​1) Link a bank account

​2) Create and track payments

​3) Withdraw funds

Overview

Prerequisites

1) Link a bank account

2) Create and track payments

3) Withdraw funds