Skip to main content

​
Overview

This guide walks you through simulating deposit payments in sandbox environments. Use the test deposit endpoint to create settled deposits for test users immediately, making funds available without waiting for actual bank transfers.
Test endpoints are only available in development and staging environments. They are disabled in production for security reasons. Always use the sandbox environment (api.sandbox.wealthyhood.com) when working with test endpoints.
All endpoints require an M2M bearer token. Test endpoints do not require the x-user-id header since they operate on test data.

​
Prerequisites

  • API access and M2M credentials
  • Sandbox environment access (development or staging)
  • A test user with a portfolio (see User builder flow flow)
If you need to create a test user first, follow the User builder flow flow before proceeding with this guide.

​
1) Create a sandbox deposit

Simulate a deposit payment for the test user. This creates a settled deposit transaction immediately, making funds available without waiting for actual bank transfers. Use POST /test/deposits to create a test deposit: 
async function createTestDeposit({ token, userId, amount }) {
  const res = await fetch(`${BASE}/test/deposits`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    body: JSON.stringify({ userId, amount })
  });
  if (!res.ok) {
    const error = await res.json();
    throw new Error(`Failed to create deposit: ${error.message}`);
  }
  const deposit = await res.json();
  return deposit;
}

// Example: Create a €100 deposit
const deposit = await createTestDeposit({
  token: 'YOUR_M2M_TOKEN',
  userId: user._id,
  amount: 100.00
});

console.log('Deposit created:', deposit.id);
console.log('Status:', deposit.status); // Always "Settled"
console.log('Amount:', deposit.amount); // In cents (10000)
The deposit is created with Settled status immediately, and the user’s cash availability is updated automatically. The deposit uses the user’s default currency and is associated with their first portfolio.
Requirements: The user must exist and have a portfolio. If the user has a bank account, it will be automatically linked to the deposit.

​
2) Verify the deposit

Verify that the deposit was created successfully and check the user’s cash balance. Use GET /cash to check the user’s cash balance: 
async function getCash({ token, userId }) {
  const res = await fetch(`${BASE}/cash`, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-user-id': userId,
      'Accept': 'application/json'
    }
  });
  if (!res.ok) throw new Error(`Failed to get cash: ${res.status}`);
  return res.json();
}

// Check cash balance after deposit
const cash = await getCash({
  token: 'YOUR_M2M_TOKEN',
  userId: user._id
});

console.log('Available cash:', cash.available);
console.log('Currency:', cash.currency);
Alternatively, use GET /deposits to list all deposits for the user: 
curl -X GET 'https://api.sandbox.wealthyhood.com/deposits' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -H 'x-user-id: 64f0c51e7fb3fc001234abcd'

​
Complete example

Here’s a complete example that creates a deposit for an existing test user and verifies the balance: 
const BASE = 'https://api.sandbox.wealthyhood.com';
const token = 'YOUR_M2M_TOKEN';
const userId = '64f0c51e7fb3fc001234abcd'; // Existing test user ID

async function sandboxPaymentFlow() {
  try {
    // 1. Create deposit
    const depositRes = await fetch(`${BASE}/test/deposits`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        userId: userId,
        amount: 250.00
      })
    });
    const deposit = await depositRes.json();
    console.log('Created deposit:', deposit.id, deposit.status);

    // 2. Verify cash balance
    const cashRes = await fetch(`${BASE}/cash`, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'x-user-id': userId,
        'Accept': 'application/json'
      }
    });
    const cash = await cashRes.json();
    console.log('Cash balance:', cash.available, cash.currency);

    return { deposit, cash };
  } catch (error) {
    console.error('Error in sandbox payment flow:', error);
    throw error;
  }
}

sandboxPaymentFlow();

​
Troubleshooting

​
User not found error

Error: 404 - User not found Solution: Ensure the userId is a valid MongoDB ObjectId (24-character hexadecimal string) and the user exists in the system.

​
User does not have a portfolio

Error: 400 - User does not have a portfolio Solution: Create the user with a status that includes a portfolio (e.g., VERIFIED_WITH_CASH, INVESTED, etc.). Some statuses like NEW may not have portfolios.

​
Invalid amount

Error: 400 - Amount must be a positive number Solution: Ensure the amount is a positive number greater than 0. Use decimal format (e.g., 100.50) for amounts with cents.

​
Endpoint not available

Error: 403 - Forbidden or endpoint returns 404 Solution: Verify you’re using the sandbox environment (api.sandbox.wealthyhood.com). Test endpoints are disabled in production.