TapPay Payment Integration Skill

繁體中文 | English

TapPay's official Agent Skill that helps merchants integrate the TapPay payment gateway into any website. Describe what you need in plain language; your AI coding agent walks you through the integration for your framework, language and payment methods — and explains how the merchant side decides a transaction's status and manages orders.

Works with Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot, Cursor and other agents that support Agent Skills (see "Installation" below).

Item	Value
Skill version	v1.3.0
Last updated	2026-10-07 (aligned with the TapPay developer documentation)
TPDirect SDK version	v5.25.0 (defined once in references/00-setup.md §9)
Backend examples	Node.js (complete), PHP / Python (condensed)

TPDirect is plain JavaScript and works with any frontend framework. The content follows the TapPay developer documentation and was checked against actual TapPay sandbox behaviour. If anything here differs from the developer documentation, the developer documentation prevails.

---

What it is

This is not an SDK or library. It is an integration guide that reasons: once installed, the agent first asks a few questions (which payment methods, your frontend/backend stack, whether you have a database and order system, automatic or manual capture…), then loads only the relevant sections and gives you ready-to-use code, field tables for every API, payload rules, and the most common pitfalls with their fixes.

Good for:

• Merchants / engineers integrating TapPay for the first time
• Teams stuck on an error (e.g. 10014, canMakePaymentWithActiveCard is false) who want a fast fix
• Anyone who needs to know "has this order actually been paid?" — timeouts, duplicate notifications, "payment succeeded but the page says failed", sweeping stuck orders, reconciliation
• Evaluating which payment methods TapPay supports and how their flows differ

---

Supported payment methods

Category	Methods
Credit card	3DS / N3D, instalment (Direct Pay only), saved card (pay-by-token)
Mobile wallets (Token Pay)	Apple Pay, Google Pay, Samsung Pay
E-payment wallets	LINE Pay, JKO Pay (街口支付), Easy Wallet (悠遊付), Pi Wallet (Pi 錢包), Plus Pay (全盈+PAY), PXPay Plus (全支付), iPASS MONEY (一卡通 MONEY)
Buy now, pay later (BNPL)	AFTEE, OPPay (大哥付你分期), GoGo Pay (分期趣)
Asynchronous collection	ATM virtual-account transfer (per TapPay product document V1.2.4)
Logistics + collection	Convenience-store C2C logistics: pickup-and-pay (COD) and pickup-only shipments (7-Eleven / FamilyMart / Hi-Life; per TapPay product document V1.0.1; OK mart was removed in SDK v5.26.0)

Post-transaction refund / capture / reconciliation / trade history and card binding (Pay by Card Token) are covered too.

Out of scope

• Complete flows for non-TWD currencies (field tables only note the ×100 amount rule), Link Pay, wallets from other regions.
• Acquiring-bank contract terms, fees and settlement schedules.

Good to know

• ATM virtual account and convenience-store logistics follow TapPay's product specs (ATM V1.2.4, C2C logistics V1.0.1). A few items depend on your merchant setup — the sandbox logistics host and how to simulate shipment status, per-chain store rules, and cancelling / refunding an ATM or COD transaction. Each chapter marks them with "confirm with TapPay" and a safe default (15 §16 has a checklist); please check them with your TapPay technical contact before launch.
• Sweeper intervals, retry limits and other timing values in the order-state chapter are recommended defaults; tune them for your business.

---

Installation

This skill follows the open Agent Skills format (a folder with a SKILL.md), so it works with any agent that supports skills. Download tappay-payment-integration.skill — a plain zip containing the tappay-payment-integration/ folder — and unzip it into your agent's skills directory.

Agent	Personal (all projects)	One project only
Claude Code	~/.claude/skills/	.claude/skills/
OpenAI Codex CLI	~/.codex/skills/ or ~/.agents/skills/	.agents/skills/
Gemini CLI	~/.gemini/skills/ or ~/.agents/skills/	.gemini/skills/ or .agents/skills/
GitHub Copilot (VS Code / Copilot CLI)	~/.copilot/skills/	.github/skills/
Cursor	~/.cursor/skills/ or ~/.agents/skills/	.cursor/skills/ or .agents/skills/

Tip: .agents/skills/ is a shared location read by Codex, Gemini CLI, GitHub Copilot and Cursor — one copy there serves all of them.

# Example: personal install for Claude Code
unzip tappay-payment-integration.skill -d ~/.claude/skills/

