Skip to main content
PUT
/
trading
/
oa
/
sub-accounts
/
{subAccountId}
/
orders
/
{orderId}
cURL
BODY='{"quantity":200,"price":26000}'
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')

curl -X PUT \
  -H "X-FH-APIKEY: $FINHAY_API_KEY" \
  -H "X-FH-TIMESTAMP: $TIMESTAMP_MS" \
  -H "X-FH-NONCE: $NONCE_UUID" \
  -H "X-FH-SIGNATURE: $SIGNATURE_HEX" \
  -H "X-FH-BODYHASH: $BODY_HASH" \
  -H "X-FH-2FA-TOKEN: $FINHAY_2FA_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$BODY" \
  "https://open-api.fhsc.com.vn/trading/oa/sub-accounts/$SUB_ACCOUNT_NORMAL/orders/ORD123456"
{
  "error_code": "0",
  "message": "success",
  "result": [
    {
      "order_id": "ORD123456",
      "account_id": "120C000008.1",
      "transaction_date": "2026-05-28",
      "symbol": "HPG",
      "order_side": "BUY",
      "order_quantity": 200,
      "limit_price": 26000,
      "market_price": null,
      "execute_quantity": 0,
      "execute_price": 0,
      "order_status": "SENT",
      "fee_amount": 0,
      "tax_amount": 0,
      "execute_amount": 0,
      "order_type": "LO",
      "code": null,
      "rejected_reason": null,
      "lot": "EVEN"
    }
  ]
}

Authorizations

​
X-FH-APIKEY
string
header
required

API key dài hạn của client. Cấu hình 1 lần lúc khởi tạo; có thể wire thẳng vào static setter của SDK tự-gen. Đi kèm với FINHAY_API_SECRET — secret này chỉ dùng ở phía client để tính X-FH-SIGNATURE, không bao giờ gửi qua mạng.

​
X-FH-TIMESTAMP
string
header
required

Unix time hiện tại tính bằng milliseconds, đưới dạng chuỗi số thập phân.

Được tính per-request bởi signing middleware. Không set thủ công — dùng middleware mẫu trong README.

​
X-FH-NONCE
string
header
required

UUIDv4 duy nhất per-request (ví dụ crypto.randomUUID()). Server cache cặp (apiKey, nonce) trong 5 phút; nếu nonce được reuse với cùng apiKey trong window này, request sẽ bị từ chối với AUTH_NONCE_REUSED (401).

Server chấp nhận chuỗi opaque bất kỳ về mặt kỹ thuật, nhưng nên dùng UUIDv4 để đảm bảo tính unique.

Được tính per-request bởi signing middleware. Không set thủ công — xem middleware mẫu trong tài liệu Authentication.

​
X-FH-SIGNATURE
string
header
required

HMAC-SHA256 của canonical signing payload, encode hex (lowercase).

Signing payload:

{X-FH-TIMESTAMP}\n{METHOD}\n{REQUEST_PATH}[?{QUERY}]\n{BODYHASH}
  • ?{QUERY} chỉ nối vào path khi request có query string.
  • {BODYHASH} là chuỗi rỗng khi body rỗng (vẫn không có newline sau đó).

Được tính per-request bởi signing middleware. Không set thủ công — dùng middleware mẫu trong README.

​
X-FH-BODYHASH
string
header
required

SHA-256 của raw request body, encode hex (lowercase). Bắt buộc khi request có body (POST / PUT / PATCH). Có thể bỏ qua — hoặc gửi chuỗi rỗng — khi body rỗng.

Là segment cuối của canonical signing payload ({timestamp}\n{method}\n{path}[?{query}]\n{bodyHash}). Server dùng giá trị client gửi lên để verify chữ ký; server không tự hash lại body, nên client phải hash đúng chuỗi bytes đã gửi đi.

Được tính per-request bởi signing middleware. Không set thủ công — xem middleware mẫu trong tài liệu Authentication.

​
X-FH-2FA-TOKEN
string
header
required

Daily 2FA session JWT do server cấp sau khi user xác thực qua OTP. Áp dụng cho các write operation nhạy cảm (đặt / sửa / huỷ lệnh) — phải đi cùng đủ 4 header HMAC + X-FH-BODYHASH.

Token có tuổi thọ 1 ngày giao dịch và được scope theo apiKey. Khi hết hạn hoặc bị revoke, server trả HTTP 403 với 1 trong các error_code:

  • OTP_SESSION_REQUIRED — chưa có session, cần khởi tạo OTP flow.
  • OTP_SESSION_EXPIRED — session đã hết hạn.
  • OTP_SESSION_INVALID — token không hợp lệ / chữ ký sai.
  • OTP_SESSION_REVOKED — bị thu hồi (user logout, đổi key, …).

Khi gặp 403 thuộc các mã trên, client phải chạy lại OTP flow để xin token mới rồi retry request.

Path Parameters

​
subAccountId
string
required

subAccountId được lấy từ bootstrap flow (GET /users/v1/users/{userId}/sub-accounts), chọn NORMAL hoặc MARGIN tuỳ mục đích.

Example:

"0001234567"

​
orderId
string
required

ID lệnh trên sàn — lấy từ field order_id trong response của POST /trading/oa/sub-accounts/{subAccountId}/orders (Place Order) hoặc từ GET /trading/v1/accounts/{subAccountId}/order-book (sổ lệnh trong ngày). Bắt buộc khi sửa hoặc huỷ lệnh.

Example:

"ORD123456"

Body

application/json

Body của request sửa lệnh (PUT /trading/oa/sub-accounts/{subAccountId}/orders/{orderId}). Cả 2 field đều optional nhưng phải có ít nhất 1.

Chỉ sửa được trên phần lệnh chưa khớp và khi trạng thái lệnh thuộc SENT hoặc WAITING_TO_SEND. Với lệnh đã khớp một phần, server sẽ return code = -701111 và sửa chỉ áp dụng cho phần unmatched.

​
quantity
integer<int64>

Số lượng mới (bội số lot size).

Required range: x >= 1
Example:

200

​
price
integer<int64>

Giá limit mới, đơn vị VND (không nhân 1000).

Required range: x >= 1
Example:

26000

Response

Server đã xử lý request. Phải đọc result[].code — non-null nghĩa là sàn từ chối hoặc lệnh đã khớp một phần (-701111).

Các field chung của envelope trong mọi response của Finhay API.

  • error_code là "0" (string) khi thành công, mã khác "0" khi lỗi.
  • message là thông điệp ngắn từ server.
​
result
object[]
required

Mảng kết quả — thông thường chứa đúng 1 entry phản ánh trạng thái lệnh sau khi sửa. Khi lệnh đã khớp một phần, server có thể trả code = -701111 nghĩa là chỉ sửa được phần unmatched.

​
error_code
string

"0" khi thành công, khác "0" khi lỗi.

Example:

"0"

​
message
string

Thông điệp trạng thái dễ đọc.

Example:

"success"