tw-ecom-invoice-ezpay

name	tw-ecom-invoice-ezpay
description	Issue and manage Taiwan e-invoices via ezPay (加值服務中心) through mcp-ezpay-einvoice. Use when issuing B2B/B2C invoices, handling carrier codes (手機條碼, 自然人憑證), voiding within the same bimonthly window, or issuing allowances (折讓) across periods. Do NOT use for direct 財政部 API integration (see tw-einvoice-guide) or for UniversalEC-backed flows (see tw-ecom-invoice-universalec).
metadata	{"category":"WP-05 台灣創業","domain":"ecommerce-tw","layer":"invoice","related_mcps":["mcp-ezpay-einvoice"],"related_skills":["tw-einvoice-guide","tw-ecom-invoice-carrier","tw-ecom-invoice-void","tw-tax-basics"],"last_verified":"2026-04","tags":["taiwan","e-invoice","ezpay","tax-compliance"]}

ezPay E-Invoice Methodology

When to use this skill

• Issuing B2B or B2C 統一發票 from a Taiwan storefront, POS, or SaaS backend through ezPay (藍新系) as the 加值服務中心
• Attaching a consumer carrier — 手機條碼 (/XXXXXXX), 自然人憑證, or 會員載具 — so the invoice is not printed on paper
• Voiding a wrongly-issued invoice within the same bimonthly period, or issuing an allowance (折讓) when the void window has closed
• Issuing or triggering a scheduled invoice (status="3") that must go live on a later date (e.g., subscription renewal)
• Reconciling ezPay-issued invoices against the 財政部電子發票整合服務平台 daily to catch upload lag or dropped records
• Debugging opaque ezPay responses: LIB10002 encryption failures, INV20002 void-window errors, ALW10001 allowance-over-invoice errors

Do NOT use when

• The merchant connects to the 財政部 platform directly (no 加值中心) — use tw-einvoice-guide for the MOF-direct pattern and concepts
• The storefront is on UniversalEC (統一發票整合服務) or another 加值中心 (ECPay 綠界, 銓葳) — they have different tool shapes; this skill's gotchas are ezPay-specific
• You only need the API schema for one ezPay endpoint — read the tool description in mcp-ezpay-einvoice or the ezPay developer portal at https://inv.ezpay.com.tw/
• The question is "what is a 手機條碼" or "B2B vs B2C invoice format" — that is foundational material already covered by tw-einvoice-guide. This skill assumes you know the landscape

Core concepts

ezPay is a 加值服務中心 — a middleman that batches merchant invoice requests, uploads them to the 財政部電子發票整合服務平台 on the merchant's behalf, and relays carrier / 捐贈碼 lookups back. The merchant's legal counterparty for tax purposes is still 財政部; ezPay is an operational convenience, not the source of truth.

mcp-ezpay-einvoice wraps 7 tools over the ezPay API:

• Invoice lifecycle: issue_invoice, trigger_invoice, void_invoice, query_invoice
• Allowance (折讓) lifecycle: issue_allowance, trigger_allowance, void_allowance

Category. category="B2B" requires buyer_ubn (統編) — omit it and the invoice silently becomes B2C (lottery-eligible, wrong tax reporting). category="B2C" attaches a carrier or prints paper.

Carriers. carrier_type="0" + carrier_num="/ABC1234" for 手機條碼 (slash + 7 chars). carrier_type="1" for 自然人憑證 (2 letters + 14 digits). carrier_type="2" for ezPay 會員載具. love_code (3-7 digits) for 捐贈碼 — mutually exclusive with carriers.

字軌. 財政部 assigns invoice-number ranges (字軌) per bimonthly period (e.g., TE00000000-TE99999999). ezPay draws from this pool on issuance. Exhausting the range blocks issuance — the MOF assigns the next period's range in advance, but only if you requested it.

Void vs allowance. void_invoice only works inside the same bimonthly period the invoice was issued (see Gotchas). After the period closes, corrections must go through issue_allowance → trigger_allowance (status C=confirm, D=cancel).

Decision tree