# Example: project install shared by Codex / Gemini CLI / Copilot / Cursor
unzip tappay-payment-integration.skill -d <your-project>/.agents/skills/

You should end up with <skills directory>/tappay-payment-integration/SKILL.md. Restart the agent (or start a new session) so it picks up the new skill.

Other ways to install

• Gemini CLI: gemini skills install ./tappay-payment-integration.skill (add --scope workspace for the current project only).
• Claude desktop app / claude.ai: open Settings, find the Skills section and upload the .skill file.
• Any supported agent via the skills CLI: npx skills add https://github.com/TapPay/tappay-payment-integration-skill (use -a <agent> to pick the agent, -g for a personal install).

Once installed, no command is needed: the agent uses the skill automatically whenever you talk about TapPay.

---

Usage

Just describe your situation, for example:

I'm adding TapPay credit card 3DS to an Express.js + vanilla JS site. Where do I start and what must I not get wrong?

Add LINE Pay to my checkout page; the order must update after payment.

The order was paid but the page shows "failed", and backend_notify arrived too. How do I decide the transaction status?

pay-by-prime timed out. Can I just retry? What status should the order have?

pay-by-prime keeps returning 10014. Here's how I generate bank_transaction_id: ... What's wrong?

The agent first confirms a few things (payment methods, frontend framework, backend language, database and order system, automatic/manual capture, current progress), then loads only the matching chapters.

The skill answers in the language you write in (English or Traditional Chinese).

---

Skill contents

File	Topic
SKILL.md	Entry point: interview flow, module index, core design rules
references/00-setup.md	Portal setup, the two kinds of Merchant ID, env vars, ngrok, HTTP helper (three failure kinds), Record lookup helper, classifyRecord, security rules, status / error codes, SDK version
references/01-credit-card.md	Card SDK, card fields, getPrime, full pay-by-prime request / response field tables, timeout handling
references/02-3ds-flow.md	3DS redirect flow, frontend redirect parameters, backend_notify payload fields, result page, Record API fields
references/03-apple-pay.md	Apple Pay: setup order, N3D flow
references/04-google-pay.md	Google Pay: SDK setup, getPrime
references/05-saved-card.md	Saved card / pay-by-token (field table), when to store, ownership checks
references/06-instalment.md	Credit-card instalment rules and compatibility
references/07-pitfalls.md	Real pitfalls P1–P32 + pre-launch checklist + testing SOP
references/08-framework-notes.md	React / Next.js / Vue / PHP / Python notes, general environment issues
references/09-e-payment.md	Shared e-payment / BNPL flow, per-wallet comparison, pay_info, binding support matrix
references/10-samsung-pay.md	Samsung Pay: verification-window flow
references/11-pay-by-card-token.md	Single entry point for card binding, Bind Card / Remove Card field tables
references/12-refund-capture.md	Refund / capture (Cap field table, delay_capture_in_days) / reconciliation / trade history
references/13-order-state-management.md	Merchant order and payment state: data model, state machine, decision table, notify handling, timeouts, sweeper, result-page polling, post-refund/capture states, daily reconciliation
references/14-atm.md	ATM virtual account: get account, payee_info, payment deadline, notify, status, reconciliation, order-state mapping
references/15-cvs-logistics.md	Convenience-store C2C logistics: COD, pickup-only, store map, logistics notify and codes, separate payment / shipment state lines
references/16-method-matrix.md	Cross-method matrix (review entry point): API support, notify rules, success / waiting states, capture & refund timing, reconciliation visibility, shopper-facing copy, and how differences between documentation pages are handled
references/17-scenario-checklist.md	50 must-pass scenarios: expected order state, shopper screen and reconciliation result for each
references/18-code-review-checklist.md	Reviewing existing code: severity levels, finding format, launch gate
scripts/	Runnable Node.js reference implementation: tappay-client.js (HTTP helper, Record lookup, classifyRecord), order-state/ (schema, attempts, notify handler, state machine, sweeper, result page)
evals/evals.json	Test prompts used to check the skill's answers

---

Prerequisites

• A TapPay account and sandbox credentials (app_id, app_key, partner_key, merchant_id) from TapPay Portal → Developer.
• A public HTTPS URL to test 3DS / e-payment redirects and backend_notify locally (ngrok works); backend_notify_url must be https on port 443.
• Your backend server's public IP registered under API Source IPs in the Portal.

What each method needs enabled first

