Chuyển tới nội dung chính

Lưu ý kỹ thuật

Technical notes and best practices for implementing UFG Business Processes.

1. Message Routing qua UFG​

End-to-End Encryption​

  • UFG KHÔNG decrypt payload
  • Encryption thực hiện giữa Broker và Custody Bank
  • UFG chỉ verify signature và route message

UFG Gateway Role​

2. Idempotency​

Message ID Format​

{MEMBER_ID}-{TYPE}-{YYYYMMDD}-{SEQUENCE}

Ví dụ:

  • BRK00-HOLD-20250126-001
  • CUSTODY00-ACK-20250126-001

Duplicate Detection​

Custody Bank phải track MsgId để:

  • ✅ Phát hiện duplicate requests
  • ✅ Trả về kết quả đã xử lý (idempotent)
  • ✅ Tránh double-processing

3. Timeout & Expiry​

Request Timeout​

Loại RequestTimeout
Query Balance30s
Hold Request60s
Release Request30s
Settlement Confirm120s

Hold Expiry​

Asset TypeDefault Expiry
T+0 Stocks4 hours
T+2 StocksUntil settlement date
DerivativesSession end

Auto-release sau expiry nếuchưa settlement.

4. Error Handling​

Standard Status Codes​

CodeMeaningAction
ACCRAcceptedRequest thành công
RJCTRejectedRequest bị từ chối
PDNGPendingĐang xử lý
CANDCancelled and DoneĐã hủy thành công

Common Error Scenarios​

Insufficient Funds​

<ReqHdlg>
  <StsCd>RJCT</StsCd>
</ReqHdlg>
<SplmtryData>
  <Status>INSUFFICIENT</Status>
</SplmtryData>

Account Not Found​

<Rsn>
  <Cd>NACT</Cd> <!-- No Account -->
</Rsn>

Account Closed​

<Rsn>
  <Cd>CLOS</Cd> <!-- Closed -->
</Rsn>

5. Supplementary Data​

Purpose​

Chứa thông tin bổ sung không thuộc ISO 20022 standard nhưng cần thiết cho business logic.

Common Fields​

<SplmtryData>
  <PlcAndNm>OrderDetails</PlcAndNm>
  <Envlp>
    <OrderRef>ORD-VN30-001</OrderRef>
    <Symbol>VN30F2501</Symbol>
    <Quantity>100</Quantity>
    <Price>15000000</Price>
    <Side>BUY</Side>
  </Envlp>
</SplmtryData>

6. ISIN Codes​

Format Convention​

Asset TypeFormatExample
VN StocksVN000000{SYMBOL}VN000000VN30
VN30 DerivativesVN30F{YYMM}VN30F2501
BondsVN{ISSUER}{MATURITY}VNGOVT2030

7. Settlement Cycle​

T+2 for Stocks​

T+0 for Derivatives​

Settle same day - hold expires end of session.

8. Security Best Practices​

Private Key Management​

  • ❌ NEVER share private key
  • ✅ Store securely on server
  • ✅ Rotate keys periodically
  • ✅ Use HSM for production

Message Validation​

// Pseudo-code
function validateMessage(message) {
  // 1. Verify signature
  if (!verifySignature(message)) {
    throw new Error('Invalid signature');
  }
  
  // 2. Check timestamp
  if (isExpired(message.timestamp)) {
    throw new Error('Message expired');
  }
  
  // 3. Check duplicate
  if (isDuplicate(message.msgId)) {
    return cachedResponse(message.msgId);
  }
  
  // 4. Process
  return processMessage(message);
}

9. Performance Optimization​

Connection Pooling​

Maintain persistent connections to UFG Gateway để giảm latency.

Batch Processing​

Có thể gom nhiều requests trong một batch cho query operations (không áp dụng cho hold/release).

Caching​

Cache query results trong thời gian ngắn (vài giây) để tránh duplicate queries.

10. Monitoring & Logging​

Key Metrics to Monitor​

  • Request/Response latency
  • Success rate per message type
  • Hold expiry rate
  • Duplicate request rate

Logging Requirements​

Log tất cả:

  • MsgId cho mọi request/response
  • Timestamp
  • Status code
  • Error details (nếu có)
{
  "timestamp": "2025-01-26T11:00:00Z",
  "msgId": "BRK00-HOLD-20250126-001",
  "messageType": "camt.048",
  "direction": "outbound",
  "status": "success",
  "latency_ms": 245
}