What is the user asking for?
│
├─ Issue a NEW invoice?
│    ├─ Buyer has 統編?  → issue_invoice(category="B2B", buyer_ubn=...)
│    └─ Consumer?         → issue_invoice(category="B2C", carrier_type/carrier_num
│                                         OR love_code OR print_flag="Y")
│
├─ Scheduled invoice (issue on a future date)?
│    → issue_invoice(status="3", create_status_time="YYYY-MM-DD")
│      Later: trigger_invoice(invoice_trans_no, merchant_order_no, total_amt)
│
├─ Correct a WRONG invoice?
│    ├─ Issued in the CURRENT bimonthly period?
│    │    → void_invoice(invoice_number, invalid_reason)
│    │      (Then re-issue fresh if needed)
│    └─ Issued in a PAST bimonthly period?
│         → issue_allowance(invoice_no, items, total_amt)
│             → trigger_allowance(allowance_no, allowance_status="C")
│           (Voiding the allowance later: void_allowance)
│
├─ Partial refund (return 1 of 3 items)?
│    → issue_allowance against the original invoice for the returned portion only
│
└─ "Did this invoice issue?" / "What's the status of order X?"
     → query_invoice(search_type="0" by invoice number, "1" by merchant_order_no)
       Treat ezPay's answer as a local cache — MOF platform is the authority

Void-window boundary: per the README, the cutoff is roughly "before the 14th of the next odd month" (e.g., Mar-Apr invoices must be voided before May 14). Confirm the exact cutoff against the current MOF calendar — it shifts with national holidays.

Implementation guidance

Three flows. For each, the exact mcp-ezpay-einvoice tool is named. See references/issuance-flow.md for setup wiring and examples/sample_scenario.md for an end-to-end Shopline → ezPay → allowance walkthrough.

Issue invoice (one-shot, post-payment)

1. Trigger from the payment-success callback (NotifyURL on NewebPay / ECPay / TapPay). Never issue from the browser ReturnURL — see tw-ecom-payment-newebpay IRON LAW.
2. Before calling issue_invoice, validate the carrier client-side: / + 7 alphanumeric for 手機條碼; 2 letters + 14 digits for 自然人憑證. An invalid carrier string returns a generic ezPay error and the invoice is never created.
3. Call issue_invoice with category, tax_type="1" (應稅), amt (pre-tax), tax_amt, total_amt (amt + tax_amt), pipe-delimited item arrays, and print_flag="N" when a carrier is supplied.
4. Persist the returned InvoiceNumber, InvoiceTransNo, and RandomNumber keyed on your internal merchant_order_no. The random number is required for 中獎 cross-reference later.

Void invoice (same-period correction)

1. Call query_invoice first to confirm the invoice is still voidable — a previously-voided invoice returns INV20001; an out-of-window invoice returns INV20002.
2. Call void_invoice(invoice_number, invalid_reason). The reason string is a free-text audit field — keep it specific (e.g., "buyer cancelled before shipment", not "誤開").
3. If you need to re-issue, call issue_invoice with a new merchant_order_no — the old one is now permanently associated with the voided invoice, and re-using it returns INV10001 (duplicate merchant order number).

Allowance / 折讓 (cross-period correction or partial refund)

1. Call issue_allowance(invoice_no, items[], total_amt) with only the returned/refunded items. Allowance total_amt includes both goods and tax components (per the README example: 65 item + 3 tax = 68 total).
2. Allowance starts in a pending state. Call trigger_allowance(allowance_no, allowance_status="C") to confirm (or "D" to cancel before it is filed with MOF).
3. If the allowance itself was filed incorrectly, void_allowance(allowance_no, invalid_reason) reverses it — but only within the allowance's own voidability window (analogous to invoice void, but tracked separately).
4. Allowance amount must not exceed the original invoice amount — ALW10001 fires if so. For a full refund that exceeds a single invoice, you need one allowance per invoice, not a combined one.

Gotchas

• 字軌 exhaustion silently blocks issuance. MOF assigns number ranges per bimonthly period; ezPay draws from them. If you don't request the next period's range in advance (via the ezPay merchant portal or MOF platform), the first issuance attempt after the rollover fails with an opaque error. Monitor remaining-number count weekly and request the next range at least 1 bimonthly period ahead. (TODO: verify the exact portal path and any ezPay auto-refill option against the current ezPay merchant portal.)
• Void window is same-bimonthly only; cross-period corrections need 折讓. Per the README, an invoice issued in March-April can be voided before roughly May 14. A March invoice discovered wrong in June cannot be voided — void_invoice returns INV20002 (void period has passed). The only correction path is issue_allowance + trigger_allowance. Agents who retry void_invoice indefinitely never resolve the error.
• 手機條碼 format is strict: / + exactly 7 alphanumeric characters. ABC1234 (no slash), /ABC12345 (8 chars), lowercase, or a scanned barcode with leading whitespace all fail. Validate client-side before issue_invoice — ezPay's error for invalid carriers is generic, and the invoice is not created, so you cannot recover by patching. Many POS scanners also need to be configured to emit the / prefix; test with real 手機條碼 barcodes, not typed input.
• Missing buyer_ubn on a B2B sale silently becomes B2C. category="B2B" without buyer_ubn will be rejected, but category="B2C" with a business buyer that SHOULD have had a 統編 issues a B2C invoice — which is lottery-eligible and taxed differently. When the buyer exists in your CRM as a company, enforce category="B2B" + buyer_ubn in your backend, not the UI. UI-only enforcement is bypassed by webhooks replaying a stale payload.
• ezPay state can lag the MOF platform — reconcile against MOF, not ezPay. query_invoice returns ezPay's internal record. The 財政部電子發票整合服務平台 is where tax liability is established, and ezPay uploads in batches. A successful query_invoice does not prove the invoice is on the MOF platform. Run a daily reconciliation job that fetches the MOF upload status (per invoice or per batch) and reconciles against your DB. Trust neither ezPay's local state nor your own DB as the source of truth for tax filing. (TODO: verify exact ezPay-to-MOF upload latency from the ezPay merchant portal reporting dashboard.)

