tingee_ruby_sdk 0.3.0

data/docs/tingee-api-reference.md

@@ -0,0 +1,317 @@
+# Tingee BaaS — verified API reference
+
+Official documentation: **https://developers.tingee.vn/docs/banking/**
+
+Everything here was **observed against the live production API (2026-07-16)**, not
+copied from the docs above. Claims marked `NOT OBSERVED` are unverified. This is
+the contract `Tingee::Client` and `Tingee::Signature` are built against. Where
+this file and the official docs disagree, this file records what the API
+actually did; re-verify against the live API before trusting either.
+
+Redaction: account numbers → last 4, no identity/CCCD, no mobile numbers, no
+client_id/secret_token, no payer PII from memos.
+
+## 0. Auth & signing (OBSERVED)
+
+- Base URL (prod): `https://open-api.tingee.vn`
+- Headers on every request: `x-client-id`, `x-request-timestamp`
+  (`yyyyMMddHHmmssSSS`, **UTC+7**), `x-signature`, `Content-Type: application/json`.
+- Signature: `HMAC_SHA512(secret_token, x-request-timestamp + ":" + JSON.stringify(body))`, **hex** digest.
+- **`body` is `payload || {}`** — a no-body GET signs the string `"{}"`, NOT empty.
+  Signing `""` returns `code 97 Invalid signature`. Confirmed against the official
+  `tingee-node` SDK (`src/signature/signer.ts`, `src/client/http.ts`:
+  `generateSignature(secretKey, timestamp, body || {})`) and a live `get-banks`
+  call. The wire request still omits the body on GET; only the SIGNED string is `"{}"`.
+- Timestamp window: ±10 min of server clock (else error `90`).
+
+Known-good triple from a live `get-banks` GET (the ENV-gated signature test asserts
+this; the secret is not stored here):
+
+```
+timestamp: 20260716155928753
+body:      {}
+signature: 93a3031c8e3a26ede4d4d684cad1f69a459acbfc24deb87a39ed918a6b70f909537105e8f7c491f59932ff9401c5499c8d92a02e6709a8310ddc947255ab4de4
+```
+
+Ruby encoding note: `OpenSSL::HMAC.hexdigest` on a UTF-8 message warns
+"UTF-8 string passed as BINARY" under json 3.0 — the gem `.b`-forces the signing
+string to bytes. The digest of ASCII/UTF-8 bytes is unchanged either way.
+
+## Response envelope
+
+All endpoints return `{code, message, data}`; `code == "00"` is success and the
+gem unwraps and returns `data`. **Exception: `get-banks` returns a bare JSON
+array** — the array IS the success payload.
+
+## 1. get-banks — supported banks (LIVE)
+
+`GET /v1/get-banks`. Row shape:
+`{code, name, bin, shortName, urlLogo, termsAndConditions:{url, urlVA}}`.
+
+**Tingee supports 14 real banks (+ NEXTPAY mPOS).** Napas BIN → Tingee code:
+
+| Bank | Napas BIN | Tingee code | Notes |
+|---|---|---|---|
+| Vietcombank | 970436 | VCB | |
+| VietinBank | 970415 | CTG | |
+| BIDV | 970418 | BIDV | |
+| MB Bank | 970422 | MBB | |
+| ACB | 970416 | ACB | needs register-notify (extra OTP round) |
+| OCB | 970448 | OCB | |
+| VPBank | 970432 | VPB | |
+| Sacombank | 970403 | STB | |
+| VIB | 970441 | VIB | |
+| TPBank | 970423 | TPB | authorizeLink flow |
+| MSB | 970426 | MSB | |
+| PGBank | 970430 | PGB | |
+| Shinhan | 970424 | SHINHAN | |
+| Co-opBank | 970446 | COB | |
+
+**Canonical supported code list** (leaked by a `create-bank-link-session` 400 on
+`allowedBanks`): `OCB, BIDV, MBB, ACB, VPB, PGB, VIB, STB, CTG, VCB, AGRIBANK,
+SHINHAN, COB, MSB, NEXTPAY, TPB`. Note `AGRIBANK` is accepted here but was NOT
+returned by `get-banks` — Agribank is supported (via bank-link) despite the
+get-banks gap.
+
+**❌ NOT supported** (verified absent from both get-banks and allowedBanks):
+**Techcombank (TCB)** — the one large bank genuinely unsupported — plus SHB,
+HDBank, Eximbank, SeABank, NamABank, SCB, LPBank, VietABank, ABBANK, BacABank,
+PVcomBank, NCB, VietCapitalBank, SaigonBank, BaoVietBank, VietBank, GPBank,
+Oceanbank/MBV.
+
+## 2. create-bank-link-session — hosted SDK flow (LIVE)
+
+`POST /v1/create-bank-link-session` with an **empty body** → `code 00`,
+`data` = SDK URL string.
+
+- **No `merchantId` / sub-merchant provisioning needed** for the default merchant —
+  credentials resolve to a merchant directly. Pass `merchantId` only for a
+  sub-merchant.
+- URL returned points at prod (`https://bank-link.tingee.vn?token=…&s=…`) when the
+  configured base is prod. Linking there links a real account.
+- The token is base64 JSON: `{merchantId, type, timestamp, clientId}` — clientId is
+  the public id (not the secret).
+- Optional params: `redirectUrl`, `allowedBanks` (array of Tingee codes),
+  `bankName`, `shopId`.
+
+**Known Tingee bug (2026-07-16, escalated):** the hosted SDK JS crashes on some
+banks with `TypeError: e.confirmId.startsWith is not a function` after the user
+links. It's their frontend bug — the SDK internally calls `create-va` (it holds a
+`confirmId`) and mishandles it. Fallback: the raw create-va chain below, which is
+fully verified.
+
+## 3. Manual link chain — create-va → confirm-va (LIVE, works end-to-end)
+
+> **Redirect-authorize banks (VCB, TPB) use the same endpoint with a different
+> shape:** add `appType:"baas"` + `redirectUrl` and create-va answers with an
+> authorize link (`deepLink` for VCB, `authorizeLink` for TPB) instead of sending an
+> OTP. There is no confirm-va step — the result arrives on your webhook as
+> `status:"confirm-va-success"|"confirm-va-failed"` (§7). Pass your own `requestId`:
+> it is echoed back on that webhook, and **TPB returns no `confirmId` at all**, so it
+> is the only correlation key. One `Client#create_va` covers all shapes; unset params
+> are omitted from the payload.
+
+Bypasses the hosted SDK. Verified flow (Sacombank, real account):
+
+1. `POST /v1/create-va`
+   `{accountType:"personal-account", bankBin, accountNumber, accountName,
+   identity (CCCD), mobile, isNotifyAccountNumber, webhookUrl}`
+   → `data: {confirmId, otpMethod}`.
+   - **`mobile` must be domestic `0`-prefixed** (`09…`); `84…` →
+     `400 mobile must be a valid phone number`.
+   - STB returns `otpMethod:"SmartOTP"` (bank-app OTP, not SMS). No `authorizeLink`
+     (that's TPBank only).
+   - **`isNotifyAccountNumber: false` is the verified-working mode**: a real VietQR
+     transfer to the linked real account fired the payment webhook on a
+     notify=false link. notify=true ("watch the real account") MAY also work but
+     was never confirmed to fire on a plain transfer.
+2. `POST /v1/confirm-va` `{bankBin, confirmId, otpNumber}`
+   → `data: {bankName, accountType, accountNumber, vaAccountNumber, shopId}`.
+   - Bank-side OTP verification **can take minutes** — run in a background job with
+     a raised read timeout, not a web request.
+   - STB needs NO register-notify — confirm-va alone activates. **Only ACB needs
+     the extra step** (§4).
+3. `get-va-paging` then shows the link:
+   `{bankName, bankBin, accountType, accountName, accountNumber:"xxxx…119",
+   vaAccountNumber:"TNG60716171228", status:"active", creationTime, shopId}`.
+
+### The two account numbers (critical)
+
+confirm-va returns BOTH:
+
+- `accountNumber` — the **real** bank account. Money lands here; this is what a
+  customer transfers to and what a QR should show.
+- `vaAccountNumber` — `TNG` + timestamp digits, a **Tingee-internal routing
+  handle**, NOT a transferable account. Store it as your unique routing key for
+  webhooks.
+
+Also store `bankBin` and `shopId` from the response — `delete-va` needs the BIN.
+
+## 4. register-notify — ACB only (LIVE contract)
+
+`POST /v1/register-notify` `{vaAccountNumber, bankBin}` → `data: {confirmId}` —
+run once right after confirm-va succeeds, then
+`POST /v1/confirm-register-notify` `{bankBin, confirmId, otpNumber}` with the
+second OTP.
+
+## 5. get-va-paging (LIVE)
+
+`POST /v1/get-va-paging` (optional `{merchantId}`) → `data: {totalCount, items}`.
+
+## 6. Unlink — delete-va → confirm-delete-va (LIVE)
+
+Tingee is inconsistent about *where* the params ride, but both key the bank by
+**BIN** — verified live:
+
+- `POST /v1/delete-va` — params ride the **QUERY STRING** (not the JSON body):
+  `?bankBin=970403&vaAccountNumber=TNG…`. The bodyless-signing convention still
+  applies (the signed string is `"{}"`). → `data: {confirmId}`.
+- `POST /v1/confirm-delete-va` — params ride the **BODY**:
+  `{bankBin, confirmId, otpNumber}`.
+
+**Trap (2026-07-17):** a `?bankName=STB` variant of delete-va *appears* to work — it
+returns a `confirmId` and the bank really does send an OTP — but the session it opens
+is unconfirmable: confirm-delete-va then fails with
+`"Lỗi hệ thống phương thức xác thực"`. The failure surfaces one step later than the
+mistake, which is what makes it costly to diagnose. Use the BIN on both calls.
+
+Response shape varies by bank: OTP banks return `{confirmId}`, TPB returns an
+`authorizeLink` (owner approves at the bank; a `delete-va-success` webhook finishes
+it), and VCB returns `{}` — already detached, nothing to confirm.
+
+Unlinking is also how per-webhook billing stops for an account (see §9).
+
+## 6b. transaction/get-paging — transaction history (DOC, not yet live-verified)
+
+`POST /v1/transaction/get-paging` → `data: {totalCount, items}`. Body:
+
+- `startTime`, `endTime` — **required**, format `"yyyyMMddHHmmss"` (UTC+7). Each
+  request may span at most a **10-day** window (Tingee errors past that).
+- Optional: `filter` (keyword — tx code/content), `skipCount`, `maxResultCount`,
+  `merchantId` (required for a Master Merchant), `shopIds[]`, `vaAccountNumbers[]`,
+  `bankBin`.
+
+Item shape (per the docs): `{transactionId, accountNumber, amount, type
+(CREDIT/DEBIT), bankBin, bankName, transactionTime, description}`.
+
+## 7. Webhooks
+
+### Payment callback (LIVE, real captured payload)
+
+```json
+{"clientId":"…","transactionCode":"<acct>/FT26197KVBJB","amount":2000,
+ "content":"hello FT26197646813469","bank":"STB","bankBin":"970403",
+ "accountNumber":"<real acct>","vaAccountNumber":"TNG60716173559",
+ "transactionDate":"20260716174026","additionalData":[]}
+```
+
+Field semantics (all confirmed real):
+
+- idempotency key → `transactionCode` (`<accountNumber>/FT<ref>`, unique per txn)
+- amount → `amount` — **integer**, no decimals observed
+- memo → `content` (payer text; the bank may append its FT ref)
+- routing → `vaAccountNumber` (unique per link) or `accountNumber` (real);
+  `bankBin` IS present
+- `transactionDate` — `yyyyMMddHHmmss`
+- `additionalData: []` — empty for a plain transfer; a billId-bound dynamic QR may
+  populate it
+
+**A plain bank transfer (any VietQR / manual transfer into the real account) fires
+the webhook** — no Tingee-minted QR required. Verified with a real transfer.
+
+### Bank-link result callback (redirect-authorize banks)
+
+Redirect-authorize banks (VCB, TPB) have no confirm-va step — the link's outcome
+arrives here instead, on the same endpoint as payments:
+
+```json
+{"requestId":"<the requestId YOU sent to create-va>","status":"confirm-va-success",
+ "vaAccountNumber":"TNG…","accountNumber":"<real acct>","accountName":"NGUYEN VAN A"}
+```
+
+- `status` — `confirm-va-success` | `confirm-va-failed` | `delete-va-success`.
+- **Distinguish it from a payment by SHAPE**: a link result has `status` and NO
+  `transactionCode`; a payment has `transactionCode` and no `status`. The two are
+  disjoint, so branch on that rather than guessing from other fields.
+- Correlate on `requestId` — it echoes the one you sent to create-va. VCB echoes it
+  as `confirmId` in the create-va response too; **TPB returns no confirmId at all**,
+  so your own `requestId` is the only key that works for both.
+- Unlike confirm-va, this payload DOES echo `accountName` — prefer it over whatever
+  the owner typed.
+- `delete-va-success` is best matched on `vaAccountNumber` (authoritative for "which
+  account just detached"); its `requestId` echo is unverified.
+
+### Signature verification (LIVE — raw bytes, resolved 2026-07-16)
+
+Tingee signs the **RAW body bytes exactly as sent**:
+`x-signature = HMAC_SHA512(secret, x-request-timestamp + ":" + raw_body)`.
+
+A genuine payment callback's signature was reproduced from the raw body verbatim.
+Do NOT re-parse/re-serialize — hash raw. (The official `tingee-node` SDK's
+`verifyWebhookSignature` re-serializes via `JSON.stringify(JSON.parse(body))`;
+against the real webhook, raw bytes are what verified. Raw is also immune to
+Ruby-vs-JS number formatting: a re-serialized whole-number float would render
+`250000.0` in Ruby vs `250000` in JS and break a valid signature.)
+Rails: pass `request.raw_post` verbatim to `Tingee::Signature.verify`.
+
+### Connection-test ping (LIVE)
+
+Tingee's dashboard "test webhook" sends
+`{"event":"ping","message":"Tingee Webhook Connection Test","timestamp":<ms>}`
+with **NO `x-signature` / `x-request-timestamp` headers — the ping is UNSIGNED**.
+Your endpoint must short-circuit on `event == "ping"` (or "only verify when the
+signature header is present") and 200-ack, else the dashboard's connection test
+shows failure.
+
+### Ack & retry contract
+
+- Success ack: `{"code":"00","message":"Success"}` at HTTP 200 — Tingee stops
+  retrying on it. Always ack replays too (idempotency on `transactionCode`).
+- Retry interval/count on failure: Tingee's docs conflict (1 min vs 5 min) —
+  `NOT OBSERVED` precisely.
+- Whether `"02"` (already-processed) is honored for replays: `NOT OBSERVED`.
+
+### Registering the webhook
+
+In the Tingee dashboard, register your webhook URL with auth =
+**API Credentials** (HMAC) — not the static API-key option — so callbacks carry
+`x-signature`/`x-request-timestamp`.
+
+## 8. Error codes
+
+| Code | Meaning |
+|---|---|
+| `00` | Success |
+| `90` | Timestamp outside the ±10 min window |
+| `91` | Timeout |
+| `97` | Invalid signature (including the signed-`""`-instead-of-`"{}"` mistake) |
+| `1001`–`1076` | Business errors (undocumented series, codes kept raw) |
+
+The gem raises `Tingee::Error` with the raw code preserved; transport failures are
+normalized to code `"NETWORK"`, non-JSON gateway/WAF pages to `"HTTP_<status>"`.
+
+## 9. Operational notes
+
+- **Billing is per delivered webhook** (check Tingee's current pricing).
+  Delivered ≠ matched — unroutable webhooks still bill. Whether retries
+  bill: `NOT OBSERVED` (ask support).
+- Disabling your own feature flags does NOT stop the meter — **only unlinking
+  (`delete-va` chain) stops webhook billing** for an account.
+- Post-unlink webhook behavior (do they fully stop?): `NOT OBSERVED`.
+- `vaAccountNumber` uniqueness scope (global vs bank-scoped): `NOT OBSERVED`.
+- Outgoing-transfer callbacks (does a debit fire a webhook too?): `NOT OBSERVED` —
+  determines whether the per-webhook cost covers only customer payments or all
+  balance changes.
+
+## 10. Known Tingee bugs (escalated 2026-07-16, off this gem's critical path)
+
+- `/v1/generate-dynamic-qr` returns
+  `500 "Field 'accountNumber' doesn't have a default value"` for a valid documented
+  request (their dashboard mints the same QR fine). Not wrapped by this gem —
+  plain transfers fire the webhook, so dynamic QRs aren't needed for payment
+  confirmation. Unnecessary anyway: `Tingee::VietQR.payload` mints the transfer QR
+  locally, and a plain transfer into the real account fires the webhook whatever
+  minted the QR.
+- Hosted bank-link JS SDK crashes
+  `TypeError: e.confirmId.startsWith is not a function` (§2). Workaround: the raw
+  create-va chain (§3).

data/docs/tingee-vcb-personal-link.md

@@ -0,0 +1,130 @@
+# 🛠️ Tài liệu hướng dẫn tích hợp API — Liên kết tài khoản VCB Cá nhân
+
+> Nguồn: `Tài_liệu_Liên_kết_VCB_Cá_nhân.docx` (Tingee by Heno). Chuyển sang Markdown, giữ nguyên nội dung gốc.
+>
+> **Lưu ý luồng:** VCB cá nhân dùng **deepLink** mở app VCB Digibank để khách xác nhận — KHÔNG có bước `confirm-va` bằng OTP như các ngân hàng khác. Kết quả liên kết trả về **bất đồng bộ qua webhook** (`confirm-va-success` / `confirm-va-failed`).
+
+## I. Tổng quan
+
+Tài liệu này hướng dẫn cách tích hợp API của hệ thống Tingee để thực hiện:
+
+- Liên kết tài khoản VCB cá nhân
+- Nhận webhook khi có kết quả
+
+## II. Hướng dẫn chi tiết
+
+### Bước 1: Đăng ký tài khoản Tingee
+
+Truy cập: <https://app.tingee.vn/>
+
+### Bước 2: Lấy thông tin ứng dụng
+
+Truy cập: **Trang chủ Tingee → Avatar → Developers**
+
+Tại đây bạn sẽ lấy được:
+
+- `x-client-id`
+- `Secret token`
+
+![Trang Developers — ClientId, Secret token, Url webhook](./images/tingee-developers-credentials.png)
+
+## III. API liên kết tài khoản ngân hàng VCB
+
+**Endpoint:** `POST https://open-api.tingee.vn/v1/create-va`
+
+### Headers
+
+| Tên | Kiểu | Mô tả |
+|-----|------|-------|
+| `x-client-id` | string | Định danh ứng dụng (lấy tại mục Developers) |
+| `x-request-timestamp` | string | Dấu thời gian theo định dạng `yyyyMMddHHmmssSSS` |
+| `x-signature` | string | Chuỗi hash HMAC SHA512: `{timestamp}:{requestBodyString}` với Secret token làm key |
+
+### Request Body
+
+| Tên | Kiểu | Mô tả |
+|-----|------|-------|
+| `requestId` | UUID | ID request liên kết tài khoản |
+| `bankName` / `bankBin` | string | Mã code / Mã bin VCB |
+| `mobile` | string | Số điện thoại KH |
+| `merchantId` | number | ID merchant Tingee |
+| `shopId` | number | ID shop muốn liên kết VA (bỏ qua nếu muốn tạo shop mới trên Tingee) |
+| `merchantName` | string | Tên shop của merchant |
+| `merchantAddress` | string | Địa chỉ shop |
+| `accountNumber` | string | Số tài khoản |
+| `accountType` | string | Truyền `personal-account` |
+| `vaPrefix` | string | Mã đầu VA (dùng cho luồng quét QR trên loa để liên kết) |
+| `vaSuffix` | string | Chuỗi VA (dùng cho luồng quét QR trên loa để liên kết) |
+| `appType` | string | Mặc định để `baas` |
+| `redirectUrl` | string | URL để redirect về app FinOne |
+| `webhookUrl` | string | URL nhận webhook kết quả |
+
+### Response
+
+| Tên | Kiểu | Mô tả |
+|-----|------|-------|
+| `code` | string | Mã lỗi |
+| `message` | string | Thông tin lỗi |
+| `data` | object | |
+| `data.confirmId` | string | ID confirm |
+| `data.deepLink` | string | Deeplink mở app VCB |
+
+### Sample
+
+**Request (curl):**
+
+```bash
+curl -X 'POST' \
+  'http://open-api.tingee.vn/v1/create-va' \
+  -H 'accept: */*' \
+  -H 'x-signature: 222da13b161cd6a15f337a4c35a22cf3a0ff375bab494a4ae302d07c27687aa281b7899d7a31eeceb9caad7eb0dab506f880b590c01f49e750329fee54213ab5' \
+  -H 'x-request-timestamp: 20250828140611111' \
+  -H 'x-client-id: 3021ab73e90e72e3a0f01cbfd8f6d604' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "requestId": "000000c4-62bd-4e50-a213-b51e3772074e",
+  "bankName": "VCB",
+  "mobile": "0987665555",
+  "merchantId": 140998,
+  "merchantName": "Cửa hàng số 1",
+  "merchantAddress": "Hà Nội",
+  "accountNumber": "0912323232",
+  "accountType": "personal-account",
+  "appType": "baas",
+  "redirectUrl": "finonemerchant://"
+}'
+```
+
+**Response:**
+
+```json
+{
+  "code": "00",
+  "message": "Success",
+  "data": [
+    {
+      "confirmId": "000000c4-62bd-4e50-a213-b51e3772074e",
+      "deepLink": "vcbpartner://linkPaymentEvent?token=eyJhbGciOiJSUzI1NiJ9...."
+    }
+  ]
+}
+```
+
+## IV. Nhận Webhook thông báo kết quả
+
+- Khi khách hàng xác nhận liên kết xong trên app VCB Digibank, VCB sẽ gửi webhook kết quả về cho Tingee. Từ đó Tingee xử lý dữ liệu rồi gửi webhook lại cho FinOne qua **Webhook URL** mà đối tác đã gửi qua Tingee ở API liên kết tài khoản.
+
+### Dữ liệu Webhook
+
+| Tên | Kiểu | Mô tả |
+|-----|------|-------|
+| `requestId` | string | ID request khi gọi API liên kết |
+| `merchantId` | number | ID Merchant |
+| `shopId` | number | ID shop |
+| `bankName` | string | Mã code VCB |
+| `bankBin` | string | Mã bin VCB |
+| `accountNumber` | string | Số tài khoản |
+| `accountName` | string | Tên chủ tài khoản |
+| `vaAccountNumber` | string | Số tài khoản ảo |
+| `isNotifyAccountNumber` | boolean | `false`: Liên kết và tạo TK ảo |
+| `status` | string | Trạng thái liên kết — `"confirm-va-success"`: Thành công / `"confirm-va-failed"`: Thất bại |

data/lib/tingee/client.rb

@@ -0,0 +1,205 @@
+require "net/http"
+require "json"
+require "uri"
+
+module Tingee
+  # HTTP + endpoint methods. Only live-verified endpoints are wrapped — no
+  # speculative "complete SDK". Responses use a uniform {code, message, data}
+  # envelope EXCEPT get-banks, which returns a bare array (verified live).
+  class Client
+    # read_timeout: web requests keep the 90s default (stay under your proxy's
+    # response timeout); background jobs should pass a larger value — bank-side
+    # OTP verification on confirm_va can take minutes.
+    def initialize(config = Tingee.config, read_timeout: 90)
+      @config = config
+      @read_timeout = read_timeout
+      @config.validate!
+    end
+
+    # GET /v1/get-banks — returns the bare bank array (the supported-bank/BIN map).
+    def get_banks
+      get("/v1/get-banks")
+    end
+
+    # POST /v1/create-bank-link-session — returns the SDK URL string (data). No
+    # merchant_id is needed for the default merchant; pass one only for a sub-merchant.
+    def create_bank_link_session(merchant_id: nil, redirect_url: nil, allowed_banks: nil, bank_name: nil, shop_id: nil)
+      payload = { type: "bank-link" }
+      payload[:merchantId]   = merchant_id          if merchant_id
+      payload[:redirectUrl]  = redirect_url         if redirect_url
+      payload[:allowedBanks] = Array(allowed_banks) if allowed_banks
+      payload[:bankName]     = bank_name            if bank_name
+      payload[:shopId]       = shop_id              if shop_id
+      post("/v1/create-bank-link-session", payload)
+    end
+
+    # POST /v1/get-va-paging — returns {totalCount, items} of linked virtual accounts.
+    def get_va_paging(merchant_id: nil)
+      payload = {}
+      payload[:merchantId] = merchant_id if merchant_id
+      post("/v1/get-va-paging", payload)
+    end
+
+    # POST /v1/create-va — starts a bank link (the raw API chain, usable when Tingee's
+    # hosted JS SDK is unavailable or broken — docs/tingee-api-reference.md §create-va,
+    # live-verified). ONE method serves all three bank shapes; which one you get is
+    # decided by the bank, not by a different endpoint:
+    #
+    #   OTP banks (STB, ACB, MBB, …) — pass account_number/account_name/identity/mobile.
+    #     The bank sends/pushes an OTP to `mobile`. Returns {confirmId, otpMethod};
+    #     finish with #confirm_va.
+    #   Redirect-authorize banks (VCB) — additionally pass app_type: "baas" +
+    #     redirect_url + request_id. Returns an authorizeLink/deepLink instead of
+    #     sending an OTP; the owner confirms in the bank's app and the result arrives
+    #     asynchronously on webhook_url as {status: "confirm-va-success"|"confirm-va-failed"}.
+    #     There is NO confirm_va step for these.
+    #   No-account-field banks (TPB, doc-sourced) — pass neither account nor identity
+    #     fields; the owner picks the account on the bank's own web. TPB returns NO
+    #     confirmId at all, so the request_id YOU send is the only key that can
+    #     correlate the settle webhook back to your pending request. Always pass and
+    #     STORE your own request_id for any redirect-authorize flow.
+    #
+    # Every optional field is omitted from the payload when nil, so a bank only ever
+    # receives the params its contract actually defines (VCB tolerates and overrides
+    # what it doesn't use — verified live; TPB's contract has none of them).
+    #
+    # is_notify_account_number: FALSE is the DEFAULT because it is the mode proved
+    # end-to-end — a real VietQR transfer to the linked real account fired the webhook
+    # on a notify=false link (2026-07-16). notify=true is documented as "watch the real
+    # account" and MAY also work, but was never confirmed to fire on a plain transfer;
+    # do not switch the default to true without a real-transfer test on a true link.
+    def create_va(bank_bin:, webhook_url:, account_number: nil, account_name: nil,
+                   identity: nil, mobile: nil, account_type: "personal-account",
+                   is_notify_account_number: false, app_type: nil, redirect_url: nil,
+                   request_id: nil, merchant_id: nil, merchant_name: nil,
+                   merchant_address: nil, shop_id: nil, va_prefix: nil, va_suffix: nil)
+      payload = {
+        accountType: account_type, bankBin: bank_bin,
+        isNotifyAccountNumber: is_notify_account_number,
+        webhookUrl: webhook_url
+      }
+      payload[:accountNumber]   = account_number   if account_number
+      payload[:accountName]     = account_name     if account_name
+      payload[:identity]        = identity         if identity
+      payload[:mobile]          = mobile           if mobile
+      payload[:appType]         = app_type         if app_type
+      payload[:redirectUrl]     = redirect_url     if redirect_url
+      payload[:requestId]       = request_id       if request_id
+      payload[:merchantId]      = merchant_id      if merchant_id
+      payload[:merchantName]    = merchant_name    if merchant_name
+      payload[:merchantAddress] = merchant_address if merchant_address
+      payload[:vaPrefix]        = va_prefix        if va_prefix
+      payload[:vaSuffix]        = va_suffix        if va_suffix
+      # One shop per project; an explicit arg wins over the configured default.
+      shop_id ||= @config.shop_id
+      payload[:shopId]          = shop_id          if shop_id
+      post("/v1/create-va", payload)
+    end
+
+    # POST /v1/confirm-va — finishes the link with the bank's OTP. Returns
+    # {bankName, accountType, accountNumber (real), vaAccountNumber (routing key), shopId}.
+    def confirm_va(bank_bin:, confirm_id:, otp_number:)
+      post("/v1/confirm-va", { bankBin: bank_bin, confirmId: confirm_id, otpNumber: otp_number })
+    end
+
+    # POST /v1/register-notify — ACB only, run once right after confirm_va succeeds.
+    # Returns {confirmId} for a second OTP round (see #confirm_register_notify).
+    def register_notify(bank_bin:, va_account_number:)
+      post("/v1/register-notify", { vaAccountNumber: va_account_number, bankBin: bank_bin })
+    end
+
+    def confirm_register_notify(bank_bin:, confirm_id:, otp_number:)
+      post("/v1/confirm-register-notify", { bankBin: bank_bin, confirmId: confirm_id, otpNumber: otp_number })
+    end
+
+    # POST /v1/delete-va — starts an unlink. Params ride the QUERY STRING (not the
+    # JSON body); the bank is identified by `bankBin`, per the documented contract.
+    #
+    # A `bankName` variant (Tingee's short bank CODE, e.g. "STB") also returns a
+    # confirmId AND triggers the bank's OTP, so it looks like it worked — but the
+    # session it creates cannot be confirmed: #confirm_delete_va then 400s with
+    # "Lỗi hệ thống phương thức xác thực" (seen live 2026-07-17). Do not reintroduce
+    # it. Unlink is the only way to stop Tingee's per-webhook billing, so an unlink
+    # that silently cannot complete is expensive.
+    #
+    # Returns {confirmId} (OTP banks). Bank-shape variations — TPB answers with an
+    # authorizeLink, VCB returns {} because it detaches immediately — are the caller's
+    # to branch on; see docs/tingee-api-reference.md §6.
+    def delete_va(bank_bin:, va_account_number:)
+      request(:post, "/v1/delete-va", query: { bankBin: bank_bin, vaAccountNumber: va_account_number })
+    end
+
+    # POST /v1/confirm-delete-va — finishes the unlink with the bank's OTP. Params
+    # ride the BODY this time (unlike delete_va's query string above), and the bank
+    # is identified by bankBin here — bankName gets ignored and Tingee then fails
+    # with "Lỗi hệ thống phương thức xác thực" (seen live 2026-07-17).
+    def confirm_delete_va(bank_bin:, confirm_id:, otp_number:)
+      post("/v1/confirm-delete-va", { bankBin: bank_bin, confirmId: confirm_id, otpNumber: otp_number })
+    end
+
+    # POST /v1/transaction/get-paging — transaction history. `start_time`/`end_time`
+    # are required, format "yyyyMMddHHmmss" (UTC+7); Tingee caps each query at a
+    # 10-day window (over that it returns an error — not enforced here). Optional
+    # params are only sent when given. Returns {totalCount, items}.
+    def get_transactions(start_time:, end_time:, filter: nil, skip_count: nil, max_result_count: nil,
+                         merchant_id: nil, shop_ids: nil, va_account_numbers: nil, bank_bin: nil)
+      payload = { startTime: start_time, endTime: end_time }
+      payload[:filter]           = filter                   if filter
+      payload[:skipCount]        = skip_count               if skip_count
+      payload[:maxResultCount]   = max_result_count         if max_result_count
+      payload[:merchantId]       = merchant_id              if merchant_id
+      payload[:shopIds]          = Array(shop_ids)          if shop_ids
+      payload[:vaAccountNumbers] = Array(va_account_numbers) if va_account_numbers
+      payload[:bankBin]          = bank_bin                 if bank_bin
+      post("/v1/transaction/get-paging", payload)
+    end
+
+    private
+
+    def get(path)        = request(:get, path)
+    def post(path, body) = request(:post, path, body)
+
+    def request(method, path, payload = nil, query: nil)
+      signed_body = JSON.generate(payload || {}) # bodyless request signs "{}", not ""
+      ts  = Signature.timestamp
+      sig = Signature.generate(secret: @config.secret_token, timestamp: ts, body: signed_body)
+      uri = URI.join(@config.base_url, path)
+      uri.query = URI.encode_www_form(query) if query # delete-va reads query params, not the body
+
+      req = (method == :get ? Net::HTTP::Get : Net::HTTP::Post).new(uri)
+      req["Content-Type"]        = "application/json"
+      req["x-client-id"]         = @config.client_id
+      req["x-request-timestamp"] = ts
+      req["x-signature"]         = sig
+      req.body = signed_body unless method == :get
+
+      parse(perform(uri, req))
+    end
+
+    # Transport seam — tests override with canned responses (see client_test.rb).
+    def perform(uri, req)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 10
+      http.read_timeout = @read_timeout
+      http.request(req)
+    rescue Timeout::Error, SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
+      # Normalize transport failures to Tingee::Error so callers handle one error type —
+      # a bare timeout mid-link would otherwise crash the caller and strand the flow.
+      raise Error.new("NETWORK", e.message)
+    end
+
+    def parse(res)
+      body = res.body.to_s.empty? ? nil : JSON.parse(res.body)
+      return body if body.is_a?(Array) # get-banks: a bare array IS the success payload
+
+      raise Error.new("HTTP_#{res.code}", res.body.to_s) unless body.is_a?(Hash)
+      raise Error.new(body["code"], body["message"]) unless body["code"] == "00"
+
+      body["data"]
+    rescue JSON::ParserError
+      # A gateway/WAF error page (non-JSON) — surface as Tingee::Error, not a raw parse crash.
+      raise Error.new("HTTP_#{res.code}", res.body.to_s)
+    end
+  end
+end

data/lib/tingee/configuration.rb

@@ -0,0 +1,21 @@
+module Tingee
+  # Injected credentials — set via Tingee.configure (e.g. from a Rails initializer);
+  # this layer never reads any credential store itself.
+  class Configuration
+    # shop_id: every VA this app creates is grouped under one Tingee shop
+    # (one shop per project). Optional: nil sends no shopId and Tingee
+    # auto-creates a throwaway shop per link.
+    attr_accessor :client_id, :secret_token, :base_url, :shop_id
+
+    def initialize
+      @base_url = "https://open-api.tingee.vn"
+    end
+
+    # Called when a client is built, not at load — a credential-less env still boots.
+    def validate!
+      return if client_id && secret_token
+
+      raise Error.new("CONFIG", "Missing Tingee credentials (client_id, secret_token) — set them via Tingee.configure")
+    end
+  end
+end