paynow

name

paynow

description

PayNow（立吉富，paynow.com.tw）台灣第三方支付 + 電子發票服務商 API 完整技術參考， 對應官方文件 docs.paynow.com.tw（2026 最新版）。PayNow 同時存在兩代金流串接： (1) 新版 REST API — PaymentIntent 付款意圖 + Component SDK v2（iframe 內嵌）+ Bearer Token（PrivateKey）認證 + HMAC-SHA256 Webhook 驗簽；端點 api.paynow.com.tw / sandboxapi.paynow.com.tw（建立/查詢/執行付款意圖、退款開立/查詢/列表、 Customer 綁卡 Token、ApplePay session、3DS/OTP session、Partner 商戶綁定）。 (2) 舊版 CashFlow API — HTTP form-post etopm.aspx 導轉式 + 背景交易 PayNowAPI_JS.aspx （請款 CP_gp / 退款 R_gp / 取消授權 CPA_gp / 交易查詢 PQS_gp / 票券核銷 T_S T_G）； 簽章用 SHA-1 PassCode、AES256（檢核碼 GP/GK 換鑰）、HMAC-SHA256、TripleDES； 端點 www.paynow.com.tw / test.paynow.com.tw；付款方式信用卡/WebATM/虛擬帳號/超商代碼 (ibon/FamiPort/icash)/超商條碼/銀聯/分期/自動扣款/ApplePay。 (3) 電子發票 API — Bearer Token；端點 invoiceapi-prod.paynow.com.tw / invoiceapi-dev.paynow.com.tw（開立 /api/invoices/issue、作廢 /api/invoices/cancel、 折讓 /api/invoices/allowance、折讓作廢 /api/invoices/cancel-allowance、 查詢 GET /api/invoices、POS 取號 + POS 開立）；載具 carrier_type、捐贈碼 npoban、 課稅別 tax_type、零稅率原因 zero_tax_rate_reason。 Use this skill whenever code or tasks involve PayNow、立吉富、paynow.com.tw、 docs.paynow.com.tw、台灣金流、台灣電子發票、付款通知 webhook、payment_result、 PaymentIntent、付款意圖、Component SDK、js.paynow.com.tw、PrivateKey/PublicKey、 etopm.aspx、PayNowAPI_JS.aspx、PassCode、BuysafeNo、WebNo、檢核碼、CheckNum、 EncryptionKey/EncryptionIV、退款 refund、交易查詢、/api/invoices/issue、carrier_type、 npoban、tax_type、X-Payment-Center-Hmac-Sha256、超商代碼 ibon/FamiPort、虛擬帳號、 e-invoice / 台灣金流串接，或在 Power Checkout 等 WooCommerce 外掛新增 PayNow provider。 本 SKILL 為唯一官方 API reference 來源——不要再去翻 docs.paynow.com.tw 官網。

PayNow（立吉富）金流 + 電子發票 API

PayNow 立吉富由立吉富股份有限公司提供，是台灣第三方支付（信用卡 / ATM / 超商代碼 / 超商條碼 / 銀聯 / 分期 / LINE Pay / Apple Pay）與電子發票加值服務商。 本文件對應官方開發者文件 docs.paynow.com.tw（2026 最新版）。

本 SKILL 撰寫對象為 Power Checkout（WooCommerce 外掛，PHP 8.1+）。所有範例以 PHP / WordPress 慣例呈現；官方文件提供的 C# 範例（加解密）也一併收錄於 references/encryption.md 供對照。

---

最關鍵認知：PayNow 有「三套」獨立 API，不要混用

PayNow 的文件同時存在三個彼此獨立的串接體系，認證方式、端點網域、加密簽章完全不同。 動手前先確認你要串的是哪一套：

