Giá Vàng - Tỷ Giá Ngoại Tệ API integration (SJC gold & VCB FX)

Deliverables checklist

• OpenAPI 3.1 specification for gold, FX, history, and account endpoints
• Protocol report covering app's HTTP traffic, caching, and signature scheme
• Python (FastAPI) and Node.js (NestJS) reference source — runnable on a single VM
• Postman collection with sample SJC/DOJI/PNJ and VCB payloads
• Compliance brief mapped to State Bank of Vietnam Decree 24 / 232/2025/ND-CP guidance

Pricing & engagement

Two engagement models: source-code delivery from $300 with payment after acceptance, or pay-per-call access to our hosted endpoints with zero upfront cost. NDAs supported. Most teams start on the source-code model and graduate to hosted billing once their integration is stable.

1. Jewellery e-commerce price stamp

A Vietnamese jewellery retailer wants every product detail page to quote a live SJC reference plus a vendor-specific markup. Our /v1/gold/spot?vendor=sjc&branch=hcm endpoint returns the latest buy/sell pair; the storefront caches for 60 seconds and falls back to the previous tick on upstream failure.

2. Treasury FX-lock workflow

An import-export firm books USD-VND invoices and wants to pin Vietcombank's transfer rate at the moment of order acceptance. The integration calls /v1/fx/vcb?currency=USD, stores the buy_transfer value with the order, and emits an OpenFinance-style Statement.Lock event that the ERP picks up.

3. Risk dashboard with chart back-fill

A fintech analytics team needs 1-year SJC and world-gold spreads. The historical endpoint /v1/gold/history?instrument=sjc&range=1y returns daily OHLC; combined with FX history this powers a Grafana panel that plots Vietnam premium versus the London PM fix.

4. Compliance audit log

Following the SBV's August 2025 reform of bullion licensing, a licensee must keep an immutable record of the SJC reference at the time of each transaction over 20 million VND. Our webhook fires once per material price move and writes signed records into the audit store.

5. Market-sentiment overlay

A trading-signals product overlays gold price moves with crowd commentary. The comments mirror exposes /v1/social/threads?instrument=sjc with pagination, like/dislike counts and language tags so an NLP layer can score sentiment without scraping the mobile app directly.

Spot price endpoint

GET /v1/gold/spot?vendor=sjc&branch=hcm
Authorization: Bearer <ACCESS_TOKEN>
Accept: application/json

200 OK
{
  "vendor": "sjc",
  "branch": "hcm",
  "buy":  { "amount": 121500000, "unit": "VND/tael" },
  "sell": { "amount": 124000000, "unit": "VND/tael" },
  "as_of": "2026-05-03T08:14:32+07:00",
  "source_hash": "a91f…"
}

Vietcombank FX call

GET /v1/fx/vcb?currency=USD&date=2026-05-03
Authorization: Bearer <ACCESS_TOKEN>

200 OK
{
  "currency": "USD",
  "buy_cash":     25430.0,
  "buy_transfer": 25460.0,
  "sell":         25800.0,
  "as_of":        "2026-05-03T08:00:00+07:00",
  "source":       "vietcombank.com.vn/api/exchangerates"
}

Webhook on price move

POST https://your-app.example/webhook
X-Signature: sha256=…
Content-Type: application/json

{
  "event":     "gold.price.changed",
  "vendor":    "sjc",
  "delta_pct": 0.42,
  "previous":  { "buy": 121000000, "sell": 123500000 },
  "current":   { "buy": 121500000, "sell": 124000000 },
  "as_of":     "2026-05-03T08:14:32+07:00"
}

# Verify HMAC, then enqueue downstream job
# Retries: 3x with 30s/2m/10m back-off

Auth & error contract

OAuth 2.0 client-credentials with 1-hour access tokens; refresh via long-lived refresh token bound to your tenant. All endpoints return RFC 7807 problem-detail bodies on error, with stable codes such as upstream_unavailable, rate_limited and stale_quote so retry policies stay deterministic.

Vietnam-specific framework

Gold trading in Vietnam is governed by Decree 24/2012/ND-CP, recently amended by Decree 232/2025/ND-CP, which ended the state monopoly on bullion production and introduced an SBV licensing regime. We map each integration to the relevant article — for example, the 20-million-VND payment-account rule for gold transactions — and add the necessary audit logging and consent records.

Data protection

Personal data (account login, comments) is processed under Vietnam's Personal Data Protection Decree (PDPD, 13/2023/ND-CP), with optional GDPR alignment for EU consumers. We implement data minimisation, retention windows, and signed delete requests; PII never leaves the customer's region without explicit instruction.

About OpenFinance Lab

We are an independent studio focused on protocol analysis and OpenData/OpenFinance integrations for mobile financial apps. Our engineers come from banks, payment processors, and Asia-Pacific fintech teams — we know Vietnam's gold and FX rails as well as PSD2 and PDPD, and we ship end-to-end APIs under real security and compliance constraints.

• Vietnam fintech: SJC/DOJI/PNJ gold, VCB/BIDV FX, e-wallet protocol analysis
• Pan-APAC: UPI (India), PromptPay (Thailand), PayNow (Singapore), GCash (Philippines)
• Custom Python / Node.js / Go SDKs and test harnesses
• Full pipeline: protocol analysis → build → validation → compliance brief
• Source-code delivery from $300; pay after acceptance
• Pay-per-call hosted API — no upfront fee, ideal for usage-based teams

Contact

For quotes or to submit your target app and requirements, open our contact page:

Contact page

Engagement workflow

1. Scope confirmation: which feeds (SJC, DOJI, PNJ, VCB, BIDV), which history depth, which downstream system.
2. Protocol analysis and source mapping (2–4 business days)
3. Build and internal validation against live upstream sources (3–6 business days)
4. Docs, samples, and Postman collection (1–2 business days)
5. Typical first delivery: 5–12 business days; high-frequency or institutional setups may extend timelines.

FAQ

Which gold and FX sources can you wire in?

How fresh is the data?

Is scraping SJC and Vietcombank pages compliant?

How long does delivery take and what do I get?