VPBank Securities NEO Invest API integration & OpenFinance protocol analysis

1. Authentication & session bridge

Reproducible login flow with username/password + OTP, device-binding token, and silent session refresh. Used by reconciliation services that need to pull statements after midnight without human intervention. Output: token store, refresh hook, and audit log of every authentication event.

2. Order book & placement

Place LO, ATO, ATC, MP, MTL, MOK, MAK, and stop-conditional orders on HOSE / HNX / UPCoM through the same channels NEO Invest exposes after the KRX migration. Use cases: algorithmic execution, smart-order routing, or simply pushing approved trades from a portfolio management system.

3. Portfolio & P/L analytics

Daily holdings snapshot, realized vs unrealized P/L per ticker, tax lot tracking, and corporate-action adjustments (cash dividend, stock dividend, bonus shares, splits). Designed to feed wealth-tech dashboards, robo-advisor backtesting, and 1099-equivalent retail tax tools.

4. Statement & cash-flow export

Date-ranged statement export for trades, cash transfers, margin interest, and fees in CSV/JSON/Excel. Typical buyers: outsourced accounting firms reconciling client portfolios into MISA, Bravo, or SAP accounts receivable modules.

5. Market data & stock screener

Streaming top-of-book and 5-level depth, intraday tick history, plus the same multi-criteria filter NEO Invest exposes (trading volume, transaction value, % change, foreign room, EPS, P/E, P/B). Suitable for screener websites, Telegram trading bots, and quantitative research notebooks.

6. Research feed bridge

Pull VPBankS analyst notes, sector reports, target-price changes, and macro briefings from the in-app research panel. Pipe them into Slack, Notion, or compliance review workflows so investment committees see the same primary source as retail users.

A. Family-office consolidated reporting

A multi-broker family office holds positions at NEO Invest plus SSI iBoard Pro and TCBS TCInvest. We publish a unified /v1/positions and /v1/transactions endpoint that maps each broker's payload into a single schema (ticker, qty, avg_cost, currency, broker_id). The NEO Invest connector authenticates, pulls daily statements, and pushes them into the family office's data lake. OpenFinance angle: the same pattern Vietnam's Circular 64/2024/TT-NHNN encourages for cross-institution data sharing.

B. Accounting & tax automation

An outsourced accounting firm in Ho Chi Minh City onboards retail clients who use NEO Invest. Our connector calls /statement at month-end with date ranges, normalizes fee/tax fields into Vietnamese chart-of-account codes, and pushes journal entries into MISA SME. Capital gains, dividend withholding, and margin interest expense are reconciled automatically — reducing month-end close from days to hours.

C. Quant research and screener sites

A fintech publisher wants to expose a stock screener powered by NEO Invest's real-time filter logic. We deliver a hosted /screener endpoint accepting JSON criteria (volume range, %change, P/E ceiling, foreign-room threshold). The publisher charges visitors a SaaS subscription; our pay-per-call billing keeps unit economics predictable.

D. Compliance & surveillance for prop desks

A proprietary trading desk requires full execution audit. The connector streams every order placement, modification, and cancellation as it happens, plus hourly portfolio snapshots, into a Kafka topic. Their surveillance system flags wash trades, front-running, and suspicious size against VN30 cash equities and VN30 index futures. Aligns with State Securities Commission of Vietnam (SSC) supervisory expectations.

E. Cross-app investor dashboards

A wealth app aggregates VPBank current account balance (via VPBank NEO bank app channel), VPBank Securities NEO Invest positions, and a third-party gold tracker into one view. End users see net worth across products of the same financial group, an "OpenFinance light" experience that does not require formal Open Banking license but stays within the user-consented envelope our compliance pack documents.

Authenticate & refresh session

// POST /v1/neoinvest/auth/login
{
  "username": "VPBKS123456",
  "password": "***",
  "otp": "458210",
  "device_id": "srv-bot-01"
}

// 200 OK
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "rtk_...",
  "expires_in": 1800,
  "account_no": "067C123456",
  "channel": "neo-invest"
}

// POST /v1/neoinvest/auth/refresh
Authorization: Bearer <refresh_token>

Place a HOSE limit order (KRX-compatible)

POST /v1/neoinvest/orders
Authorization: Bearer <ACCESS_TOKEN>
Idempotency-Key: 4f9c-2025-11-04-001

{
  "account_no": "067C123456",
  "symbol": "VPB",
  "exchange": "HOSE",
  "side": "BUY",
  "type": "LO",
  "price": 22500,
  "quantity": 1000,
  "validity": "DAY"
}

// 201 Created
{ "order_id":"ORD-7781","status":"PENDING_NEW","matched_qty":0 }
// Webhook on fill
POST /your/webhook  { "order_id":"ORD-7781","status":"FILLED",
  "matched_qty":1000,"avg_price":22510,"fee":33765 }

Pull statement & portfolio

GET /v1/neoinvest/statement
  ?account_no=067C123456
  &from=2025-10-01&to=2025-10-31&format=json

// Response (truncated)
{
  "currency":"VND",
  "opening_balance":143200000,
  "closing_balance":151870500,
  "lines":[
    {"date":"2025-10-03","type":"BUY","symbol":"FPT",
     "qty":200,"price":136500,"fee":40950,"tax":0},
    {"date":"2025-10-15","type":"DIV_CASH","symbol":"VPB",
     "qty":1000,"amount":1000000,"tax_pct":5}
  ]
}

GET /v1/neoinvest/portfolio?account_no=067C123456

Real-time stock filter

POST /v1/neoinvest/screener
{
  "exchange":["HOSE","HNX","UPCOM"],
  "filters":{
     "volume_min":500000,
     "pct_change":{"min":2,"max":15},
     "pe_max":18,
     "foreign_room_pct_min":3
  },
  "sort":"value_traded:desc",
  "limit":50
}

// 200 OK -> array of {symbol, last, change_pct,
//   volume, value, pe, pb, foreign_room}