#	體系	認證	端點網域（正式 / 測試）	加密簽章	適用
1	新版 REST + Component SDK	Bearer Token（PrivateKey）	api.paynow.com.tw / sandboxapi.paynow.com.tw	無對稱加密；Webhook 用 HMAC-SHA256（key=PrivateKey）	新案優先；iframe 內嵌付款（類似站內付）、API 退款、綁卡 Token
2	舊版 CashFlow（導轉 + 背景）	merchant 帳號 + 交易密碼 + 多層檢核碼	www.paynow.com.tw / test.paynow.com.tw	SHA-1 PassCode、AES256（GP/GK 換鑰）、HMAC-SHA256、TripleDES	既有導轉式金流（etopm.aspx）、背景請款/退款/查詢（PayNowAPI_JS.aspx）
3	電子發票	Bearer Token（商家 JWT-Token）	invoiceapi-prod.paynow.com.tw / invoiceapi-dev.paynow.com.tw	無對稱加密（純 Bearer）	開立 / 作廢 / 折讓 / 折讓作廢 / 查詢 / POS

判斷捷徑：看到 Authorization: Bearer {token} → 體系 1 或 3（REST）；看到 etopm.aspx / PayNowAPI_JS.aspx / PassCode / BuysafeNo / WebNo → 體系 2（舊版）。 新版 WooCommerce 整合建議走體系 1（PaymentIntent）+ 體系 3（發票）。

各體系完整端點與參數表見：

• 體系 1 → references/payment-rest-api.md
• 體系 2 → references/cashflow-legacy-api.md
• 體系 3 → references/invoice-api.md
• 加密簽章（三套全部）→ references/encryption.md
• 錯誤碼 → references/error-codes.md
• 課稅別 / 載具 / 捐贈 / 付款方式對照 → references/concepts.md

---

體系 1：新版 REST API（PaymentIntent + Component SDK）

環境與認證

正式：https://api.paynow.com.tw
測試：https://sandboxapi.paynow.com.tw
所有 API：Header  Authorization: Bearer {PrivateKey}   （type=apiKey, in=header）

• PayNow 有兩把金鑰：PublicKey（公鑰） 用於前端產生付款表單； PrivateKey（私鑰） 用於後端發起付款 / 退款 / 查詢與 Webhook 驗簽，絕不可外洩。
• 申請私鑰需向 PayNow 申請（信件主旨「申請 PayNow 串接私鑰 (PrivateKey)」）。
• Component SDK：<script src="https://js.paynow.com.tw/sdk/v2/index.js">， 以 PayNow.createPayment({publicKey, secret, env}) → mount() → checkout()。

標準流程（iframe 內嵌付款，類似站內付）

1. 後端 POST /api/v1/payment-intents（帶 amount/currency/allowedPaymentMethods/webhookUrl…）
   → 回 result.id（pp_xxx）+ result.secret（pp_xxx_st_xxx）
2. 前端載入 SDK → PayNow.createPayment({publicKey, secret, env:'sandbox'}) → mount('#container')
3. 使用者填卡 → PayNow.checkout() → SDK 完成 3DS（pending_review→success）
4. PayNow 以 POST 將 payment_result 推到 webhookUrl（HMAC-SHA256 驗簽）→ 更新訂單
5. 後端可 GET /api/v1/payment-intents/:id 補查狀態

端點速查（完整參數見 references/payment-rest-api.md）

功能	Method	路徑
建立付款意圖	POST	/api/v1/payment-intents
查詢付款意圖	GET	/api/v1/payment-intents/:id
執行付款（後端收單，需開通）	POST	/api/v1/payment-intents/:id/checkout
退款（開立）	POST	/api/v1/payment-intents/:id/refunds
退款列表	GET	/api/v1/refunds
退款查詢	GET	/api/v1/refunds/:uuid
建立 Customer（綁卡用）	POST	/api/v1/customers
查詢 Customer	GET	/api/v1/customers/:customer_uuid
查詢 Customer 卡片 Token	GET	/api/v1/customers/:customer_uuid/card-tokens
取得 fingerprint session（3DS）	GET	/api/v1/fingerprint-session
裝置資料回傳（3DS）	POST	/sessions/:sessionID/device-information
OTP / 3DS 結果回傳	POST	/sessions/:sessionID/confirm
請求 Apple Pay session	POST	/api/v2/apple-pay-session
確認 Apple Pay session	POST	/api/v1/apple-pay-session
Apple Pay 延遲付款列表	GET	/api/v1/payment-intents/apple-pay-deferreds
Apple Pay 延遲付款取消	POST	/api/v1/payment-intents/apple-pay-deferreds/:uuid/cancel
Partner 商戶清單	GET	/api/v1/partner/merchants
Partner 商戶綁定	POST	/api/v1/partner/merchants/binding

