Savings order flow

Overview

This guide covers how to submit savings top ups and withdrawals (sell orders) using the Savings Orders endpoint POST /savings/orders.

Savings orders always operate on the savings product implied by the provided currency. No ISIN is required.

Prerequisites

Access to the Savings Orders endpoints
M2M bearer token with required scopes
x-user-id header to scope the user (MongoDB ObjectId format)

Savings top up flow

Use this flow to move cash into a user’s savings plan.

Verify the user has sufficient cash

Retrieve the user’s available cash in the target currency before submitting a top up.

const BASE = 'https://api.wealthyhood.com';

async function getCashBalance({ token, userId }) {
  const res = await fetch(`${BASE}/cash`, {
    method: 'GET',
    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();
}

curl -X GET 'https://api.wealthyhood.com/cash' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -H 'x-user-id: 64f0c51e7fb3fc001234abcd'

Build the savings top up request

Create the order payload with the side set to Buy, the savings currency, and the amount to top up.

{
  "side": "Buy",
  "currency": "EUR",
  "amount": 200
}

Submit the savings top up order

Call POST /savings/orders with the request body and required headers.

const BASE = 'https://api.wealthyhood.com';

async function submitSavingsTopUp({ token, userId, currency, amount }) {
  const res = await fetch(`${BASE}/savings/orders`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-user-id': userId,
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      side: 'Buy',
      currency,
      amount
    })
  });
  if (!res.ok) throw new Error(`Savings order failed: ${res.status}`);
  return res.json();
}

curl -X POST 'https://api.wealthyhood.com/savings/orders' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -H 'x-user-id: 64f0c51e7fb3fc001234abcd' \
  -d '{
    "side": "Buy",
    "currency": "EUR",
    "amount": 200
  }'

Retrieve order status

Use GET /transactions/savings-activity to retrieve the order status. Filter the results by the transaction id returned from the order submission.

Savings withdrawal flow

Withdrawals correspond to savings sell orders. Use this flow to return funds from the savings plan to the user’s cash balance.

Retrieve the user's savings vault balance

Before submitting a withdrawal, retrieve the user’s savings vault balance to ensure they have sufficient savings in the target currency.

const BASE = 'https://api.wealthyhood.com';

async function getSavingsVault({ token, userId }) {
  const res = await fetch(`${BASE}/savings-vault`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-user-id': userId,
      'Accept': 'application/json'
    }
  });
  if (!res.ok) throw new Error(`Failed to get savings vault: ${res.status}`);
  return res.json();
}

curl -X GET 'https://api.wealthyhood.com/savings-vault' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -H 'x-user-id: 64f0c51e7fb3fc001234abcd'

The response returns a map of savings products by currency, each containing the amount (in cents) and currency. For example:

{
  "EUR": {
    "amount": 150000,
    "currency": "EUR"
  }
}

Verify sufficient savings balance

Check that the user has enough savings in the target currency to cover the withdrawal amount. Remember that the savings vault amounts are in cents, so convert accordingly.

const savingsVault = await getSavingsVault({ token, userId });
const eurSavings = savingsVault.EUR;

if (!eurSavings || eurSavings.amount < withdrawalAmountInCents) {
  throw new Error('Insufficient savings balance');
}

Build the withdrawal request

Configure the request payload with side set to Sell.

{
  "side": "Sell",
  "currency": "EUR",
  "amount": 150
}

Submit the withdrawal order

Call POST /savings/orders with the withdrawal payload.

const BASE = 'https://api.wealthyhood.com';

async function submitSavingsWithdrawal({ token, userId, currency, amount }) {
  const res = await fetch(`${BASE}/savings/orders`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-user-id': userId,
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      side: 'Sell',
      currency,
      amount
    })
  });
  if (!res.ok) throw new Error(`Savings withdrawal failed: ${res.status}`);
  return res.json();
}

curl -X POST 'https://api.wealthyhood.com/savings/orders' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -H 'x-user-id: 64f0c51e7fb3fc001234abcd' \
  -d '{
    "side": "Sell",
    "currency": "EUR",
    "amount": 150
  }'

Retrieve withdrawal status

Use GET /transactions/savings-activity to retrieve the withdrawal status. Filter the results by the transaction id returned from the withdrawal submission.

API Reference → Savings Vault → GET /savings-vault
API Reference → Savings Orders → POST /savings/orders
API Reference → Transactions → GET /transactions/savings-activity
API Reference → Cash → GET /cash

Getting started

Screens

Flows

Sandbox Flows

Overview

Prerequisites

Savings top up flow

Savings withdrawal flow

​Overview

​Prerequisites

​Savings top up flow

​Savings withdrawal flow

​Related APIs

Overview

Prerequisites

Savings top up flow

Savings withdrawal flow

Related APIs