IRON LAW

MOF is the source of truth; ezPay state can lag. Never close the books, never file 401 (營業稅), and never tell the customer "invoice issued" based solely on an ezPay SUCCESS response or a query_invoice hit. ezPay is a batching 加值中心 — its local record can be ahead of, behind, or silently out-of-sync with the 財政部電子發票整合服務平台. Run daily reconciliation against the MOF platform's upload status for every invoice issued in the prior 48 hours. Any ezPay record without a confirmed MOF upload is pending, not issued. Two failure modes this prevents: (1) 營業稅 filing with phantom invoices that MOF never received (audit finding, fine); (2) customer-facing claims of "invoice issued" when the carrier/lottery record does not exist on MOF (consumer complaint, brand damage). When in doubt, MOF wins.

Rationalization Table

"但是…"	為什麼錯
issue_invoice 回傳 SUCCESS，發票一定開出去了	SUCCESS 只代表 ezPay 本地接受請求；上傳財政部是非同步批次，可能延遲數小時或靜默失敗
query_invoice 查得到這張發票，代表 MOF 也有	query_invoice 查的是 ezPay 本地快取，不是財政部電子發票整合服務平台
客戶手機條碼已經收到通知，所以發票在 MOF 上了	載具通知由 ezPay 發送，與 MOF 上傳是不同的非同步流程，兩者可不同步
每張都對帳太耗效能，ezPay 不太會出錯	出錯頻率低不等於零；稅務申報錯誤的代價（罰款、重審）遠高於每日對帳的成本

Output Format

When completing an ezPay invoice task, produce this structure:

# ezPay Invoice Task: {one-line summary}

## Context
- Environment: {test (cinv.ezpay.com.tw) | production (inv.ezpay.com.tw)}
- Category: {B2B | B2C | mixed}
- Carrier strategy: {手機條碼 | 自然人憑證 | 會員載具 | 捐贈碼 | 紙本}
- Trigger source: {payment NotifyURL | scheduled | manual | reconciliation}

## Tool Plan
| Step | Tool | Purpose |
|------|------|---------|
| 1 | query_invoice | Pre-check for duplicate merchant_order_no |
| 2 | issue_invoice | B2B/B2C issuance with validated carrier |
| 3 | (MOF reconciliation) | Confirm upload status against MOF platform |
| … | … | … |

## Correction Path (if applicable)
- Same-period: void_invoice → (optionally) re-issue_invoice with new merchant_order_no
- Cross-period or partial: issue_allowance → trigger_allowance (status="C")

## Assumptions & Open Questions
- Tax semantics: {tax_type="1" 應稅 with tax_rate=5, amt/tax_amt/total_amt consistent}
- Carrier validated client-side before API call: Y/N
- 統編 validated against company registry (if B2B): Y/N
- TODO: {anything that needs verification against ezPay merchant portal or MOF platform}

## Reconciliation
- ezPay → MOF upload check window: {24h / 48h / …}
- Mismatch handling: {retry / manual portal fix / support ticket}
- Daily reconciliation job: Y/N, cron at {…}

## Deliverable
{the actual issuance record, correction summary, or reconciliation report}

Related

• MCPs: mcp-ezpay-einvoice
• Skills: tw-einvoice-guide (MOF platform landscape, B2B/B2C/carrier basics), tw-ecom-invoice-carrier (carrier-specific patterns — skeleton), tw-ecom-invoice-void (void vs allowance decision — skeleton), tw-tax-basics (營業稅 401 filing reconciliation), tw-ecom-payment-newebpay (upstream trigger via payment NotifyURL), tw-ecom-dtc-shopline (order-to-invoice handoff)
• References: references/issuance-flow.md (registration → 字軌 → sandbox → prod → daily reconciliation), examples/sample_scenario.md (Shopline 手機條碼 order → ezPay invoice → cross-period refund → 折讓)

Last verified: 2026-04