PaymentIntent 狀態機

status	意義
draft	已建立尚未付款
processing	交易進行中；失敗會退回 draft
pending_review	已發起付款、待驗證 3DS（信用卡）
success	交易完成
canceled	取消（僅 draft 可轉為取消）

統一回應格式

所有 REST API 回應外層固定：

{ "status": 200, "type": "success", "message": "", "result": {...}, "requestId": "uuid", "paginate": null }

allowedPaymentMethods 可選值：CreditCard、CreditCardInstallment、ATM、 ConvenienceStore（ibon/FamiPort）、LINEPayOnline、LINEPayOffline、ApplePay、 ApplePayDeferred。allowInstallments 可選：3,6,9,12,18,24。 ApplePayDeferred 不可與其他付款方式併用。

Webhook（payment_result）驗簽

PayNow 以 POST 推送付款結果到建立付款意圖時填的 webhookUrl：

• Header：X-Payment-Center-Topic: payment_result、X-Payment-Center-Hmac-Sha256: <簽章>、 X-Payment-Center-Webhook-Id、X-Payment-Center-API-Version: v1、X-Payment-Center-Triggered-At。
• 驗簽：X-Payment-Center-Hmac-Sha256 = 用商家 PrivateKey 對 raw payload 做 HMAC-SHA256。 收到後務必比對；正確才處理。
• payload 含 Status（Success/Failed）、OrderNo、PaymentNo、PaymentIntentId、 TransactionNo、Amount、PaymentType、Meta（卡號末四碼 / 授權碼 / 卡別 / CardToken）。
• 處理完務必回 HTTP 200 確認收到。

完整 payload 欄位、HMAC 驗簽 PHP 範例見 references/payment-rest-api.md 與 references/encryption.md。

---

體系 2：舊版 CashFlow API（導轉 + 背景交易）

導轉式金流（etopm.aspx，form-post）

正式：https://www.paynow.com.tw/service/etopm.aspx
測試：https://test.paynow.com.tw/service/etopm.aspx
傳遞方式：HTTP form POST；所有參數 URL Encode；字集 UTF-8

商家組好參數（含 PassCode SHA-1 簽章）後，以表單 POST 導轉到 etopm.aspx， 使用者於 PayNow 頁面完成付款，PayNow 再 POST 回商家設定的「交易成功 / 失敗回傳網址」。

• 送出 PassCode（傳遞碼） = strtoupper(sha1(WebNo + OrderNo + TotalPrice + apicode)) （依序串接，不含 + 號；apicode 為 API 串接碼）。
• 回傳 PassCode（驗證碼） = sha1(WebNo + OrderNo + TotalPrice + 商家交易密碼 + TranStatus) （部分服務需 strtoupper）。
• PassCode2（ibon/FamiPort/icash 成功時）= strtoupper(sha1(PassCode . ReceiverEmail))。
• PayType：01信用卡 02WebATM 03虛擬帳號 05代碼繳費 09銀聯 10超商條碼 11分期付款 13自動扣款/預存授權。CodeType（PayType=05 時）：0ibon 1FamiPort 2icash。
• 回傳關鍵欄位：BuysafeNo（PayNow 訂單編號）、TranStatus（S成功 F失敗）、 ErrDesc、pan_no4（卡末四碼）、ATMNo/BarCode1~3（虛擬帳號 / 超商條碼）。

背景交易（PayNowAPI_JS.aspx，server-to-server）

正式：https://www.paynow.com.tw/service/PayNowAPI_JS.aspx
測試：https://test.paynow.com.tw/service/PayNowAPI_JS.aspx

背景交易（請款 / 退款 / 取消授權 / 查詢）一律走 GP→GK→操作 三段握手換鑰：

1. OP=GP：取「隨機檢查碼 CheckNum」與回覆 PassCode（JStr 以「固定 bootstrap AES256 金鑰」加密）
2. OP=GK：用 CheckNum 取「動態 EncryptionKey / EncryptionIV」
3. OP=<操作>：業務 JSON 用步驟 2 的 Key/IV 做 AES256 加密 → 字串對半拆成 JStr1 + JStr2 → UrlEncode 上傳

