Reserved Account

Reserved Accounts let you generate dedicated sub-accounts for your customers, vendors, or internal departments — each with its own unique account number, but linked to your main business wallet.

When someone deposits into a reserved account, the funds are automatically routed to your main balance.
You’ll also receive webhook events for each transaction, helping you reconcile payments per customer.

---

🚀 Overview

• Create dedicated virtual accounts for customers or business units.
• Route all inflows to your main bank account balance.
• Get real-time webhooks for all deposits and transfers.
• Simplify reconciliation by assigning each reserved account to a customer or purpose.

💡 Ideal for marketplaces, fintechs, and platforms managing multiple end-users under one main account.

---

🧾 Create a Reserved Account

Endpoint

POST /fiat/reserved-accounts

Description

Creates a sub-account under your main virtual bank account.

Request Body

JSON

{
    "currency": "NGN",
    "phone_number": "08093930950",
    "email": "[email protected]",
    "reference": "id_4675069331",
    "identity_id": "id_4675069331",
}

Example Request

Bash

curl -X POST "https://sandbox.tsara.ng/v1/bank-accounts/reserved" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "business_id": "biz_123",
    "linked_bank_account_id": "bank_001",
    "customer": {
      "id": "cus_456",
      "name": "John Doe",
      "email": "[email protected]"
    },
    "metadata": {
      "purpose": "Customer Deposit Wallet"
    }
  }'

Response

JSON

{
  "success": true,
  "data": {
    "id": "rsv_123",
    "linked_bank_account_id": "bank_001",
    "account_number": "1002334456",
    "bank_name": "SafeHaven MFB",
    "account_name": "John Doe - ACME LTD (Reserved)",
    "currency": "NGN",
    "status": "active",
    "created_at": "2025-10-17T12:00:00Z"
  },
  "request_id": "req_789"
}

---

🔍 Retrieve a Reserved Account

Endpoint

GET /fiat/virtual-accounts?id=rsv_123

Example

Bash

curl -X GET "https://sandbox.tsara.ng/v1/fiat/virtual-accounts/rsv_123" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response

JSON

{
  "success": true,
  "data": {
    "id": "rsv_123",
    "linked_bank_account_id": "bank_001",
    "account_number": "1002334456",
    "account_name": "John Doe - ACME LTD (Reserved)",
    "currency": "NGN",
    "status": "active",
    "customer": {
      "id": "cus_456",
      "name": "John Doe"
    }
  }
}

---

📜 List Reserved Accounts

Endpoint

GET /fiat/virtual-accounts?page=1&limit=20

Example

Bash

curl -X GET "https://sandbox.tsara.ng/v1/fiat/virtual-accounts?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response

JSON

{
  "success": true,
  "data": [
    {
      "id": "rsv_001",
      "account_number": "1002334456",
      "customer": { "name": "John Doe" },
      "status": "active"
    },
    {
      "id": "rsv_002",
      "account_number": "1002337788",
      "customer": { "name": "Jane Smith" },
      "status": "active"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

---

🔔 Webhook Notifications

When a customer makes a payment to a reserved account, you’ll receive a fiat.received webhook.

Example Payload

JSON

{
  "id": "evt_567",
  "type": "fiat.received",
  "data": {
    "reserved_account_id": "rsv_123",
    "linked_bank_account_id": "bank_001",
    "amount": 75000,
    "currency": "NGN",
    "customer": {
      "id": "cus_456",
      "name": "John Doe"
    },
    "status": "success",
    "reference": "deposit_001",
    "created_at": "2025-10-17T12:00:00Z"
  }
}

---

🧠 Best Practices

1. Create one reserved account per customer or use-case for easy tracking.
2. Use metadata (e.g., order IDs, purpose) for better reconciliation.
3. Handle webhook events asynchronously — they’re the source of truth.
4. Reserved accounts inherit the settlement options (Instant or T+1) from their linked main account.

---

🔗 Related Pages

• Virtual Bank Accounts — Main accounts for your business.
• Bank Transfers — Send or withdraw funds.
• Customers — Manage customers linked to reserved accounts.
• Webhooks — Handle deposit and withdrawal events securely.