Merchant Wallets API

Monitor your settlement account balances, view transaction ledgers, and track your merchant wallet activity.

🏦 What are Merchant Wallets?

Your merchant wallet is your settlement account with HooPay. When you initiate a "Pay User" transaction, funds are debited from your merchant wallet. When users send you money via "Collect From User", funds are credited to your merchant wallet.

Use these APIs to:

Check your current balance before initiating payouts
Monitor low balance thresholds and set up alerts
Access transaction ledgers for reconciliation
Track 24-hour activity statistics
Export ledger data for accounting

List All Merchant Wallets

GET /merchant-wallets

Retrieve all your merchant wallets across different currencies with current balances and summary statistics.

Example Request

cURL

curl https://hoopaywallet.com/api/v1/partner/merchant-wallets \
  -H "X-API-Key: hpk_live_your_key" \
  -H "X-Signature: your_hmac_signature"

Response 200 OK

JSON

{
  "success": true,
  "data": {
    "wallets": [
      {
        "id": 1,
        "currency": "USD",
        "balance": 15250.75,
        "formatted_balance": "15,250.75 USD",
        "status": "active",
        "is_low_balance": false,
        "low_balance_threshold": 1000.00,
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-28T10:30:00Z"
      },
      {
        "id": 2,
        "currency": "EUR",
        "balance": 8500.00,
        "formatted_balance": "8,500.00 EUR",
        "status": "active",
        "is_low_balance": false,
        "low_balance_threshold": 500.00,
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-28T09:15:00Z"
      }
    ],
    "summary": {
      "total_wallets": 2,
      "active_wallets": 2,
      "currencies": ["USD", "EUR"]
    }
  }
}

Get Wallet Balance

GET /merchant-wallets/{currency}/balance

Lightweight endpoint to quickly retrieve just your current balance. Perfect for frequent polling or balance checks before initiating payouts.

Example Request

cURL

curl https://hoopaywallet.com/api/v1/partner/merchant-wallets/USD/balance \
  -H "X-API-Key: hpk_live_your_key" \
  -H "X-Signature: your_hmac_signature"

Response 200 OK

{
  "success": true,
  "data": {
    "currency": "USD",
    "balance": 15250.75,
    "formatted_balance": "15,250.75 USD",
    "status": "active",
    "is_low_balance": false,
    "low_balance_threshold": 1000.00,
    "last_updated": "2025-01-28T10:30:00Z"
  }
}

💡 Low Balance Alerts

The is_low_balance field indicates if your balance has dropped below your configured threshold. Use this to set up automated alerts and ensure you always have sufficient funds for payouts.

Get Wallet Details

GET /merchant-wallets/{currency}

Get detailed information about a specific currency wallet including 24-hour activity statistics.

Response 200 OK

{
  "success": true,
  "data": {
    "id": 1,
    "currency": "USD",
    "balance": 15250.75,
    "formatted_balance": "15,250.75 USD",
    "status": "active",
    "is_low_balance": false,
    "low_balance_threshold": 1000.00,
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-28T10:30:00Z",
    "stats": {
      "last_24h": {
        "credits": {
          "count": 15,
          "total": 2500.00
        },
        "debits": {
          "count": 8,
          "total": 1200.00
        }
      },
      "last_transaction_at": "2025-01-28T09:45:00Z"
    }
  }
}

Get Transaction Ledger

GET /merchant-wallets/{currency}/ledger

Access your complete transaction ledger for reconciliation and audit purposes. Supports filtering by transaction type, date range, and reference type.

Query Parameters

Parameter	Type	Description
`type`	string	Filter: `credit`, `debit`, `all` (default: all)
`reference_type`	string	Filter by reference type (e.g., deposit, withdrawal, refund)
`from_date`	date	Start date (YYYY-MM-DD)
`to_date`	date	End date (YYYY-MM-DD)
`per_page`	integer	Results per page (1-100, default: 20)
`page`	integer	Page number (default: 1)

Example: Last 7 Days of Debits

cURL

curl "https://hoopaywallet.com/api/v1/partner/merchant-wallets/USD/ledger?type=debit&from_date=2025-01-21&to_date=2025-01-28" \
  -H "X-API-Key: hpk_live_your_key" \
  -H "X-Signature: your_hmac_signature"

Response 200 OK

{
  "success": true,
  "data": {
    "currency": "USD",
    "current_balance": 15250.75,
    "entries": [
      {
        "id": 12345,
        "type": "debit",
        "amount": 100.00,
        "currency": "USD",
        "balance_before": 15350.75,
        "balance_after": 15250.75,
        "reference_type": "partner_pay_user",
        "reference_id": "dep_abc123xyz",
        "memo": "Partner pay-user settlement (amount: 97.50, fee: 2.50)",
        "posted_at": "2025-01-28T09:45:00Z",
        "created_at": "2025-01-28T09:45:00Z"
      }
    ],
    "summary": {
      "total_credits": 0.00,
      "total_debits": 8500.00,
      "credit_count": 0,
      "debit_count": 85,
      "net_change": -8500.00
    }
  },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 85
  }
}

Common Use Cases

💰 Pre-Payout Balance Check

Before initiating a large batch payout, check if you have sufficient merchant wallet balance:

GET /merchant-wallets/USD/balance
→ Check if balance >= total_payout_amount
→ If yes: proceed with payouts
→ If no: top up merchant wallet first

📊 Daily Reconciliation

Download today's ledger entries and match against your internal records:

GET /merchant-wallets/USD/ledger?from_date=2025-01-28&to_date=2025-01-28
→ Export entries to CSV
→ Match reference_id with your system
→ Verify balance_after matches expected balance

🔔 Low Balance Monitoring

Set up automated alerts when balance drops below threshold:

// Poll every 5 minutes
GET /merchant-wallets/USD/balance
→ If is_low_balance === true
→ Send alert to finance team
→ Trigger auto top-up workflow

📈 Monthly Reporting

Generate monthly settlement reports:

GET /merchant-wallets/USD/ledger?from_date=2025-01-01&to_date=2025-01-31
→ Get summary.total_credits (funds received)
→ Get summary.total_debits (payouts made)
→ Calculate net_change for the month

Best Practices

Cache balance checks - Don't poll the balance endpoint excessively. Cache for 30-60 seconds.
Use ledger for reconciliation - Always match ledger entries by reference_id, not just amounts.
Monitor low_balance_threshold - Set up automated alerts to avoid failed payouts.
Filter ledger queries - Use date ranges and type filters to reduce response size.
Store ledger snapshots - For compliance, store daily ledger snapshots in your system.

Previous Fees

Next Transaction History