Method	Prerequisite
Credit card	Acquiring-bank contract and the matching TapPay Merchant ID; instalment needs bank support for the terms
Apple Pay	Apple merchant identifier (your own or TapPay MASS), Payment Processing certificate, domain-verification file, an acquiring account that supports Token Pay (DPAN)
Google Pay	A Google Pay & Wallet Console Merchant ID for production; also a Token Pay–capable acquiring account
Samsung Pay	A Token Pay merchant; testing needs a Samsung phone
E-payment wallets	A separate Merchant ID per wallet (the credit-card one will not work)
Binding (LINE Pay / Easy Wallet / PXPay Plus / iPASS MONEY)	Some need a separately enabled binding Merchant ID
BNPL (AFTEE / OPPay / GoGo Pay)	Request a test account and credit line from TapPay; complete onboarding with the BNPL provider

---

Security notes

• partner_key stays on the backend — never in frontend code, API responses or logs.
• The backend decides the amount: the frontend sends only orderId (plus a prime or saved-card id); amount / currency / details are always computed by the backend from the order, otherwise users can tamper with the amount.
• backend_notify and redirect parameters can both be forged: backend_notify has no signature by default (TapPay can enable an X-Api-Checksum header for your merchant on request), and the developer documentation notes that frontend redirect data can be forged. Treat both only as triggers; always query the Record API from the backend (classify record_status with classifyRecord) and compare amount / currency / order number.
• If backend_notify does not get HTTP 200, TapPay re-sends after 1, 2, 4, 8 and 16 minutes — at most 5 times — and then stops. So: store the notification first, then answer 200 (answer non-200 if storing fails so it is re-sent), and run a sweeper for stuck orders.
• Timeout ≠ failure: a pay-by-prime timeout means the result is unknown. A prime is single-use (valid 90 seconds) and must not be re-sent; look the transaction up with the Record API first.
• Every read of a transaction or saved card checks the logged-in identity and ownership.
• All keys and merchant codes in this repo are placeholders (e.g. YOUR_PARTNER_KEY); no real credentials are included.

---

Design principles

• Framework-neutral: frontend examples are vanilla JS (TPDirect itself is plain JS); backend is mainly Node.js with condensed PHP / Python equivalents.
• No real keys: every credential is a placeholder.
• Merchant-facing: every pitfall is written as symptom → root cause → fix.
• Documentation first: specs follow the TapPay developer documentation; recommended engineering practices (e.g. sweeper intervals) are labelled as recommendations, not TapPay specs.

---

Changelog

• v1.3.0 (2026-10)
  • Runnable Node.js reference implementation moved to scripts/ (TapPay client helpers, order-state engine, SQL schema); 00 and 13 keep the rules and decision tables.
  • Pitfalls index (07) condensed to symptom → cause → fix with pointers; API field tables keep the error-prone fields and link the official reference.
• v1.2.1 (2026-10)
  • Saved-card binding rule made consistent across chapters: always stage the card_secret, promote it once the Record API confirms the payment (N3D included).
• v1.2.0 (2026-10)
  • First public release under the TapPay name.
  • Open questions in the ATM and logistics chapters are now customer-facing "confirm with TapPay" notes with a safe default.
  • SKILL.md lists the current SDK version up front.
  • Installation for any agent that supports Agent Skills (Codex, Gemini CLI, GitHub Copilot, Cursor…); MIT license.
• v1.1.0 (2026-10)
  • Added ATM virtual account (14) and convenience-store C2C logistics (15).
  • Added merchant order and payment state management (13): data model, state machine, decision table, sweeper, reconciliation.
  • Added the cross-method matrix (16), 50 must-pass scenarios (17) and a code-review checklist (18).
  • Field tables for pay-by-prime / pay-by-token / backend_notify / redirect / Record / Cap / Bind Card / Remove Card.
  • Unified record_status handling (classifyRecord), timeout → unknown-result handling, backend-decided amounts and ownership checks.
  • SDK version unified at v5.25.0.
• v1.0.0: first release.

---

License

MIT

---

Feedback

Please report issues or suggestions by opening an Issue in this repository.

The complete official reference is the TapPay developer documentation.

Disclaimer: this skill is an integration guide and is not legal, financial or compliance advice. Specs, limits and error codes may change with TapPay or acquiring banks; where this skill differs from the developer documentation, the documentation prevails. Test fully in the sandbox before launch and confirm contract scope with TapPay and your acquiring bank.