Tw Ecom Payment Newebpay

NewebPay Integration Methodology

When to use this skill

• Accepting payment on a Taiwan storefront through NewebPay (藍新金流): credit card, ATM (虛擬帳號), CVS barcode (超商條碼), LINE Pay, Apple Pay, Taiwan Pay, Samsung Pay
• Setting up 定期定額 (credit card recurring billing) — subscription boxes, SaaS, content sites, donation platforms
• Reconciling NewebPay callback webhooks against internal order state, or debugging why an order is "paid on NewebPay" but "open in our DB"
• Issuing refunds, cancelling authorizations, or closing (請款) credit card transactions through mcp-newebpay
• Debugging AES-256-CBC / TradeSha signature mismatches, 3DS 2.0 liability shift behavior, or MPGGateway form submission failures

Do NOT use when

• The question is "which gateway should we pick?" — use tw-payment-integration (comparison of NewebPay / ECPay / TapPay / LINE Pay Direct)
• The merchant is on ECPay (綠界) or TapPay — those providers have their own skills and different API / signature schemes
• You only need the exact API schema for one NDNF/NDNP endpoint — read mcp-newebpay tool descriptions or the NewebPay official PDF (線上交易─幕前支付技術串接手冊_NDNF / 信用卡定期定額串接技術手冊_NDNP)
• The dispute is about chargeback / 爭議款 handling — see tw-ecom-payment-dispute

Core concepts

NewebPay (藍新金流) is one of the three dominant TW payment gateways (with ECPay and TapPay). It is an aggregator — one merchant contract covers credit card, ATM, CVS, and wallet rails, each with its own settlement cycle. mcp-newebpay wraps 8 official tools covering two API families:

• NDNF (線上交易) — one-off transactions. Tools: create_mpg_payment, query_trade, cancel_authorization, close_refund, ewallet_refund.
• NDNP (定期定額) — credit-card recurring mandates. Tools: create_period_payment, alter_period_status, alter_period_content.

NDNF and NDNP are separate merchant accounts with separate MerchantID + HashKey + HashIV triples. Configuring one does not enable the other.

Signature model. Every request body is AES-256-CBC-encrypted with the merchant's HashKey (32 chars) and HashIV (16 chars) into a TradeInfo blob, and a SHA-256 TradeSha is computed over HashKey=…&{TradeInfo}&HashIV=… and the result uppercased (the literal format, not a generic param sort — see Gotchas). Version is 2.0. 3DS 2.0 liability shift is handled by NewebPay's hosted MPG page; merchants never see card PAN.

Trust boundary. create_mpg_payment / create_period_payment return encrypted form data for a browser-side POST to https://ccore.newebpay.com/MPG/mpg_gateway (or core.newebpay.com in prod). The merchant backend never sees card PAN. Payment result is delivered via two channels: NotifyURL (server-to-server webhook) and ReturnURL (browser redirect). These can arrive out of order.

Decision tree

What is the user asking for?
│
├─ New one-time payment (credit card / ATM / CVS / wallet)?
│    → NDNF: create_mpg_payment
│      Returns {url, form_data} → merchant must render an auto-submit form
│      Result arrives via NotifyURL (trust) + ReturnURL (display only)
│
├─ Subscription / 定期定額 / recurring membership?
│    → NDNP: create_period_payment
│      Separate MerchantID from NDNF — verify both credential sets exist
│      Changes after go-live: alter_period_status (pause/resume/terminate),
│                              alter_period_content (amount/cycle/expiry)
│
├─ "Did this order get paid?" / reconciliation?
│    → NDNF: query_trade  (canonical source of truth for a single MerchantOrderNo)
│      Use this whenever NotifyURL was missed, duplicated, or suspect
│
├─ Refund / cancellation?
│    ├─ Credit card, before close (請款)? → cancel_authorization (NPA-B01)
│    ├─ Credit card, after close?         → close_refund (NPA-B03x)
│    └─ LINE Pay / Taiwan Pay / e-wallet? → ewallet_refund (NPA-B06)
│
└─ Recurring mandate state change?
     ├─ Pause / resume / terminate      → alter_period_status
     └─ Change amount / cycle / expiry  → alter_period_content

When mcp-newebpay reports a "tool not configured" error, the corresponding NDNF or NDNP env group was not set — see README Environment variables table.

Implementation guidance

Three flows. For each, the exact mcp-newebpay tool is named. See references/integration-flow.md for full wiring and examples/sample_scenario.md for an end-to-end subscription walkthrough.

One-time payment (NDNF)

1. Merchant backend calls create_mpg_payment with MerchantOrderNo (your idempotency key), Amt (integer TWD), ItemDesc, Email, NotifyURL, ReturnURL, and which payment methods to enable (CREDIT, VACC for ATM, CVS, BARCODE, LINEPAY, APPLEPAY, ...)
2. Return value is {url, form_data}. The merchant must render an auto-submit HTML form that POSTs form_data to url. Do not attempt to follow the redirect server-side — the customer must hit NewebPay's hosted page in their own browser for 3DS 2.0 to work.
3. After the customer pays, NewebPay fires NotifyURL (server-to-server POST, decrypt TradeInfo, check Status == "SUCCESS"). This is the authoritative event. The customer's browser is also redirected to ReturnURL — treat this as a UI hint only, never as the completion signal.
4. On reconciliation doubt, call query_trade(MerchantOrderNo, Amt) to re-confirm server-side.

Recurring / 定期定額 (NDNP)

1. create_period_payment — establishes the mandate. Requires NDNP credentials. Returns the same {url, form_data} shape; the customer goes through one interactive auth on NewebPay's hosted page to authorize the mandate. After that, NewebPay charges on the cycle automatically and fires NotifyURL on each cycle.
2. Each billing cycle: NewebPay charges the stored card and posts to NotifyURL. Merchant must handle Status == "SUCCESS" (grant service period) and failure (card expired, insufficient funds, acquirer decline) separately — failures do not auto-retry.
3. Mandate lifecycle: pause/resume/terminate via alter_period_status; amount/cycle/expiry via alter_period_content. Treat PeriodNo (e.g., P260403144725zl3MVV) as the canonical handle — not the merchant order number.

Refund

• Credit card path depends on close (請款) state. Before close: cancel_authorization releases the hold. After close: close_refund with operation refund / cancel_refund. Close itself is also close_refund with operation close / cancel_close.
• E-wallet (LINE Pay / Taiwan Pay) path is different: ewallet_refund — the credit card close_refund tool will not work for wallet rails.
• Always check query_trade first to confirm CloseStatus (3 = settled) before choosing the refund tool.