N
NewebPay Integration Methodology 台灣電商：NewebPay Integration Methodology
Released已發布 industry ecommerce
Integrate NewebPay (藍新金流) for Taiwan e-commerce via mcp-newebpay. Use when accepting credit card / ATM / CVS / LINE Pay / periodical payments on NewebPay, handling 3DS 2.0 flows, computing TradeSha signatures, or reconciling callback webhooks. Do NOT use for comparing gateways (see tw-payment-integration) or for non-NewebPay providers (TapPay, ECPay have their own skills).
台灣電商技能：NewebPay Integration Methodology 分析與應用。
Assumptions前提假設
- {assumption grounded in a NewebPay constraint}
- TODO: {anything that needs verification against NewebPay merchant portal or NDNF/NDNP PDF}
Output Format輸出格式
When completing a NewebPay task, produce this structure:
# NewebPay Task: {one-line summary}
Gotchas注意事項
- TradeSha is NOT a generic alphabetical-sort HMAC. It is
SHA256("HashKey={key}&{TradeInfo blob}&HashIV={iv}").upper()—HashKeyfirst,HashIVlast, the literal encryptedTradeInfosandwiched between, and the result in uppercase hex. Developers who treat it as "sort params alphabetically and HMAC them" build something that validates against nothing.mcp-newebpayhandles this for you; if you hand-roll a verifier for NotifyURL, copy the exact format. - NotifyURL can arrive before, after, or simultaneously with ReturnURL. Never close an order on ReturnURL alone — the browser can be closed, the redirect can fail, or NotifyURL can beat the redirect to your server. Treat ReturnURL as "show the customer a thank-you page"; treat NotifyURL as "the money moved". If your order state machine depends on ordering, you will ship double-fulfillment or ghost-open-orders.
- NDNF and NDNP use different MerchantID / HashKey / HashIV. Cross-contaminating them produces a signature-valid-but-wrong-merchant request that NewebPay rejects with a generic error.
mcp-newebpayuses separate env groups (NEWEBPAY_NDNF_*vsNEWEBPAY_NDNP_*) specifically to prevent this; do not unify them in wrapper code. - HashIV must be exactly 16 bytes; HashKey must be exactly 32 bytes. Merchants migrating from the older MPG1 protocol often re-use MPG1 keys of the wrong length — AES-256-CBC then pads/truncates silently and every request fails decryption on NewebPay's side with an opaque "參數錯誤" (parameter error). If all requests are failing, check the lengths before anything else.
- 定期定額 does not auto-handle card expiry. When a customer's card expires, NewebPay marks the mandate as failed on the next cycle and fires NotifyURL with a failure code — but does not automatically suspend the mandate. Your backend must detect the failure code, notify the customer (SMS / email with an update-card link), and decide whether to
alter_period_statusto pause. Silent failures accumulate as unpaid subscription months. - Test endpoint is
ccore.newebpay.com; production iscore.newebpay.com. Both accept differently-provisioned MerchantID / HashKey pairs; a test key against the prod endpoint (or vice versa) returns "MerchantID 不存在" which looks like a bad credential but is really a wrong-endpoint bug.mcp-newebpayswitches viaNEWEBPAY_ENV=test|production; verify this before debugging credentials.
Tags標籤
taiwanpaymentnewebpayfintech