tingee_ruby_sdk 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b8c34e49cceee99dc1a94785dde20511c8e405d9fd3dce14289d8e70aec951f4
+  data.tar.gz: 6dfa9725570c35cf7d9cc43f701bfb857840d671e682de02d38e9f3dc035cbae
+SHA512:
+  metadata.gz: 5c9d96ed98a6ccf7531754b91bfaecfe67e13a58e5436a19ba51930cc93c6e2f3241d916b71b4e42d9ef35af146eaecfea59c859b2e87d66ee7b53a64dc2eda9
+  data.tar.gz: bf2ebfb597a85e3162fa01f7491d86953504a50af5f95a91553cffe489622b73bd11456e65f9b490632c8842229bfcf64ede7d516318217db3e9f38c2069a72f

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lpwanw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,337 @@
+# tingee_ruby_sdk
+
+[![Gem Version](https://img.shields.io/gem/v/tingee_ruby_sdk)](https://rubygems.org/gems/tingee_ruby_sdk)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE.txt)
+
+Ruby client for the [Tingee](https://tingee.vn) BaaS API (`open-api.tingee.vn`) —
+bank account linking, virtual accounts, and payment webhooks for Vietnamese banks.
+Official API docs: [developers.tingee.vn/docs/banking](https://developers.tingee.vn/docs/banking/).
+
+- **Pure Ruby, zero runtime dependencies.** `net/http`, `openssl`, `json` only. No
+  Rails required (enforced by a boundary test).
+- **Built from a live-verified API contract.** Every wrapped endpoint and every
+  signing rule in this gem was observed against the production API (2026-07-16),
+  not copied from marketing docs. The full observed contract, including Tingee's
+  quirks and known bugs, lives in [`docs/tingee-api-reference.md`](docs/tingee-api-reference.md).
+- **Only verified endpoints are wrapped** — no speculative "complete SDK".
+- **VietQR payment codes are minted locally** — no `img.vietqr.io` round-trip, no API
+  call. See [VietQR payment codes](#vietqr-payment-codes).
+
+> **Building the full auto-confirm feature?** Follow
+> [`docs/bank-auto-confirm-integration-guide.md`](docs/bank-auto-confirm-integration-guide.md) —
+> a complete app-side playbook (data model, link state machine, webhook endpoint,
+> payment matching, go-live checklist) distilled from a production integration.
+> Written so you can hand the link to an AI coding agent and it knows what to build.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "tingee_ruby_sdk", "~> 0.3"
+```
+
+```sh
+gem install tingee_ruby_sdk
+```
+
+Requires Ruby >= 3.2. Or track unreleased work:
+
+```ruby
+gem "tingee_ruby_sdk", github: "lpwanw/tingee_ruby_sdk"   # main
+gem "tingee_ruby_sdk", path: "../tingee_ruby_sdk"         # local checkout
+```
+
+## Configuration
+
+Credentials are injected — the gem never reads any credential store itself:
+
+```ruby
+# e.g. config/initializers/tingee.rb in a Rails app
+Tingee.configure do |c|
+  c.client_id    = ENV["TINGEE_CLIENT_ID"]      # or Rails credentials, etc.
+  c.secret_token = ENV["TINGEE_SECRET_TOKEN"]
+  # c.base_url = "https://open-api.tingee.vn"   # default (production)
+  # c.shop_id  = 252011  # optional: group every VA under ONE Tingee shop (one shop
+                         # per project); unset, Tingee auto-creates a shop per link
+end
+```
+
+Validation happens when a client is built, not at load time — a credential-less
+environment still boots. A missing credential raises `Tingee::Error` with code
+`"CONFIG"`.
+
+## Usage
+
+### Client basics
+
+```ruby
+client = Tingee::Client.new                     # uses Tingee.config, 90s read timeout
+slow   = Tingee::Client.new(read_timeout: 300)  # for background jobs (OTP confirm can take minutes)
+```
+
+All methods return the unwrapped `data` payload on success (`code "00"`), or raise
+`Tingee::Error` (see [Error handling](#error-handling)).
+
+### Supported banks
+
+```ruby
+client.get_banks
+# => bare array (NOT the usual envelope): [{"code"=>"VCB", "name"=>..., "bin"=>"970436", ...}, ...]
+```
+
+14 real banks are supported; notably **Techcombank (TCB) is NOT supported**. Full
+verified bank/BIN table in the [API reference](docs/tingee-api-reference.md#1-get-banks--supported-banks).
+
+### Bank linking — hosted SDK flow
+
+```ruby
+url = client.create_bank_link_session(redirect_url: "https://yourapp.com/settings/bank")
+# => "https://bank-link.tingee.vn?token=…" — redirect the user there
+```
+
+An empty payload works for the default merchant; pass `merchant_id:` only for a
+sub-merchant. Note: Tingee's hosted JS SDK had a live crash bug at verification
+time (`confirmId.startsWith`) — the manual chain below is the verified fallback.
+
+### Bank linking — manual API chain (verified end-to-end)
+
+One `create_va` serves every bank; the bank decides which shape you get back. OTP banks
+are below, redirect-authorize banks (VCB/TPB) in the next section.
+
+```ruby
+# 1. Start the link — the bank sends/pushes an OTP to `mobile`
+data = client.create_va(
+  bank_bin:       "970403",             # Napas BIN (STB/Sacombank here)
+  account_number: "0400…",
+  account_name:   "NGUYEN VAN A",
+  identity:       "0123456789…",        # CCCD — do not persist
+  mobile:         "09xxxxxxxx",         # MUST be domestic 0-prefixed; "84…" is rejected
+  webhook_url:    "https://yourapp.com/webhooks/tingee"
+)
+data # => {"confirmId"=>"…", "otpMethod"=>"SmartOTP"}
+
+# 2. Finish with the bank's OTP (can take minutes bank-side — use a background job)
+link = client.confirm_va(bank_bin: "970403", confirm_id: data["confirmId"], otp_number: "123456")
+link["accountNumber"]   # the REAL bank account — money lands here, show this on QRs
+link["vaAccountNumber"] # "TNG…" — Tingee-internal ROUTING KEY, store it to route webhooks
+
+# 3. ACB only: one extra OTP round
+r = client.register_notify(bank_bin: "970416", va_account_number: link["vaAccountNumber"])
+client.confirm_register_notify(bank_bin: "970416", confirm_id: r["confirmId"], otp_number: "654321")
+```
+
+### Bank linking — redirect-authorize banks (VCB, TPB)
+
+Same `create_va`, different bank behavior: pass `app_type: "baas"` + `redirect_url` and
+the bank answers with an **authorize link** instead of sending an OTP. There is **no
+`confirm_va` step** — the owner approves in the bank's app/web and the result arrives
+**asynchronously on your webhook** as `status: "confirm-va-success" | "confirm-va-failed"`
+(see [§Webhooks](docs/tingee-api-reference.md#7-webhooks)).
+
+```ruby
+# Pass and STORE your own request_id — it's echoed back on the webhook to correlate.
+# TPB returns NO confirmId at all, so your request_id is the ONLY correlation key.
+data = client.create_va(
+  bank_bin:       "970436",              # VCB
+  request_id:     my_link_id,
+  account_number: "0912323232",
+  mobile:         "0987665555",
+  app_type:       "baas",
+  redirect_url:   "https://yourapp.com/settings/bank",  # where the bank sends them back
+  webhook_url:    "https://yourapp.com/webhooks/tingee"
+)
+data.first["deepLink"] # "vcbpartner://linkPaymentEvent?token=…" — open in VCB Digibank
+                       # (TPB answers with "authorizeLink" — an https page)
+
+# Later, on your webhook (verify the signature first — see below):
+#   payload["status"] == "confirm-va-success" → payload["vaAccountNumber"] is now linked
+```
+
+Banks whose contract collects nothing from you (TPB — the owner picks the account on the
+bank's own web) simply omit `account_number`/`account_name`/`identity`/`mobile`; unset
+params are never sent.
+
+### Listing linked accounts
+
+```ruby
+client.get_va_paging # => {"totalCount"=>1, "items"=>[{"vaAccountNumber"=>"TNG…", "status"=>"active", …}]}
+```
+
+### Unlinking
+
+```ruby
+# Note Tingee's inconsistency: delete-va takes QUERY params, confirm-delete-va takes a
+# JSON BODY. Both identify the bank by its BIN ("970403"). The gem handles the transport.
+r = client.delete_va(bank_bin: "970403", va_account_number: "TNG…")
+client.confirm_delete_va(bank_bin: "970403", confirm_id: r["confirmId"], otp_number: "111111")
+```
+
+> **Do not pass the bank's short CODE (`bankName: "STB"`) to delete-va.** It looks like
+> it works — Tingee returns a `confirmId` and the bank really does send an OTP — but the
+> session it opens cannot be confirmed: `confirm-delete-va` then fails with
+> `"Lỗi hệ thống phương thức xác thực"` (live, 2026-07-17). Since unlinking is the only
+> way to stop per-webhook billing, an unlink that silently cannot complete keeps costing
+> money.
+
+Bank-shape variations on `delete_va`'s response are the caller's to branch on: OTP banks
+return `{confirmId}`, TPB returns an `authorizeLink`, and VCB returns `{}` because it
+detaches immediately — nothing left to confirm.
+
+### Transaction history
+
+```ruby
+# start_time/end_time are required ("yyyyMMddHHmmss", UTC+7); max 10-day window.
+client.get_transactions(start_time: "20260701000000", end_time: "20260710235959")
+# => {"totalCount"=>100, "items"=>[{"transactionId"=>…, "amount"=>100000, "type"=>"CREDIT", …}]}
+
+# Optional filters: filter (keyword), skip_count, max_result_count, merchant_id,
+# shop_ids, va_account_numbers, bank_bin.
+```
+
+Unlinking is also how you stop Tingee's per-webhook billing for an account.
+
+### VietQR payment codes
+
+Mint the payer-facing transfer QR locally — no `img.vietqr.io` round-trip, no API call:
+
+```ruby
+memo    = Tingee::VietQR.normalize_description("Thanh toán đơn HD#{invoice.id}")
+payload = Tingee::VietQR.payload(
+  bank_bin:       link.tingee_bank_bin,
+  account_number: link.bank_account_number,  # the REAL account from confirm_va
+  amount:         invoice.total,             # whole VND; omit or 0 for an open-amount QR
+  description:    memo
+)
+# => "00020101021138540010A00000072701240006…5802VN6225…6304<CRC>"
+```
+
+`amount` is parsed, never coerced: anything that is not a whole non-negative number of
+dong raises `Tingee::Error` with code `"QR_INPUT"`. That includes the formatted strings
+a form field or CSV will hand you — `"1.234.567"` is rejected rather than silently
+becoming a **1 ₫** QR. `Integer`, whole `Float`/`BigDecimal`/`Rational`, and a bare
+digit string all work.
+
+The gem returns the **EMVCo payload string, not an image** — QR pixel encoding is
+Reed-Solomon plus masking, which would mean a runtime dependency, and this gem has
+none. Render it app-side:
+
+```ruby
+require "rqrcode"   # add to YOUR Gemfile — deliberately not a dependency of this gem
+RQRCode::QRCode.new(payload).as_png(size: 512)
+```
+
+> **`description` is ASCII-folded and truncated to 25 chars** (`Thanh toán` → `Thanh toan`),
+> because many bank scanners mangle or reject a non-ASCII memo. **Persist the string
+> `normalize_description` returns and match your webhook's `description` against that** —
+> matching against your original un-normalized text silently misses every payment.
+>
+> A description that survives normalization as nothing (emoji or symbols only) raises
+> `"QR_INPUT"` rather than minting a QR with no reference the matcher could key on.
+
+A plain transfer into the linked real account fires the payment webhook regardless of
+which tool minted the QR, so nothing here needs Tingee's (broken) dynamic-QR endpoint.
+Ported from [openhoangnc/vietqr](https://github.com/openhoangnc/vietqr) (MIT); the test
+suite reproduces that project's fixtures byte-exact.
+
+## Webhook verification
+
+Tingee signs webhooks with `HMAC_SHA512(secret, timestamp + ":" + raw_body)` over
+the **raw body bytes exactly as sent** (verified against a real captured payment
+webhook). Pass the body verbatim — never re-parse/re-serialize it:
+
+```ruby
+Tingee::Signature.verify(
+  secret:    Tingee.config.secret_token,
+  timestamp: request_headers["x-request-timestamp"],
+  raw_body:  raw_request_body,   # Rails: request.raw_post — verbatim!
+  signature: request_headers["x-signature"]
+) # => true/false (constant-time comparison)
+```
+
+### Rails controller example
+
+```ruby
+class Webhooks::TingeeController < ActionController::Base
+  skip_forgery_protection
+
+  ACK = { code: "00", message: "Success" }.freeze
+
+  def create
+    raw = request.raw_post
+    payload = JSON.parse(raw) rescue nil
+    return render(json: ACK) if payload.nil?
+
+    # Dashboard connection test: unsigned {"event":"ping"} — ack it or the
+    # dashboard's test shows failure. Don't verify, don't process.
+    return render(json: ACK) if payload["event"] == "ping"
+
+    unless Tingee::Signature.verify(
+      secret: Tingee.config.secret_token,
+      timestamp: request.headers["x-request-timestamp"],
+      raw_body: raw,
+      signature: request.headers["x-signature"]
+    )
+      return head(:unauthorized)
+    end
+
+    # payload: {"transactionCode", "amount" (integer), "content" (memo),
+    #           "accountNumber", "vaAccountNumber", "bankBin", "transactionDate", …}
+    # Route on vaAccountNumber (unique per link), idempotency-key on transactionCode.
+    render json: ACK # always ack so Tingee stops retrying
+  end
+end
+```
+
+Payment-callback field semantics are documented in the
+[API reference §Webhooks](docs/tingee-api-reference.md#7-webhooks).
+
+## Error handling
+
+Every failure raises `Tingee::Error` with the raw Tingee code preserved:
+
+```ruby
+begin
+  client.confirm_va(bank_bin:, confirm_id:, otp_number:)
+rescue Tingee::Error => e
+  e.code    # "97" (bad signature), "90" (timestamp drift), "1001".."1076" (business),
+            # "HTTP_502" (non-JSON gateway page), "NETWORK" (transport), "CONFIG"
+  e.message # "Tingee error 97: Invalid signature"
+end
+```
+
+Transport failures (timeouts, DNS, TLS) are normalized to code `"NETWORK"` so
+callers handle one error type.
+
+## Signing rules (the things that will bite you)
+
+- Signature = `HMAC_SHA512(secret, timestamp + ":" + minified_json_body)`, hex digest.
+- Timestamp header format `yyyyMMddHHmmssSSS` in **UTC+7**; >10 min drift → error `90`.
+- A bodyless request (e.g. GET) still signs the string `"{}"` — signing `""` → error `97`.
+- Webhooks verify over **raw bytes**, outbound requests sign the minified body.
+
+All handled by the gem; listed here so you don't fight them when debugging.
+
+## Testing
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+### Poking the live API
+
+Rails apps: `bin/rails console` (with the initializer set) — `Tingee::Client.new.get_banks`.
+Without Rails:
+
+```bash
+TINGEE_CLIENT_ID=… TINGEE_SECRET_TOKEN=… bin/console
+> client = Tingee::Client.new
+> client.get_banks
+```
+
+One test reproduces a real captured signature and only runs when
+`TINGEE_SECRET_TOKEN` is set; it is skipped otherwise.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/docs/bank-auto-confirm-integration-guide.md

@@ -0,0 +1,307 @@
+# Bank auto-confirm integration guide
+
+A step-by-step playbook for wiring `tingee_ruby_sdk` into an app so customer bank
+transfers automatically confirm payments. Written to be handed to an AI coding
+agent or a developer with zero prior context — follow it top to bottom.
+
+Distilled from a production Rails integration (multi-tenant invoicing app,
+2026-07). Rails examples throughout, but every rule is framework-agnostic; the
+Rails-specific parts are marked. API-level facts live in
+[`tingee-api-reference.md`](tingee-api-reference.md) (official docs:
+[developers.tingee.vn/docs/banking](https://developers.tingee.vn/docs/banking/)) —
+this file is the app-side architecture.
+
+## What you're building
+
+1. **Link**: a business owner links their Vietnamese bank account to Tingee
+   (OTP-verified). You store a routing key.
+2. **Receive**: any plain bank transfer into that account (VietQR, manual
+   transfer — no Tingee QR needed) fires a signed webhook to your app.
+3. **Match**: your app routes the webhook to the right account/tenant, matches it
+   to an open invoice/order (memo + exact amount), and marks it paid.
+4. **Unlink**: reverses the link — also the ONLY way to stop Tingee's
+   per-webhook billing (every delivered webhook bills, matched or not).
+
+## 0. Prerequisites
+
+- Tingee merchant account with API credentials (`client_id`, `secret_token`).
+- In the Tingee dashboard: register your webhook URL
+  (`https://yourapp.com/webhooks/tingee`) with auth = **API Credentials** (HMAC),
+  NOT the static API-key option.
+- The gem: `gem "tingee_ruby_sdk", github: "lpwanw/tingee_ruby_sdk"`.
+- Know your supported-bank story: **Techcombank is NOT supported** (see the API
+  reference §1 for the full list). Hide/explain the link button for unsupported
+  banks.
+
+## 1. Configure credentials
+
+Inject at boot; never let the gem read a credential store. Missing credentials
+must not fail boot — `Tingee::Client.new` raises only when actually used.
+
+```ruby
+# config/initializers/tingee.rb (Rails)
+Rails.application.config.to_prepare do
+  creds = Rails.application.credentials.tingee
+  next unless creds
+
+  Tingee.configure do |c|
+    c.client_id    = creds[:client_id]
+    c.secret_token = creds[:secret_token]
+    c.base_url     = creds[:base_url] if creds[:base_url] # default is prod
+  end
+end
+```
+
+`to_prepare` (not a bare initializer body) so the config survives dev reloads.
+
+## 2. Data model
+
+Three pieces of state. Adapt names to your domain (`organizations` below = your
+tenant/account model).
+
+### 2a. On the linked account (organization)
+
+| Column | Source | Purpose |
+|---|---|---|
+| `tingee_va_account_number` (string, **unique index**, nullable) | `confirm_va` → `vaAccountNumber` (`TNG…`) | THE routing key — webhooks route on it. Not a real account. |
+| `bank_account_number` | `confirm_va` → `accountNumber` | The REAL account — what QRs show (feed it to `Tingee::VietQR.payload`), where money lands. |
+| `tingee_bank_bin`, `tingee_shop_id` | `confirm_va` response | Needed for unlink / support. |
+| `tingee_linked_at` (datetime) | you | Link state + audit. |
+| `bank_auto_confirm_enabled` (boolean, default **false**) | you | Feature gate — launches OFF, flipped per account. |
+
+Make the routing-key uniqueness a **partial unique DB index**
+(`WHERE tingee_va_account_number IS NOT NULL`) plus a model validation — the same
+bank account must never link to two of your tenants.
+
+`linked?` = `tingee_va_account_number.present?`.
+
+### 2b. In-flight link/unlink flow (one row per account)
+
+The link is a two-step OTP conversation and the slow step runs in a background
+job — so the pending state must live in the **DB, not the session** (a job can't
+touch a session). One table, unique per account:
+
+```
+tingee_link_requests:
+  organization_id (unique index)
+  step        confirm_va | confirm_register_notify | start_delete_va | confirm_delete_va
+  status      otp | verifying | failed
+  bank_code, bank_bin
+  confirm_id  (from Tingee; survives a wrong OTP — retrying is legitimate)
+  account_name (confirm-va doesn't echo it; carry the typed value)
+  error_message
+```
+
+**Never store** the customer's CCCD (`identity`), `mobile`, or the OTP — they are
+create-va call inputs only.
+
+### 2c. Webhook log (metering + idempotency, NOT a ledger)
+
+```
+tingee_webhooks:
+  organization_id   (nullable! unroutable webhooks still count — they still bill)
+  transaction_code  (UNIQUE DB index — this IS the idempotency mechanism)
+  amount            (integer)
+  memo_invoice_id   (extracted from memo, e.g. /HD(\d+)/i — never store the raw memo: payer PII)
+  matched_invoice_id (nullable)
+  received_at, processed_at
+```
+
+Idempotency via the DB unique index on `transaction_code` (race-safe), not a
+model validation — a replay raises the DB's duplicate error, which the webhook
+controller rescues and acks. `processed_at` distinguishes "processed, no match"
+from "job never ran" — your match-rate metric depends on that.
+
+## 3. The link flow
+
+Two paths exist. **Use the manual API chain** — Tingee's hosted JS SDK
+(`create_bank_link_session`) had a live crash bug at verification time; the raw
+chain is the verified-in-production path.
+
+### The state machine
+
+```
+create_va (sync, fast — bank sends OTP)          → step: confirm_va,   status: otp
+owner submits OTP                                → status: verifying, enqueue job
+job: confirm_va (SLOW — minutes at the bank)     → success: apply link, destroy request
+                                                 → ACB only: register_notify → step: confirm_register_notify, status: otp (second OTP)
+job failure, confirm_id present (wrong OTP/blip) → status: otp (retry legitimate)
+job failure, no confirm_id                       → status: failed (terminal, only cancel)
+```
+
+Rules learned in production:
+
+- **`confirm_va` MUST run in a background job with a raised read timeout**
+  (`Tingee::Client.new(read_timeout: 300)`): bank-side SmartOTP verification
+  routinely exceeds 90s and will 504 any synchronous request path.
+- `create_va` can stay synchronous — it only initiates the bank's OTP send (fast).
+- `mobile` must be domestic `0`-prefixed (`09…`), never `84…`.
+- **No automatic retry on the confirm job**: the OTP is consumed by the first
+  attempt; a retry can never succeed. Failures land on the record for the owner.
+- **ACB is special**: after `confirm_va` succeeds, call `register_notify` — a
+  second OTP round via `confirm_register_notify`. Call register_notify BEFORE
+  persisting the link locally: a link whose notify registration failed never
+  receives webhooks and silently breaks auto-confirm. On success, apply the link
+  and flip the request to the second OTP step in one transaction.
+- **Routing-key collision** (same bank account, second tenant): the unique index
+  rejects `apply_link!` even though Tingee-side confirm succeeded. Mark the
+  request `failed` with a clear message.
+- **Double-submit guard**: flip `otp → verifying` under a row lock; only the
+  transition enqueues the job. Enqueue AFTER the lock's transaction commits.
+- **Stale-replay guard**: while a request is `verifying`, a job owns it —
+  a back-button form replay must not destroy/recreate it. Redirect instead.
+- **Cancel** is allowed from ANY status (it's the escape hatch for a dead job);
+  the confirm job must tolerate the record vanishing (`find_by → return if nil`).
+- Persist from `confirm_va`'s response: real `accountNumber` → what your QR
+  shows; `vaAccountNumber` → routing key; plus `bankBin`, `shopId`.
+
+### UI pattern (Rails)
+
+Settings page renders from the `tingee_link_request` state (form → OTP input →
+verifying spinner → failed/cancel) and live-updates via Turbo broadcasts on the
+record's `after_update_commit` / `after_destroy_commit` — the owner can leave the
+page while the bank verifies. Any live-update mechanism (polling included) works;
+the point is: the page follows the DB record.
+
+## 4. The webhook endpoint
+
+Public, no auth/tenancy — the tenant is resolved FROM the payload. Order matters:
+
+```ruby
+class Webhooks::TingeeController < ActionController::Base
+  skip_forgery_protection
+  ACK = { code: "00", message: "Success" }.freeze
+
+  def create
+    raw = request.raw_post
+    payload = JSON.parse(raw) rescue nil
+    return render(json: ACK) if payload.nil?                 # unparseable — ack, ignore
+
+    return render(json: ACK) if payload["event"] == "ping"   # 1. unsigned dashboard test — ack or their UI shows failure
+
+    unless Tingee::Signature.verify(                          # 2. HMAC over RAW bytes — raw_post verbatim, never re-encode
+      secret: Tingee.config.secret_token,
+      timestamp: request.headers["x-request-timestamp"],
+      raw_body: raw,
+      signature: request.headers["x-signature"]
+    )
+      return head(:unauthorized)
+    end
+
+    record(payload)                                           # 3. log + route + enqueue
+    render json: ACK                                          # 4. ALWAYS ack success — Tingee stops retrying
+  rescue ActiveRecord::RecordNotUnique
+    render json: ACK                                          # replay — already recorded, safe no-op
+  end
+
+  private
+
+  def record(payload)
+    # nil-guard the routing key: a blank vaAccountNumber must route to NO tenant,
+    # not accidentally match every unlinked tenant's nil column.
+    va = payload["vaAccountNumber"].presence
+    org = va && Organization.find_by(tingee_va_account_number: va)
+    webhook = TingeeWebhook.create!(
+      organization: org,
+      transaction_code: payload["transactionCode"],
+      amount: payload["amount"].to_i,
+      memo_invoice_id: payload["content"].to_s[/HD(\d+)/i, 1]&.to_i,
+      received_at: Time.current
+    )
+    Tingee::PaymentJob.perform_later(webhook.id)
+  end
+end
+```
+
+Route: `post "/webhooks/tingee"`. Non-negotiables:
+
+- **Verify raw bytes** (`request.raw_post`) — re-parsing/re-serializing breaks
+  valid signatures.
+- **Ack the unsigned ping** before verification.
+- **Record + ack fast, match in a job.** You ack before matching, and Tingee
+  never resends an acked transaction — so the matching job MUST retry on
+  transient failure (`retry_on StandardError, attempts: 5`) or a hiccup silently
+  loses the payment. Matching is idempotent against a still-open invoice, so
+  retries are safe.
+- Log EVERY webhook, routable or not — each one bills.
+
+## 5. Payment matching
+
+App-side policy (deliberately not in the gem). The safe-by-construction rules:
+
+- **Memo convention**: your checkout/QR embeds a marker (`HD<invoice_id>`);
+  extract with a permissive regex — banks append their own reference text.
+  Mint the QR with `Tingee::VietQR.payload` (no `img.vietqr.io` call needed) and
+  **store what `Tingee::VietQR.normalize_description` returns, then match on that** —
+  it ASCII-folds and truncates the memo, so matching your original un-normalized
+  string misses every payment.
+- **All must hold**: feature flag enabled for the tenant, invoice still
+  open/draft, **exact amount match**, invoice belongs to the routed tenant
+  (run the matcher inside the tenant scope so cross-tenant attribution is
+  impossible by construction).
+- **Re-check open + exact amount UNDER a row lock, and pay in the same lock** —
+  a concurrent edit to the invoice between check and pay could settle it for a
+  total that no longer equals what was transferred.
+- **Any miss is safe**: fall through to your existing manual confirm path and
+  stamp `processed_at`. Narrow rules, safe misses — never guess.
+- Optional but valuable: a **self-test transfer** path — the settings page shows
+  a QR with a special memo; the matcher recognizes it, stamps
+  `tingee_test_verified_at`, and the page celebrates. Proves the whole pipe
+  end-to-end per account before real money relies on it.
+
+## 6. Unlink
+
+Mirror of linking, same state machine and job (`start_delete_va` →
+`confirm_delete_va` with OTP):
+
+- `delete_va` is slow too (it triggers the bank-side detach + OTP send) — run it
+  in the job, show the verifying spinner until the OTP form appears.
+- Both `delete_va` and `confirm_delete_va` key the bank by **BIN** (`"970403"`).
+  Passing the short code (`bankName: "STB"`) to `delete_va` returns a `confirmId`
+  and fires the bank's OTP, but opens a session `confirm_delete_va` cannot confirm —
+  it fails with `"Lỗi hệ thống phương thức xác thực"` (live, 2026-07-17). The error
+  surfaces one step after the mistake, which is what makes it costly to diagnose.
+- `delete_va`'s response shape varies by bank: `{confirmId}` (OTP banks, show the OTP
+  form), an `authorizeLink` (TPB — owner approves at the bank, a `delete-va-success`
+  webhook finishes it), or `{}` (VCB — already detached, finish locally now).
+- On confirmed unlink: clear all `tingee_*` fields AND the test-verified stamp
+  (a re-link needs fresh proof).
+- **Business rule**: disabling your feature flag does NOT stop Tingee's meter —
+  offer a "disable" that flags off AND unlinks in one action.
+
+## 7. Go-live checklist
+
+- [ ] Credentials in prod; boot succeeds without them in other envs.
+- [ ] Webhook URL registered in the Tingee dashboard (API Credentials/HMAC auth);
+      dashboard "test webhook" returns success (the unsigned ping path works).
+- [ ] `curl -X POST https://yourapp.com/webhooks/tingee -d '{}'` →
+      `{"code":"00","message":"Success"}`.
+- [ ] Feature flag default-false for every account; enable per pilot account.
+- [ ] Per pilot account, real end-to-end proof: link a supported bank → transfer
+      the exact total with the memo marker → invoice auto-pays with no manual
+      refresh; wrong amount does NOT auto-pay; manual confirm still works.
+- [ ] Monitoring: webhooks vs matched per account (match rate),
+      `organization_id IS NULL` rows (unroutable = linking problem, still
+      billed), `processed_at IS NULL` older than a few minutes (stranded job —
+      re-enqueue; manual confirm is the safety net).
+- [ ] Rollback story: flag off stops auto-pay instantly; unlink stops billing;
+      manual confirm untouched throughout — the feature degrades to the old
+      behavior, never worse.
+
+## 8. Gotchas index (hard-won, don't relearn)
+
+| # | Gotcha |
+|---|---|
+| 1 | `confirm_va`/`delete_va` take minutes at the bank — background job + `read_timeout: 300`, never a web request. |
+| 2 | OTP is consumed on first attempt — no auto-retry on confirm jobs. |
+| 3 | Webhook HMAC is over RAW bytes — `request.raw_post` verbatim. |
+| 4 | Dashboard ping is UNSIGNED — ack it before verifying. |
+| 5 | Ack-before-match means the match job MUST retry — Tingee never resends an acked txn. |
+| 6 | Idempotency = DB unique index on `transactionCode`, rescue the duplicate error with an ack. |
+| 7 | Blank `vaAccountNumber` must route nowhere — guard the nil-column lookup. |
+| 8 | `delete_va`: query-string params, keyed by **BIN**. The `bankName` variant returns a confirmId and sends an OTP but opens an unconfirmable session — confirm-delete-va then 400s. |
+| 9 | ACB needs `register_notify` (second OTP) — register BEFORE persisting the link. |
+| 10 | `mobile` domestic `0`-prefix; never persist identity/mobile/OTP; never store raw memos (PII). |
+| 11 | Exact-amount re-check under the invoice row lock. |
+| 12 | Unlink is the only way to stop per-webhook billing. |
+| 13 | Techcombank unsupported — handle in UI, not as an error surprise. |