Skip to main content

​
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();
}
Check the status field to ensure the wallet is active before initiating payments to the IBAN.
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();
}
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();
}
Validate sufficient available balance and supported currencies before creating withdrawals.