URL: /paas/fincard-virtual/accounts

---
title: 'Accounts'
description: 'Merchant account management, balances, ledger transactions, and fund transfers'
---

# Account APIs

Manage merchant accounts (WALLET and MARGIN types), query balances, view ledger transactions, and execute fund transfers.

<Info>
  **Base URL:** `POST /api/v2.1/fincard/virtual/account/...`
</Info>

---

## Assets (Account Info)

Returns all merchant accounts with balances.

```bash
POST /api/v2.1/fincard/virtual/account/info
```

**Request:** `{}` (empty body)

**Response `data[]`:**

| Field | Type | Description |
|-------|------|-------------|
| `accountId` | String | Account ID |
| `accountName` | String | Account name |
| `accountType` | String | `WALLET` or `MARGIN` |
| `currency` | String | Currency (e.g. `USD`) |
| `totalBalance` | BigDecimal | Total balance |
| `availableBalance` | BigDecimal | Available balance |
| `frozenBalance` | BigDecimal | Frozen balance |
| `digital` | Long | Decimal places for display |

<Accordion title="Example Response">
```json
{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": [
    {
      "accountId": "19847563867367666",
      "accountName": "wallet9023",
      "accountType": "WALLET",
      "currency": "USD",
      "totalBalance": 100,
      "availableBalance": 100,
      "frozenBalance": 0,
      "digital": 2
    }
  ]
}
```
</Accordion>

---

## Account List

Paginated list of accounts with optional type filter.

```bash
POST /api/v2.1/fincard/virtual/account/list
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `accountId` | Long | No | Filter by account ID |
| `type` | String | No | `WALLET` or `MARGIN` |
| `pageNum` | Integer | Yes | Page number (default 1) |
| `pageSize` | Integer | Yes | Page size (default 10, max 10) |

**Response `data`:** `{ total: Long, records: [...] }` — records same shape as Account Info.

---

## Single Account Query

Query a single account by ID.

```bash
POST /api/v2.1/fincard/virtual/account/single/query
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `accountId` | Long | Yes | Account ID |

**Response `data[]`:** Same shape as Account Info.

---

## Ledger Transactions

Query financial transaction history for an account.

```bash
POST /api/v2.1/fincard/virtual/account/transaction
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pageNum` | Integer | Yes | Page number (default 1) |
| `pageSize` | Integer | Yes | Page size (default 10, max 100) |
| `orderNo` | String | No | Filter by transaction ID |
| `accountId` | Long | No | Filter by account |
| `bizType` | String | No | Transaction type (see below) |
| `startTime` | Long | No | Start time (ms). Max 30-day range |
| `endTime` | Long | No | End time (ms) |

**Transaction Types (`bizType`):**

| Value | Description |
|-------|-------------|
| `chain_deposit` | Wallet chain deposit |
| `chain_withdraw` | Wallet chain withdrawal |
| `card_purchase` | Card purchase (create fee + deposit) |
| `card_deposit` | Card deposit |
| `card_withdraw` | Card withdraw |
| `card_cancel` | Card cancel |
| `card_auth_fee_patch` | Card authorization fee |
| `card_auth_cross_board_patch` | Card cross-border fee |
| `gt_transfer` | Global transfer |
| `gt_transfer_refund` | Global transfer refund |
| `fixed` | Adjustment |
| `card_overdraft_statement` | Card overdraft bill |

**Response `data`:** `{ total, records[] }`

| Field | Type | Description |
|-------|------|-------------|
| `txId` | Long | Internal transaction ID |
| `accountId` | String | Account ID |
| `amount` | BigDecimal | Amount |
| `beforeBalance` | BigDecimal | Balance before transaction |
| `afterBalance` | BigDecimal | Balance after transaction |
| `orderNo` | String | Transaction ID |
| `bizType` | String | Transaction type |
| `direction` | String | `IN` or `OUT` |
| `remark` | String | Remark |
| `createTime` | Long | Millisecond timestamp |

<Accordion title="Example Response">
```json
{
  "success": true,
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "total": 34,
    "records": [
      {
        "txId": 517581,
        "accountId": "1979009257233215490",
        "currency": "USD",
        "amount": "4.08",
        "beforeBalance": "99327.04375",
        "afterBalance": "99322.96375",
        "orderNo": "C2C_UZS_2025122307584616966",
        "bizType": "gt_transfer",
        "direction": "OUT",
        "remark": "Global transfer",
        "createTime": 1766480100874
      }
    ]
  }
}
```
</Accordion>

---

## Create Shared Account

Create a new MARGIN account for shared card mode.

```bash
POST /api/v2.1/fincard/virtual/account/create
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `accountName` | String | Yes | Account name |

**Response `data[]`:** The created account (same shape as Account Info).

---

## Fund Transfer

Transfer or collect funds between accounts.

```bash
POST /api/v2.1/fincard/virtual/account/transfer
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | String | Yes | `TRANSFER` or `COLLECTION` |
| `merchantOrderNo` | String | Yes | Client transaction ID `[20..40]` |
| `amount` | BigDecimal | Yes | Amount |
| `payerAccountId` | Long | Yes | Payer account (typically WALLET) |
| `payeeAccountId` | Long | Yes | Payee account (typically MARGIN) |
| `remark` | String | No | Remark |

**Response `data`:** `true` (boolean)

<Note>
  Use this to fund a MARGIN account before creating shared (BUDGET_CARD) cards linked to it.
</Note>

---

## Wallet Deposit (Deprecated)

<Warning>
  **Deprecated.** Use the [Wallet v2 APIs](/paas/fincard-virtual/wallet) instead.
</Warning>

Create a wallet deposit order. Returns deposit address and amount.

```bash
POST /api/v2.1/fincard/virtual/account/walletDeposit
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chain` | String | No | `TRC20` (default) or `BEP20` |
| `amount` | BigDecimal | Yes | Deposit amount |

**Response `data`:**

| Field | Type | Description |
|-------|------|-------------|
| `orderNo` | String | Transaction ID |
| `userInputDepositAmount` | BigDecimal | Input amount |
| `actualDepositAmount` | BigDecimal | Actual amount (with decimal adjustment) |
| `currency` | String | `USDT` |
| `chain` | String | Network chain |
| `toAddress` | String | Wallet deposit address |
| `createTime` | Long | Order time (ms) |
| `expireSecond` | Long | Validity period (seconds) |

---

## Wallet Deposit Transactions (Deprecated)

<Warning>
  **Deprecated.** Use the [Wallet v2 Transaction History](/paas/fincard-virtual/wallet) instead.
</Warning>

```bash
POST /api/v2.1/fincard/virtual/account/walletDepositTransaction
```

Paginated query for wallet deposit transactions. Response: `{ total, records[] }`.