Skip to content

docs(research): Tingee as the M2 payment channel - #239

Merged
JOY (JOY) merged 7 commits into
devfrom
claude/tingee-research-3714fc
Nov 18, 2026
Merged

JOY (JOY) merged 7 commits into
devfrom
claude/tingee-research-3714fc

Conversation

@JOY

@JOY JOY (JOY) commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Research for the M2 switch from payOS to Tingee (JOY, 2026-11-18; PO comments on #24, #25 and #29). Docs only, no code.

  • docs/research/tingee.md: what Tingee offers, bank support, sign-up/KYC/fees, the API (auth, account linking, webhook payload, signature and retries, ids, reconciliation, sandbox), the money flow, and a proposed mapping onto PaymentChannel, the inbound pipeline and statement import. Every claim is tagged as confirmed (Tingee docs or terms), Tingee site, inferred, or unknown.
  • docs/Give-Technical-Design.md: records the switch as decision D8, adds a note in 5.2 that payos is replaced by tingee, and updates the M2 sentence in section 7.

Key findings

Test plan

  • prettier --check on both files
  • Fresh-context review (subagent, one round). It re-checked the key facts against Tingee's pages: the Techcombank absence, the per-bank table, the webhook payload and signature, the transaction-list limits, ACB-only debit notifications, Master Merchant, and the terms art. 5.2. Findings, all fixed in 0b5c087:
    • P1: the confirmation step now builds the transaction from the transaction-list row, so a signed webhook cannot change an amount.
    • P1: accounts are resolved by bank BIN plus number, and the BIN is in the dedupe key.
    • P1: a link is activated only after get-va-paging shows the organizer's account number and holder name. The bank-link webhook carries neither.
    • P2: a missing transactionCode is a final error.
    • P2: statement-import pairing by amount, day and content is marked as a design change that needs a decision.
    • P2: the citations for retries, the dedupe key and the signature examples are corrected.
    • P2: Master Merchant phone and login risks, plan lapses, and card rows are noted.
    • P3: QR table annotations, and the D-table diff is cut to the D8 row.

🤖 Generated with Claude Code


📌 TL;DR

This PR updates the technical design to replace the payos payment channel with Tingee for the M2 milestone, adding a new decision (D8) and a comprehensive research document detailing Tingee's API capabilities, bank support limitations (notably Techcombank), and the architectural mapping for webhook ingestion and reconciliation.

🎯 Type of Change

  • 🚀 New feature
  • 🐛 Bugfix
  • 🧹 Refactor
  • ⚡ Performance
  • 📚 Documentation
  • ⚙️ CI / Configuration

🔍 Changes Walkthrough

File Summary of Changes
docs/Give-Technical-Design.md Added decision D8 specifying Tingee as the M2 channel. Updated the channel table to mark payos as deprecated in favor of tingee. Adjusted milestone descriptions to reflect the switch.
docs/research/tingee.md New file containing deep-dive research on the Tingee API. Covers bank support matrix, webhook payload structures, signature verification, idempotency strategies, and a proposed design mapping for integrating Tingee into the existing PaymentChannel interface.

📊 Architectural Flow

sequenceDiagram
    participant Donor
    participant Bank
    participant Tingee
    participant GiveAPI
    participant Supabase

    Donor->>Bank: Transfer (VietQR/VA)
    Bank->>Tingee: Balance Change Notification
    Tingee->>GiveAPI: POST Webhook (Signed)
    
    Note over GiveAPI: 1. Verify HMAC-SHA512 Signature
    Note over GiveAPI: 2. Check URL Validation Challenge
    
    GiveAPI->>Supabase: Insert inbound_event (Dedupe by transactionCode)
    GiveAPI-->>Tingee: 200 OK (Immediate)
    
    Note over GiveAPI: 3. Async Processing
    GiveAPI->>Tingee: GET /transaction/get-paging (Confirm Tx)
    Tingee-->>GiveAPI: Transaction Details
    
    alt Transaction Confirmed
        GiveAPI->>Supabase: Record bank_transaction
        GiveAPI->>Supabase: Update Ledger (Received/Unmatched)
    else Unknown Account
        GiveAPI->>Supabase: Mark as Error (Staff Review)
    end
Loading

Decisions recorded and Money review round

  • JOY (2026-11-18): keep Tingee. It covers organizers at its 16 listed banks. Every other bank, Techcombank included, stays on statement import.
  • PO decisions (2026-11-18):
    • Cross-source pairing is only a link between two records. It never creates or drops a transaction and never changes an amount. Ambiguous pairs go to finance. Each record keeps its source-native identity.
    • A Tingee record's identity is the API row's transactionId. The bank code is kept as the bank reference, unique per (BIN, account number, code).
  • Money second review (PO): no blockers. All should-fix items and nits are fixed in bc1452c:
    • 1133: Vietcombank and VPBank business and household-business accounts must be linked with the Merchant's own API key.
    • In 8.4, pairing always runs, for in and out, unless id equality is proven for the bank.
    • 8.1 builds every transaction from the confirmed API row.
    • The account is resolved from the API row's bankBin, vaAccountNumber and merchantId.
    • Nits: the signature is checked on URL challenges; the retry docs are counted consistently; inferred tags; the qrAccount note; design §7 points to D8.
  • Re-verification by the fresh-context reviewer: two more rounds, fixed in b3e1cff and 74b31f0, with the final round clean:
    • Tingee records dedupe on (account, tingee, transactionId), even when a statement created the transaction.
    • Statement re-imports dedupe before pairing.
    • Statement import and Tingee recording share one account lock.
    • Lookups wait inside one 15 s attempt.

Desk research on Tingee (developers.tingee.vn v1.2.4, tingee.vn terms),
after JOY switched M2 from payOS to Tingee on 2026-11-18: products, banks,
sign-up and fees, API (auth, linking, webhook, ids, reconciliation,
sandbox), money flow, and a proposed mapping onto PaymentChannel, the
inbound pipeline and statement import (#24, #25, #29, #57).

Key finding: Tingee sends no webhooks for Techcombank accounts. Money
never passes through Tingee (terms art. 5.2).

The design doc records the switch as D8 and marks the payos row in 5.2
as replaced.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@JOY JOY (JOY) added the line:money Product line: money label Nov 18, 2026

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.

@vercel

vercel Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
give Ready Ready Preview Nov 18, 2026 1:59pm UTC

Request Review

@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: d9a82de7-9ad0-443d-8e82-95eb3eb2986f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@dos dos Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⏱️ Code Review completed (2 eligible files · 59,824 chars · 1 model call(s) · 2 PR unit(s))

Whole diff with bounded context at base 854bda3 / head 63344d8.

✅ CLEAN_PASS: Complete diff reviewed

- Confirm a webhook by building the transaction from the matching
  transaction-list row, so a signed webhook cannot change an amount.
- Resolve accounts by bank BIN plus number, and put the BIN in the
  dedupe key.
- Activate a link only after get-va-paging shows the organizer's
  account number and holder name; the bank-link webhook has neither.
- Treat a missing transactionCode as a final error.
- Mark statement-import pairing by amount, day and content as a design
  change that needs a decision.
- Correct the citations for retries, dedupe key and signature examples.
- Note the Master Merchant phone and login risks, plan lapses, and card
  rows.
- Keep the design-doc D-table diff to the new D8 row.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
dos[bot]
dos Bot approved these changes Nov 18, 2026

@dos dos Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⏱️ Code Review completed (2 eligible files · 58,972 chars · 1 model call(s) · 2 PR unit(s))

Whole diff with bounded context at base 854bda3 / head 0b5c087.

✅ CLEAN_PASS: Complete diff reviewed

- JOY kept Tingee for M2 (2026-11-18): it covers organizers at its 16
  listed banks; every other bank, Techcombank included, stays on
  statement import.
- PO rule for pairing Tingee and statement-import records: a pair is only
  a link between two records of the same transaction. It never creates,
  drops or changes an amount. Ambiguous pairs go to finance, never
  auto-linked. Each record keeps its source-native identity.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
dos[bot]
dos Bot approved these changes Nov 18, 2026

@dos dos Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⏱️ Code Review completed (2 eligible files · 59,455 chars · 1 model call(s) · 2 PR unit(s))

Whole diff with bounded context at base 854bda3 / head 23dfab6.

✅ CLEAN_PASS: Complete diff reviewed

JOY (JOY) and others added 4 commits November 18, 2026 20:54
- Identity of a Tingee record is the API row's transactionId (PO
  decision). The bank code is kept as the bank reference, unique per
  (BIN, account number, code), and is used for webhook lookup and
  statement cross-checks.
- 8.1 builds every transaction from the confirmed API row. 8.3 resolves
  the account from that row (bankBin, vaAccountNumber, merchantId) and
  verifies signatures on URL challenges too.
- 8.4: on a Tingee-linked account, cross-source pairing always runs, for
  in and out rows, unless id equality is proven for the bank.
- Error 1133: Vietcombank and VPBank business and household-business
  accounts must be linked with the sub-merchant's own API key (sections
  4, 8.2, 9, 10).
