Repository navigation
docs(research): Tingee as the M2 payment channel - #239
Conversation
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]>
There was a problem hiding this comment.
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.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the
|
- 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]>
- 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]>
- 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]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
⏸️ DOS Review: Automatic Review Limit ReachedDOS 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. |
|
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. |
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 ontoPaymentChannel, 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 thatpayosis replaced bytingee, and updates the M2 sentence in section 7.Key findings
Test plan
prettier --checkon both filesget-va-pagingshows the organizer's account number and holder name. The bank-link webhook carries neither.transactionCodeis a final error.🤖 Generated with Claude Code
📌 TL;DR
This PR updates the technical design to replace the
payospayment channel withTingeefor 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
🔍 Changes Walkthrough
docs/Give-Technical-Design.mdpayosas deprecated in favor oftingee. Adjusted milestone descriptions to reflect the switch.docs/research/tingee.mdPaymentChannelinterface.📊 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) endDecisions recorded and Money review round
transactionId. The bankcodeis kept as the bank reference, unique per (BIN, account number, code).inandout, unless id equality is proven for the bank.bankBin,vaAccountNumberandmerchantId.qrAccountnote; design §7 points to D8.tingee,transactionId), even when a statement created the transaction.