Tw Ecom Invoice Ezpay

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.