NewebPay Integration Methodology

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