操作	OP	用途
請款	CP_gp	對已授權交易請款
退款	R_gp	信用卡 / 交易退款
取消自動授權	CPA_gp	取消預存 / 自動扣款授權
交易狀態查詢	PQS_gp	查 BuysafeNo / 卡末四碼 / 分期 / 錯誤碼
票券核銷碼查詢	T_S	TripleDES 加密
票券核銷	T_G	TripleDES 加密

• 操作層 PassCode = strtoupper(sha1("2822" . UserID . 商家交易密碼 . "9955"))， 或含訂單時 strtoupper(sha1("2822" . mem_cid . OrderNo . 商家交易密碼 . "9955"))。
• 回應為純字串：成功 S_成功資訊（urlencode）/ 失敗 F_錯誤訊息（urlencode）。

bootstrap AES256 固定金鑰、GP/GK 加權檢核碼演算法、TimeStr 產生、三段握手 PHP 實作見 references/encryption.md；完整參數表見 references/cashflow-legacy-api.md。

---

體系 3：電子發票 API

環境與認證

測試：https://invoiceapi-dev.paynow.com.tw/
正式：https://invoiceapi-prod.paynow.com.tw/
所有 API：Header  Authorization: Bearer {商家 JWT-Token}

串接發票前需先取得商家 JWT-Token，打發票 API 時放入 Bearer Token。

端點速查（完整參數見 references/invoice-api.md）

功能	Method	路徑
單張發票開立	POST	/api/invoices/issue
發票作廢	POST	/api/invoices/cancel
發票折讓	POST	/api/invoices/allowance
折讓作廢	POST	/api/invoices/cancel-allowance
取得發票資料（查詢）	GET	/api/invoices?InvoiceNumber=&OrderNo=&Limit=&Page=
POS 機取得發票號碼	POST	/api/invoices/pos/invoice-numbers
POS 機發票開立	POST	/api/invoices/pos/issue

開立發票核心欄位

欄位	說明
order_no	訂單編號
total_amount	發票總金額
tax_amount	稅額（非統編發票帶 0，由國稅局算稅；統編發票帶實際稅額）
tax_type	SaleTax應稅 / ZeroTax零稅率 / FreeTax免稅 / MixTax混合（應稅+免 或 應稅+零）
carrier_type	None紙本 / PhoneBarCodeCarrier手機條碼 / EasyCardCarrier悠遊卡 / CitizenDigitalCardNo自然人憑證 / BuyerSnoPayNow 會員載具
carrier_id1 / carrier_id2	載具明碼 / 隱碼（手機條碼 / 悠遊卡 / 自然人憑證填；BuyerSno/None 留空）
npoban	捐贈愛心碼（捐贈發票）
is_pass_customs	是否經海關（零稅率必填）
zero_tax_rate_reason	零稅率原因 enum（ExportGoods 等）
buyer	{name, identifier(統編), address, phone, email}
items[]	{quantity, unit_price, amount, tax_type, tax_amount, description}
send_paper / send_sms	寄紙本 / 寄簡訊（額外扣點）

• POS 開立額外帶 invoice_number + invoice_date + random_number + is_printed（POS 自管號碼與隨機碼）。
• POS 取號的號碼不進一般上傳流程，未使用者於次期單數月 5 號上傳空白發票（須自行管理避免重複）。

載具 / 捐贈 / 課稅別完整規則、零稅率原因全表、各情境 request 範例見 references/invoice-api.md 與 references/concepts.md。

---

程式碼範例（references/php-examples.md）

references/php-examples.md 提供可直接套用的 PHP 8.1+ 範例（皆為依官方規格撰寫的整合範例）：

範例	涵蓋
PaynowRestClient	體系 1 Bearer 請求、建立/查詢付款意圖、退款
PaynowWebhookVerifier	體系 1 X-Payment-Center-Hmac-Sha256 HMAC-SHA256 驗簽
PaynowLegacyCrypto	體系 2 AES256(CBC/Zeros)、SHA-1 PassCode、HMAC-SHA256、TripleDES、TimeStr、加權檢核碼
PaynowLegacyClient	體系 2 GP→GK→操作 三段握手（請款 / 退款 / 查詢）
PaynowInvoiceClient	體系 3 開立 / 作廢 / 折讓 / 折讓作廢 / 查詢