- 6.6 lists merchantId, shopId and bankBin. Inferred tags, the four
  retry descriptions, and the dynamic-QR qrAccount note.
- Design doc section 7: the M2 row points to Tingee (D8).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- Tingee records dedupe on bank_transaction_sources (account, tingee,
  transactionId), checked before pairing and recording, in one function
  that locks the account. This holds when a statement import created the
  transaction. webhook and api_poll share the source value; the path is
  a separate via column.
- Statement re-imports are deduplicated on their own source record id
  (parser id, or group_key plus occurrence) before pairing.
- Proven-id banks: same id and amount links, a conflicting record goes
  to finance, and no record means its own transaction.
- Inline processing runs after the reply and retries the lookup for
  about a minute. The 1-minute goal depends on the list lag (to measure).
- 1133 for Bank Link marked inferred. The client-id check accepts the
  expected id per link. get-va-paging cited directly.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- The webhook lookup waits inside one attempt (under the 15 s processor
  timeout) instead of spending attempts. A long list lag may need a
  longer Tingee timeout or a "not listed yet" result that does not count
  toward parking.
- The statement-import commit takes the same account lock as the Tingee
  record function, so simultaneous records of one transfer cannot both
  post.
- The check that the client id matches its link moves to the processor,
  after the link is resolved.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@dos

dos Bot commented Nov 18, 2026

Copy link
Copy Markdown

⏸️ DOS Review: Automatic Review Limit Reached

DOS Code Review already reviewed 3 commits of this pull request automatically, the limit for one pull request, so this commit was not reviewed automatically and nothing was charged. Please step back before pushing another fix: a pull request that needs this many review rounds usually needs a rethink of its approach or a smaller scope, not one more patch. When you are ready, a maintainer can comment /review to review the current commit.

@JOY

Copy link
Copy Markdown
Contributor Author

PO acceptance: merge at 55967fa. Docs only (research + 5-line design note). Money second review (PO-run): no blocker; its 4 should-fix items and nits fixed, plus the follow-up P1 (dedupe on bank_transaction_sources before pairing) found on re-verification; re-verified clean. Records JOY's decisions: Tingee for M2 (16 banks; others incl. Techcombank stay on statement import), Master Merchant contact by JOY. PO decisions: identity = transactionId, cross-source pairing is link-only. DOS Code Review shows its 3-round cap, not a finding.

@JOY
JOY (JOY) merged commit 275ae78 into dev Nov 18, 2026
5 of 6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

line:money Product line: money

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant