Technical Notes

Technical notes and best practices for implementing UFG Business Processes.

1. Message Routing via UFG

End-to-End Encryption

• UFG DOES NOT decrypt payload
• Encryption is performed between Broker and Custody Bank
• UFG only verifies signature and routes message

UFG Gateway Role

2. Idempotency

Message ID Format

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

Example:

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

Duplicate Detection

Custody Bank must track MsgId to:

• ✅ Detect duplicate requests
• ✅ Return processed results (idempotent)
• ✅ Avoid double-processing

3. Timeout & Expiry

Request Timeout

Request Type	Timeout
Query Balance	30s
Hold Request	60s
Release Request	30s
Settlement Confirm	120s

Hold Expiry

Asset Type	Default Expiry
T+0 Stocks	4 hours
T+2 Stocks	Until settlement date
Derivatives	Session end

Auto-release after expiry if not settled.

4. Error Handling

Standard Status Codes

Code	Meaning	Action
ACCR	Accepted	Request successful
RJCT	Rejected	Request rejected
PDNG	Pending	Processing
CAND	Cancelled and Done	Cancelled successfully

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

Contains additional information not part of ISO 20022 standard but necessary for 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 Type	Format	Example
VN Stocks	VN000000{SYMBOL}	VN000000VN30
VN30 Derivatives	VN30F{YYMM}	VN30F2501
Bonds	VN{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 to reduce latency.

Batch Processing

Can batch multiple requests for query operations (not applicable for hold/release).

Caching

Cache query results for a short time (few seconds) to avoid 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 all:

• MsgId for every request/response
• Timestamp
• Status code
• Error details (if any)

{
  "timestamp": "2025-01-26T11:00:00Z",
  "msgId": "BRK00-HOLD-20250126-001",
  "messageType": "camt.048",
  "direction": "outbound",
  "status": "success",
  "latency_ms": 245
}