---

禁止事項與常見陷阱

• ❌ 不要混用三套體系的端點與認證——REST（api.paynow.com.tw，Bearer）、 舊版（www.paynow.com.tw，PassCode）、發票（invoiceapi-*.paynow.com.tw，Bearer JWT） 各自獨立，帳號 / 金鑰 / 加密均不通用。
• ❌ 正式與測試環境完全獨立，帳號需個別申請，資料庫不互通；上線前不可在正式環境測試交易 （PayNow 會警告並停用賣家帳號）。
• ❌ 舊版 PassCode 串接不含 + 號——是把各值「直接相接」成一字串再 SHA-1，不是用 + 連接。
• ❌ 舊版 AES256 用 CBC + PaddingMode.Zeros（不是 PKCS#7），輸出 base64； 與 ezPay 的 AES-256-CBC（hex 輸出）、ECPay AES-128-CBC 都不同，不可套用其他服務商的 crypto。
• ❌ 舊版背景交易必須走 GP→GK→操作 換鑰；不能直接用固定金鑰打操作 API。
• ❌ 新版 Webhook 一定要用 PrivateKey 對 raw payload 做 HMAC-SHA256 驗簽後才處理，並回 HTTP 200。
• ❌ 發票 tax_amount：非統編發票帶 0（國稅局算稅），統編發票才帶實際稅額；填反會錯。
• ❌ 發票載具與捐贈互斥——carrier_type=None 才是紙本；捐贈帶 npoban 且 carrier_type 留空。
• ❌ 零稅率（tax_type=ZeroTax）必填 is_pass_customs 與 zero_tax_rate_reason。
• ❌ PaymentIntent 只有 draft 能轉 canceled；processing / success 不可取消（要退款）。
• ❌ ApplePayDeferred 不可與其他付款方式併用。
• ❌ PaymentIntent Checkout（後端收單）與部分舊版服務需先聯繫 PayNow 業務開通才可用。
• ❌ 退款（ATM）必填 bankCode / bankBranchCode / bankAccount；信用卡退款不需要。
• ❌ 別把文件站 URL https://docs.paynow.com.tw/api/...（curl 範例的 host）當成真實 API host—— 真實 host 是 api.paynow.com.tw / invoiceapi-prod.paynow.com.tw 等（見上方環境段）。

---

Reference 檔案導覽

檔案	內容
references/payment-rest-api.md	體系 1 全部端點逐欄位 request / response、PaymentIntent / Checkout / Refund / Customer / ApplePay / Session / Partner 參數表、Webhook payload 完整欄位
references/cashflow-legacy-api.md	體系 2 導轉式（etopm.aspx）各付款方式 request / 回傳參數、背景交易（請款 / 退款 / 取消授權 / 查詢 / 票券核銷）、PassCode 組成、PayType / CodeType 對照
references/invoice-api.md	體系 3 開立 / 作廢 / 折讓 / 折讓作廢 / 查詢 / POS 取號 / POS 開立逐欄位參數、載具 / 課稅別 / 零稅率原因全表、各情境 request 範例
references/encryption.md	三套加密簽章全集：REST HMAC-SHA256、舊版 SHA-1 PassCode、AES256(CBC/Zeros)、GP/GK 加權檢核碼、TimeStr、HMACSHA256、TripleDES、ApplePay Signature；含官方 C# 原文與 PHP 對照
references/error-codes.md	完整錯誤碼表（M 會員 / A 商務 / C 請款 / B 銀行 / R 退款 / N 修改 / P 查詢 / Q 會員查詢 / T 票券系列）+ 交易查詢回應格式
references/concepts.md	三代 API 架構對照、金鑰體系、付款方式 / 課稅別 / 載具 / 捐贈 / 狀態機、SFTP 對帳檔格式、台灣電子發票背景
references/php-examples.md	可直接使用的 PHP 8.1+ 範例：REST client、Webhook 驗簽、舊版 crypto、GP/GK 握手 client、發票 client