ezPay E-Invoice Methodology 台灣電商：ezPay E-Invoice Methodology

• 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

• 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

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).

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.

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.

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

When completing an ezPay invoice task, produce this structure:

# ezPay Invoice Task: {one-line summary}

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

• Same-period: void_invoice → (optionally) re-issue_invoice with new merchant_order_no
• Cross-period or partial: issue_allowance → trigger_allowance (status="C")

• 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}

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

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

• 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