/** * AES-256-CBC 加解密器。 * * 依據藍新金流技術文件 4.1.1 AES256 加密規範實作。 */ declare class Aes256Encoder { private readonly hashKey; private readonly hashIV; /** * 加密演算法。 */ private static readonly CIPHER_METHOD; /** * 建立加解密器。 * * @param hashKey HashKey * @param hashIV HashIV */ constructor(hashKey: string, hashIV: string); /** * 從設定建立加解密器。 * * @param hashKey HashKey * @param hashIV HashIV */ static create(hashKey: string, hashIV: string): Aes256Encoder; /** * 加密資料。 * * 將資料物件轉換為 URL 編碼查詢字串後進行 AES-256-CBC 加密。 * * @param data 原始資料 * @returns 加密後的十六進位字串 */ encrypt(data: Record): string; /** * 解密資料。 * * 將十六進位加密字串解密為資料物件。 * * @param tradeInfo 加密的 TradeInfo 字串 * @returns 解密後的資料物件 * @throws NewebPayError 當解密失敗時 */ decrypt(tradeInfo: string): Record; /** * 建立 URL 編碼查詢字串。 */ private buildQueryString; /** * 解析 URL 編碼查詢字串。 */ private parseQueryString; } /** * CheckValue (TradeSha) 編碼器。 * * 依據藍新金流技術文件 4.1.5 CheckValue 規範實作。 * 用於驗證交易資料的完整性。 */ declare class CheckValueEncoder { private readonly hashKey; private readonly hashIV; /** * 建立編碼器。 * * @param hashKey HashKey * @param hashIV HashIV */ constructor(hashKey: string, hashIV: string); /** * 從設定建立編碼器。 * * @param hashKey HashKey * @param hashIV HashIV */ static create(hashKey: string, hashIV: string): CheckValueEncoder; /** * 產生 CheckValue (TradeSha)。 * * 計算方式:SHA256(HashKey={HashKey}&{TradeInfo}&HashIV={HashIV}) * * @param tradeInfo 加密後的 TradeInfo 字串 * @returns 大寫的 SHA256 雜湊值 */ generate(tradeInfo: string): string; /** * 驗證 CheckValue (TradeSha)。 * * @param tradeInfo 加密後的 TradeInfo 字串 * @param tradeSha 收到的 TradeSha 值 */ verify(tradeInfo: string, tradeSha: string): boolean; /** * 驗證並拋出例外。 * * @param tradeInfo 加密後的 TradeInfo 字串 * @param tradeSha 收到的 TradeSha 值 * @throws NewebPayError 當驗證失敗時 */ verifyOrFail(tradeInfo: string, tradeSha: string): void; } /** * 支付操作介面。 */ interface PaymentInterface { /** * 設定特店訂單編號。 */ setMerchantOrderNo(orderNo: string): this; /** * 設定訂單金額。 */ setAmt(amount: number): this; /** * 設定商品資訊。 */ setItemDesc(desc: string): this; /** * 設定支付完成返回網址。 */ setReturnURL(url: string): this; /** * 設定支付通知網址。 */ setNotifyURL(url: string): this; /** * 取得請求路徑。 */ getRequestPath(): string; /** * 取得 Payload。 */ getPayload(): Record; /** * 取得已加密的內容。 */ getContent(): PaymentContent; } /** * 支付內容(加密後)。 */ interface PaymentContent { MerchantID: string; TradeInfo: string; TradeSha: string; Version: string; } /** * 基礎支付參數。 */ interface BasePaymentParams { MerchantID: string; MerchantOrderNo: string; TimeStamp: string; Version: string; Amt: number; ItemDesc: string; RespondType: string; LangType: string; ReturnURL?: string; NotifyURL?: string; CustomerURL?: string; ClientBackURL?: string; Email?: string; EmailModify?: number; TradeLimit?: number; ExpireDate?: string; OrderComment?: string; } /** * 支付設定。 */ interface PaymentConfig { merchantId: string; hashKey: string; hashIV: string; testMode?: boolean; returnUrl?: string; notifyUrl?: string; } /** * 藍新金流 Content 基礎類別。 * * 所有 MPG 支付操作類別的基類。 */ declare abstract class Content implements PaymentInterface { protected merchantId: string; protected hashKey: string; protected hashIV: string; /** * 特店訂單編號最大長度。 */ static readonly MERCHANT_ORDER_NO_MAX_LENGTH = 30; /** * 商品資訊最大長度。 */ static readonly ITEM_DESC_MAX_LENGTH = 50; /** * Email 最大長度。 */ static readonly EMAIL_MAX_LENGTH = 50; /** * MPG API 版本。 */ protected version: string; /** * API 請求路徑。 */ protected requestPath: string; /** * 是否為測試環境。 */ protected isTest: boolean; /** * 內容資料。 */ protected content: Record; /** * AES256 編碼器。 */ private aesEncoder?; /** * CheckValue 編碼器。 */ private checkValueEncoder?; /** * 建立 Content 實例。 * * @param merchantId 特店編號 * @param hashKey HashKey * @param hashIV HashIV */ constructor(merchantId?: string, hashKey?: string, hashIV?: string); /** * 驗證憑證參數。 */ private validateCredentials; /** * 初始化內容。 */ protected initContent(): void; /** * 設定特店編號。 */ setMerchantID(id: string): this; /** * 取得特店編號。 */ getMerchantID(): string; /** * 設定 HashKey。 */ setHashKey(key: string): this; /** * 設定 HashIV。 */ setHashIV(iv: string): this; /** * 設定是否為測試環境。 */ setTestMode(isTest: boolean): this; /** * 是否為測試環境。 */ isTestMode(): boolean; /** * 設定特店訂單編號。 */ setMerchantOrderNo(orderNo: string): this; /** * 設定時間戳記。 */ setTimeStamp(timestamp: number | string): this; /** * 設定訂單金額。 */ setAmt(amount: number): this; /** * 設定商品資訊。 */ setItemDesc(desc: string): this; /** * 設定交易限制秒數。 */ setTradeLimit(seconds: number): this; /** * 設定繳費有效期限。 */ setExpireDate(expireDate: string): this; /** * 設定支付完成返回網址。 */ setReturnURL(url: string): this; /** * 設定支付通知網址。 */ setNotifyURL(url: string): this; /** * 設定取號完成返回網址。 */ setCustomerURL(url: string): this; /** * 設定返回商店網址。 */ setClientBackURL(url: string): this; /** * 設定付款人電子信箱。 */ setEmail(email: string): this; /** * 設定是否開啟付款人資料修改。 */ setEmailModify(modify: number): this; /** * 設定商店備註。 */ setOrderComment(orderComment: string): this; /** * 設定語系。 */ setLangType(lang: string): this; /** * 取得請求路徑。 */ getRequestPath(): string; /** * 取得 API 基礎網址。 */ getBaseUrl(): string; /** * 取得完整 API 網址。 */ getApiUrl(): string; /** * 取得 AES256 編碼器。 */ getAesEncoder(): Aes256Encoder; /** * 取得 CheckValue 編碼器。 */ getCheckValueEncoder(): CheckValueEncoder; /** * 驗證內容資料。 */ protected abstract validation(): void; /** * 驗證基礎參數。 */ protected validateBaseParams(): void; /** * 取得 Payload。 */ getPayload(): Record; /** * 取得已加密的內容。 */ getContent(): PaymentContent; /** * 取得原始內容物件。 */ getRawContent(): Record; /** * 設定自訂內容。 */ set(key: string, value: unknown): this; /** * 取得內容值。 */ get(key: string, defaultValue?: T): T | undefined; } /** * HTML 表單產生器選項。 */ interface FormBuilderOptions { /** * 是否自動送出表單。 */ autoSubmit?: boolean; /** * 表單 ID。 */ formId?: string; /** * 送出按鈕文字。 */ submitButtonText?: string; } /** * HTML 表單產生器。 * * 用於產生自動送出或手動送出的支付表單。 * * ## 使用情境 * * ### 1. 傳統 HTML 表單(自動送出) * ```typescript * const builder = FormBuilder.create(payment); * const html = builder.build(); // 產生包含自動送出腳本的 HTML * ``` * * ### 2. 前端自訂表單 * 當你需要在前端框架(React、Vue 等)中自訂表單 UI 時,可以使用以下方法: * * - `getFormData()` 或 `getData()`: 取得完整的表單資料(包含 action、method、fields) * - `getFields()`: 只取得表單欄位資料 * * ```typescript * const builder = FormBuilder.create(payment); * const { action, method, fields } = builder.getData(); * // 或只取得欄位 * const fields = builder.getFields(); * ``` * * 這樣你就可以在前端使用 Fetch API、Axios 或其他 HTTP 客戶端來提交表單資料。 */ declare class FormBuilder { private readonly payment; private readonly options; /** * 建立表單產生器。 * * @param payment 支付操作物件 * @param options 選項 */ constructor(payment: PaymentInterface, options?: FormBuilderOptions); /** * 從支付操作物件建立表單產生器。 * * @param payment 支付操作物件 * @param options 選項 */ static create(payment: PaymentInterface, options?: FormBuilderOptions): FormBuilder; /** * 設定是否自動送出。 */ setAutoSubmit(autoSubmit: boolean): this; /** * 設定表單 ID。 */ setFormId(formId: string): this; /** * 設定送出按鈕文字。 */ setSubmitButtonText(text: string): this; /** * 產生 HTML 表單。 */ build(): string; /** * 取得表單資料(不含 HTML)。 * * 返回包含 action、method 和 fields 的完整表單資料物件。 * 適用於前端自訂表單的情境,可以使用 Fetch API 或其他 HTTP 客戶端提交。 * * @returns 表單資料物件,包含 action(API 端點)、method(HTTP 方法)和 fields(表單欄位) * * @example * ```typescript * const builder = FormBuilder.create(payment); * const { action, method, fields } = builder.getFormData(); * * // 使用 Fetch API 提交 * const formData = new FormData(); * Object.entries(fields).forEach(([key, value]) => { * formData.append(key, value); * }); * await fetch(action, { method, body: formData }); * ``` */ getFormData(): { action: string; method: string; fields: Record; }; /** * 取得表單資料(不含 HTML)。 * * 這是 `getFormData()` 的別名方法,提供更簡潔的命名。 * 適用於前端自訂表單的情境。 * * @returns 表單資料物件,包含 action(API 端點)、method(HTTP 方法)和 fields(表單欄位) * * @example * ```typescript * const builder = FormBuilder.create(payment); * const { action, method, fields } = builder.getData(); * ``` */ getData(): { action: string; method: string; fields: Record; }; /** * 取得表單欄位資料。 * * 只返回表單欄位物件,不包含 action 和 method。 * 適用於只需要欄位資料的情境,例如在 React/Vue 中動態建立表單元素。 * * @returns 表單欄位物件,包含 MerchantID、TradeInfo、TradeSha、Version * * @example * ```typescript * const builder = FormBuilder.create(payment); * const fields = builder.getFields(); * * // 在 React 中使用 * Object.entries(fields).map(([name, value]) => ( * * )); * ``` */ getFields(): Record; /** * 取得 API 網址。 */ private getApiUrl; /** * HTML 跳脫。 */ private escapeHtml; } /** * 信用卡一次付清支付。 * * 支援信用卡一次付清、紅利折抵等功能。 */ declare class CreditPayment extends Content { /** * 初始化內容。 */ protected initContent(): void; /** * 設定是否啟用紅利折抵。 */ setRedeem(enable: number): this; /** * 設定是否啟用銀聯卡。 */ setUnionPay(enable: number): this; /** * 設定是否啟用 Google Pay。 */ setGooglePay(enable: number): this; /** * 設定是否啟用 Samsung Pay。 */ setSamsungPay(enable: number): this; /** * 設定信用卡快速結帳。 */ setTokenTerm(enable: number): this; /** * 設定信用卡快速結帳使用者識別碼。 */ setTokenTermDemand(tokenTermId: string): this; /** * 驗證內容資料。 */ protected validation(): void; } /** * 信用卡分期支付。 * * 支援 3/6/12/18/24/30 期分期付款。 */ declare class CreditInstallment extends Content { /** * 允許的分期期數。 */ private static readonly ALLOWED_INSTALLMENTS; /** * 初始化內容。 */ protected initContent(): void; /** * 設定分期期數選項。 * * @param installments 分期期數陣列,例如 [3, 6, 12] */ setInstallment(installments: number[]): this; /** * 驗證內容資料。 */ protected validation(): void; } /** * 支付方式類型。 */ declare enum PaymentType { /** 信用卡 */ CREDIT = "CREDIT", /** WebATM */ WEBATM = "WEBATM", /** ATM 轉帳 */ VACC = "VACC", /** 超商代碼 */ CVS = "CVS", /** 超商條碼 */ BARCODE = "BARCODE", /** LINE Pay */ LINEPAY = "LINEPAY", /** 台灣 Pay */ TAIWANPAY = "TAIWANPAY", /** 玉山 Wallet */ ESUNWALLET = "ESUNWALLET", /** BitoPay */ BITOPAY = "BITOPAY", /** TWQR */ TWQR = "TWQR", /** 付啦 */ FULA = "FULA", /** 超商取貨付款 */ CVSCOM = "CVSCOM" } /** * 銀行類型(ATM 轉帳)。 */ declare enum BankType { /** 台灣銀行 */ BOT = "BOT", /** 華南銀行 */ HNCB = "HNCB", /** 第一銀行 */ FCB = "FCB" } /** * 超商類型。 */ declare enum StoreType { /** 全家 */ FAMI = "FAMI", /** 7-ELEVEN */ SEVEN = "SEVEN", /** OK */ OK = "OK", /** 萊爾富 */ HILIFE = "HILIFE" } /** * 物流類型(超商取貨)。 */ declare enum LgsType { /** 全家 */ FAMIC2C = "FAMIC2C", /** 萊爾富 */ HILIFEC2C = "HILIFEC2C", /** OK */ OKMARTC2C = "OKMARTC2C", /** 統一 */ UNIMARTC2C = "UNIMARTC2C" } /** * 交易狀態。 */ declare enum TradeStatus { /** 交易成功 */ SUCCESS = "SUCCESS", /** 交易失敗 */ FAILED = "FAILED", /** 待付款 */ PENDING = "PENDING" } /** * 請退款類型。 */ declare enum CloseType { /** 請款 */ PAY = 1, /** 退款 */ REFUND = 2 } /** * 依據類型。 */ declare enum IndexType { /** 藍新交易序號 */ TRADE_NO = "1", /** 特店訂單編號 */ MERCHANT_ORDER_NO = "2" } /** * ATM 虛擬帳號支付。 * * 產生虛擬帳號供消費者轉帳。 */ declare class AtmPayment extends Content { /** * 台灣銀行。 */ static readonly BANK_BOT = BankType.BOT; /** * 華南銀行。 */ static readonly BANK_HNCB = BankType.HNCB; /** * 第一銀行。 */ static readonly BANK_FCB = BankType.FCB; /** * 初始化內容。 */ protected initContent(): void; /** * 設定指定銀行。 */ setBankType(bankType: BankType | string): this; /** * 驗證內容資料。 */ protected validation(): void; } /** * WebATM 支付。 * * 即時網路 ATM 轉帳。 */ declare class WebAtmPayment extends Content { /** * 初始化內容。 */ protected initContent(): void; /** * 驗證內容資料。 */ protected validation(): void; } /** * 超商代碼繳費支付。 * * 金額限制 30~20,000 元。 */ declare class CvsPayment extends Content { /** * 最小金額。 */ static readonly MIN_AMT = 30; /** * 最大金額。 */ static readonly MAX_AMT = 20000; /** * 初始化內容。 */ protected initContent(): void; /** * 驗證內容資料。 */ protected validation(): void; } /** * 超商條碼繳費支付。 * * 金額限制 20~40,000 元。 */ declare class BarcodePayment extends Content { /** * 最小金額。 */ static readonly MIN_AMT = 20; /** * 最大金額。 */ static readonly MAX_AMT = 40000; /** * 初始化內容。 */ protected initContent(): void; /** * 驗證內容資料。 */ protected validation(): void; } /** * LINE Pay 支付。 * * LINE Pay 電子錢包支付。 */ declare class LinePayPayment extends Content { /** * 初始化內容。 */ protected initContent(): void; /** * 設定是否使用 LINE Pay 產品圖片。 */ setImageUrl(url: string): this; /** * 驗證內容資料。 */ protected validation(): void; } /** * 台灣 Pay 支付。 * * 台灣 Pay 行動支付。 */ declare class TaiwanPayPayment extends Content { /** * 初始化內容。 */ protected initContent(): void; /** * 驗證內容資料。 */ protected validation(): void; } /** * 玉山 Wallet 支付。 * * 玉山銀行電子錢包支付。 */ declare class EsunWalletPayment extends Content { /** * 初始化內容。 */ protected initContent(): void; /** * 驗證內容資料。 */ protected validation(): void; } /** * BitoPay 支付。 * * 加密貨幣支付。 */ declare class BitoPayPayment extends Content { /** * 初始化內容。 */ protected initContent(): void; /** * 驗證內容資料。 */ protected validation(): void; } /** * TWQR 共通支付。 * * 台灣 QR Code 共通支付。 */ declare class TwqrPayment extends Content { /** * 初始化內容。 */ protected initContent(): void; /** * 驗證內容資料。 */ protected validation(): void; } /** * 付啦支付。 * * 先買後付服務。 */ declare class FulaPayment extends Content { /** * 初始化內容。 */ protected initContent(): void; /** * 驗證內容資料。 */ protected validation(): void; } /** * 超商取貨付款支付。 * * 超商物流取貨付款服務。 */ declare class CvscomPayment extends Content { /** * 全家。 */ static readonly LGS_FAMI = LgsType.FAMIC2C; /** * 萊爾富。 */ static readonly LGS_HILIFE = LgsType.HILIFEC2C; /** * OK。 */ static readonly LGS_OK = LgsType.OKMARTC2C; /** * 統一。 */ static readonly LGS_UNIMART = LgsType.UNIMARTC2C; /** * 初始化內容。 */ protected initContent(): void; /** * 設定物流類型。 */ setLgsType(lgsType: LgsType | string): this; /** * 設定取貨人姓名。 */ setReceiverName(name: string): this; /** * 設定取貨人電話。 */ setReceiverPhone(phone: string): this; /** * 驗證內容資料。 */ protected validation(): void; } /** * 全支付方式。 * * 自訂啟用多種支付方式。 */ declare class AllInOnePayment extends Content { /** * 啟用信用卡。 */ enableCredit(enable?: boolean): this; /** * 啟用 WebATM。 */ enableWebAtm(enable?: boolean): this; /** * 啟用 ATM 轉帳。 */ enableAtm(enable?: boolean): this; /** * 啟用超商代碼。 */ enableCvs(enable?: boolean): this; /** * 啟用超商條碼。 */ enableBarcode(enable?: boolean): this; /** * 啟用 LINE Pay。 */ enableLinePay(enable?: boolean): this; /** * 啟用台灣 Pay。 */ enableTaiwanPay(enable?: boolean): this; /** * 啟用玉山 Wallet。 */ enableEsunWallet(enable?: boolean): this; /** * 啟用 BitoPay。 */ enableBitoPay(enable?: boolean): this; /** * 啟用 TWQR。 */ enableTwqr(enable?: boolean): this; /** * 啟用付啦。 */ enableFula(enable?: boolean): this; /** * 啟用信用卡分期。 */ enableInstallment(installments: number[]): this; /** * 啟用紅利折抵。 */ enableRedeem(enable?: boolean): this; /** * 啟用銀聯卡。 */ enableUnionPay(enable?: boolean): this; /** * 驗證內容資料。 */ protected validation(): void; } /** * 通知處理器介面。 */ interface NotifyHandlerInterface { /** * 驗證通知資料。 */ verify(data: NotifyRawData): boolean; /** * 取得解密後的資料。 */ getData(): Record; /** * 是否成功。 */ isSuccess(): boolean; /** * 取得狀態。 */ getStatus(): string; /** * 取得訊息。 */ getMessage(): string; } /** * 原始通知資料。 */ interface NotifyRawData { Status?: string; MerchantID?: string; TradeInfo?: string; TradeSha?: string; Version?: string; [key: string]: unknown; } /** * 支付通知結果。 */ interface PaymentNotifyResult { Status: string; Message: string; MerchantID?: string; Result?: PaymentResultData; } /** * 支付結果資料。 */ interface PaymentResultData { MerchantID?: string; MerchantOrderNo?: string; TradeNo?: string; Amt?: number; PaymentType?: string; PayTime?: string; IP?: string; PayBankCode?: string; /** 信用卡授權碼 */ Auth?: string; /** 卡號末四碼 */ Card4No?: string; /** 卡號前六碼 */ Card6No?: string; /** ECI 值 */ ECI?: string; /** 分期期數 */ Inst?: number; /** 首期金額 */ InstFirst?: number; /** 每期金額 */ InstEach?: number; [key: string]: unknown; } /** * ATM 取號通知結果。 */ interface AtmNotifyResult { Status: string; Message: string; Result?: AtmResultData; } /** * ATM 取號結果資料。 */ interface AtmResultData { MerchantID?: string; MerchantOrderNo?: string; TradeNo?: string; Amt?: number; BankCode?: string; CodeNo?: string; ExpireDate?: string; ExpireTime?: string; [key: string]: unknown; } /** * 超商取號通知結果。 */ interface CvsNotifyResult { Status: string; Message: string; Result?: CvsResultData; } /** * 超商取號結果資料。 */ interface CvsResultData { MerchantID?: string; MerchantOrderNo?: string; TradeNo?: string; Amt?: number; PaymentType?: string; CodeNo?: string; StoreType?: string; ExpireDate?: string; ExpireTime?: string; /** 條碼第一段 */ Barcode_1?: string; /** 條碼第二段 */ Barcode_2?: string; /** 條碼第三段 */ Barcode_3?: string; [key: string]: unknown; } /** * 超商取貨付款通知結果。 */ interface CvscomNotifyResult { Status: string; Message: string; Result?: CvscomResultData; } /** * 超商取貨付款結果資料。 */ interface CvscomResultData { MerchantID?: string; MerchantOrderNo?: string; TradeNo?: string; Amt?: number; PaymentType?: string; StoreType?: string; StoreCode?: string; StoreName?: string; StoreAddr?: string; TradeType?: number; CVSCOMName?: string; CVSCOMPhone?: string; LgsNo?: string; LgsType?: string; [key: string]: unknown; } /** * 支付完成通知處理器。 * * 處理藍新金流 ReturnURL / NotifyURL 回傳的支付結果通知。 */ declare class PaymentNotify implements NotifyHandlerInterface { private readonly aesEncoder; private readonly checkValueEncoder; /** * 原始通知資料。 */ private rawData; /** * 解密後的交易資料。 */ private data; /** * 是否已驗證。 */ private verified; /** * 建立通知處理器。 * * @param hashKey HashKey * @param hashIV HashIV */ constructor(hashKey: string, hashIV: string); /** * 從設定建立通知處理器。 */ static create(hashKey: string, hashIV: string): PaymentNotify; /** * 驗證通知資料。 */ verify(data: NotifyRawData): boolean; /** * 驗證並拋出例外。 */ verifyOrFail(data: NotifyRawData): this; /** * 解析解密後的資料。 */ private parseDecryptedData; /** * 取得解密後的資料。 */ getData(): Record; /** * 取得原始通知資料。 */ getRawData(): NotifyRawData; /** * 是否成功。 */ isSuccess(): boolean; /** * 取得狀態。 */ getStatus(): string; /** * 取得訊息。 */ getMessage(): string; /** * 取得特店編號。 */ getMerchantID(): string; /** * 取得特店訂單編號。 */ getMerchantOrderNo(): string; /** * 取得藍新金流交易序號。 */ getTradeNo(): string; /** * 取得交易金額。 */ getAmt(): number; /** * 取得支付方式。 */ getPaymentType(): string; /** * 取得交易時間。 */ getPayTime(): string; /** * 取得 IP 位址。 */ getIP(): string; /** * 取得付款銀行。 */ getPayBankCode(): string; /** * 取得授權碼(信用卡)。 */ getAuthCode(): string; /** * 取得卡號末四碼(信用卡)。 */ getCard4No(): string; /** * 取得卡號前六碼(信用卡)。 */ getCard6No(): string; /** * 取得 ECI 值(3D 驗證)。 */ getECI(): string; /** * 取得分期期數。 */ getInst(): number; /** * 取得首期金額。 */ getInstFirst(): number; /** * 取得每期金額。 */ getInstEach(): number; /** * 取得交易結果物件。 */ getResult(): PaymentResultData; /** * 是否已驗證。 */ isVerified(): boolean; } /** * ATM 取號通知處理器。 * * 處理 ATM 虛擬帳號取號完成的通知。 */ declare class AtmNotify implements NotifyHandlerInterface { private readonly aesEncoder; private readonly checkValueEncoder; /** * 原始通知資料。 */ private rawData; /** * 解密後的交易資料。 */ private data; /** * 是否已驗證。 */ private verified; /** * 建立通知處理器。 */ constructor(hashKey: string, hashIV: string); /** * 從設定建立通知處理器。 */ static create(hashKey: string, hashIV: string): AtmNotify; /** * 驗證通知資料。 */ verify(data: NotifyRawData): boolean; /** * 驗證並拋出例外。 */ verifyOrFail(data: NotifyRawData): this; /** * 解析解密後的資料。 */ private parseDecryptedData; /** * 取得解密後的資料。 */ getData(): Record; /** * 取得原始通知資料。 */ getRawData(): NotifyRawData; /** * 是否成功。 */ isSuccess(): boolean; /** * 取得狀態。 */ getStatus(): string; /** * 取得訊息。 */ getMessage(): string; /** * 取得特店訂單編號。 */ getMerchantOrderNo(): string; /** * 取得藍新金流交易序號。 */ getTradeNo(): string; /** * 取得交易金額。 */ getAmt(): number; /** * 取得銀行代碼。 */ getBankCode(): string; /** * 取得虛擬帳號。 */ getCodeNo(): string; /** * 取得繳費截止日。 */ getExpireDate(): string; /** * 取得繳費截止時間。 */ getExpireTime(): string; /** * 取得交易結果物件。 */ getResult(): AtmResultData; /** * 是否已驗證。 */ isVerified(): boolean; } /** * 超商取號通知處理器。 * * 處理超商代碼/條碼繳費取號完成的通知。 */ declare class CvsNotify implements NotifyHandlerInterface { private readonly aesEncoder; private readonly checkValueEncoder; /** * 原始通知資料。 */ private rawData; /** * 解密後的交易資料。 */ private data; /** * 是否已驗證。 */ private verified; /** * 建立通知處理器。 */ constructor(hashKey: string, hashIV: string); /** * 從設定建立通知處理器。 */ static create(hashKey: string, hashIV: string): CvsNotify; /** * 驗證通知資料。 */ verify(data: NotifyRawData): boolean; /** * 驗證並拋出例外。 */ verifyOrFail(data: NotifyRawData): this; /** * 解析解密後的資料。 */ private parseDecryptedData; /** * 取得解密後的資料。 */ getData(): Record; /** * 取得原始通知資料。 */ getRawData(): NotifyRawData; /** * 是否成功。 */ isSuccess(): boolean; /** * 取得狀態。 */ getStatus(): string; /** * 取得訊息。 */ getMessage(): string; /** * 取得特店訂單編號。 */ getMerchantOrderNo(): string; /** * 取得藍新金流交易序號。 */ getTradeNo(): string; /** * 取得交易金額。 */ getAmt(): number; /** * 取得支付方式。 */ getPaymentType(): string; /** * 取得繳費代碼。 */ getCodeNo(): string; /** * 取得超商類型。 */ getStoreType(): string; /** * 取得繳費截止日。 */ getExpireDate(): string; /** * 取得繳費截止時間。 */ getExpireTime(): string; /** * 取得條碼第一段。 */ getBarcode1(): string; /** * 取得條碼第二段。 */ getBarcode2(): string; /** * 取得條碼第三段。 */ getBarcode3(): string; /** * 取得交易結果物件。 */ getResult(): CvsResultData; /** * 是否已驗證。 */ isVerified(): boolean; } /** * 超商取貨付款通知處理器。 * * 處理超商取貨付款的通知。 */ declare class CvscomNotify implements NotifyHandlerInterface { private readonly aesEncoder; private readonly checkValueEncoder; /** * 原始通知資料。 */ private rawData; /** * 解密後的交易資料。 */ private data; /** * 是否已驗證。 */ private verified; /** * 建立通知處理器。 */ constructor(hashKey: string, hashIV: string); /** * 從設定建立通知處理器。 */ static create(hashKey: string, hashIV: string): CvscomNotify; /** * 驗證通知資料。 */ verify(data: NotifyRawData): boolean; /** * 驗證並拋出例外。 */ verifyOrFail(data: NotifyRawData): this; /** * 解析解密後的資料。 */ private parseDecryptedData; /** * 取得解密後的資料。 */ getData(): Record; /** * 取得原始通知資料。 */ getRawData(): NotifyRawData; /** * 是否成功。 */ isSuccess(): boolean; /** * 取得狀態。 */ getStatus(): string; /** * 取得訊息。 */ getMessage(): string; /** * 取得特店訂單編號。 */ getMerchantOrderNo(): string; /** * 取得藍新金流交易序號。 */ getTradeNo(): string; /** * 取得交易金額。 */ getAmt(): number; /** * 取得支付方式。 */ getPaymentType(): string; /** * 取得超商類型。 */ getStoreType(): string; /** * 取得門市代碼。 */ getStoreCode(): string; /** * 取得門市名稱。 */ getStoreName(): string; /** * 取得門市地址。 */ getStoreAddr(): string; /** * 取得取貨人姓名。 */ getCVSCOMName(): string; /** * 取得取貨人電話。 */ getCVSCOMPhone(): string; /** * 取得物流編號。 */ getLgsNo(): string; /** * 取得物流類型。 */ getLgsType(): string; /** * 取得交易結果物件。 */ getResult(): CvscomResultData; /** * 是否已驗證。 */ isVerified(): boolean; } /** * HTTP 客戶端介面。 */ interface HttpClientInterface { /** * 發送 POST 請求。 * * @param url 請求 URL * @param data 請求資料 * @returns 回應資料 */ post(url: string, data: Record): Promise; } /** * 查詢結果。 */ interface QueryOrderResult { MerchantID?: string; MerchantOrderNo?: string; TradeNo?: string; Amt?: number; TradeStatus?: string; PaymentType?: string; CreateTime?: string; PayTime?: string; CheckCode?: string; FundTime?: string; ShopMerchantID?: string; [key: string]: unknown; } /** * 交易查詢。 * * 查詢藍新金流交易訂單狀態。 */ declare class QueryOrder { protected merchantId: string; protected hashKey: string; protected hashIV: string; /** * API 版本。 */ protected version: string; /** * API 請求路徑。 */ protected requestPath: string; /** * 是否為測試環境。 */ protected isTest: boolean; protected httpClient: HttpClientInterface; /** * 建立查詢物件。 */ constructor(merchantId: string, hashKey: string, hashIV: string, httpClient?: HttpClientInterface); /** * 從設定建立查詢物件。 */ static create(merchantId: string, hashKey: string, hashIV: string, httpClient?: HttpClientInterface): QueryOrder; /** * 設定是否為測試環境。 */ setTestMode(isTest: boolean): this; /** * 取得 API 基礎網址。 */ getBaseUrl(): string; /** * 取得完整 API 網址。 */ getApiUrl(): string; /** * 執行查詢。 */ query(merchantOrderNo: string, amt: number): Promise; /** * 建立請求 Payload。 */ protected buildPayload(merchantOrderNo: string, amt: number): Record; /** * 產生查詢用 CheckValue。 * * 查詢 API 的 CheckValue 計算方式與 MPG 不同: * SHA256(HashIV={HashIV}&Amt={Amt}&MerchantID={MerchantID}&MerchantOrderNo={MerchantOrderNo}&HashKey={HashKey}) */ protected generateCheckValue(merchantOrderNo: string, amt: number): string; /** * 解析回應。 */ protected parseResponse(response: { Status?: string; Message?: string; Result?: QueryOrderResult; }): QueryOrderResult; } /** * 信用卡交易明細查詢結果。 */ interface QueryCreditDetailResult { MerchantID?: string; MerchantOrderNo?: string; TradeNo?: string; Amt?: number; CloseAmt?: number; CloseStatus?: string; BackBalance?: number; BackStatus?: string; RespondCode?: string; Auth?: string; ECI?: string; CloseAmt0?: number; CloseStatus0?: string; [key: string]: unknown; } /** * 信用卡交易明細查詢。 * * 查詢信用卡請退款狀態。 */ declare class QueryCreditDetail { protected merchantId: string; protected hashKey: string; protected hashIV: string; /** * API 版本。 */ protected version: string; /** * API 請求路徑。 */ protected requestPath: string; /** * 是否為測試環境。 */ protected isTest: boolean; /** * AES256 編碼器。 */ private aesEncoder?; /** * HTTP 客戶端。 */ protected httpClient: HttpClientInterface; /** * 建立查詢物件。 */ constructor(merchantId: string, hashKey: string, hashIV: string, httpClient?: HttpClientInterface); /** * 從設定建立查詢物件。 */ static create(merchantId: string, hashKey: string, hashIV: string, httpClient?: HttpClientInterface): QueryCreditDetail; /** * 設定是否為測試環境。 */ setTestMode(isTest: boolean): this; /** * 取得 API 基礎網址。 */ getBaseUrl(): string; /** * 取得完整 API 網址。 */ getApiUrl(): string; /** * 執行查詢。 */ query(merchantOrderNo: string, amt: number): Promise; /** * 建立請求 Payload。 */ protected buildPayload(merchantOrderNo: string, amt: number): Record; /** * 解析回應。 */ protected parseResponse(response: { Status?: string; Message?: string; Result?: QueryCreditDetailResult; }): QueryCreditDetailResult; /** * 取得 AES256 編碼器。 */ private getAesEncoder; } /** * 請退款結果。 */ interface CreditCloseResult { MerchantID?: string; MerchantOrderNo?: string; TradeNo?: string; Amt?: number; CloseType?: number; [key: string]: unknown; } /** * 信用卡請退款。 * * 對已授權的信用卡交易進行請款或退款操作。 */ declare class CreditClose { protected merchantId: string; protected hashKey: string; protected hashIV: string; /** * 請款類型:請款。 */ static readonly CLOSE_TYPE_PAY = CloseType.PAY; /** * 請款類型:退款。 */ static readonly CLOSE_TYPE_REFUND = CloseType.REFUND; /** * API 版本。 */ protected version: string; /** * API 請求路徑。 */ protected requestPath: string; /** * 是否為測試環境。 */ protected isTest: boolean; /** * AES256 編碼器。 */ private aesEncoder?; /** * HTTP 客戶端。 */ protected httpClient: HttpClientInterface; /** * 建立請退款物件。 */ constructor(merchantId: string, hashKey: string, hashIV: string, httpClient?: HttpClientInterface); /** * 從設定建立請退款物件。 */ static create(merchantId: string, hashKey: string, hashIV: string, httpClient?: HttpClientInterface): CreditClose; /** * 設定是否為測試環境。 */ setTestMode(isTest: boolean): this; /** * 取得 API 基礎網址。 */ getBaseUrl(): string; /** * 取得完整 API 網址。 */ getApiUrl(): string; /** * 執行請款。 */ pay(merchantOrderNo: string, amt: number, indexType?: IndexType | string, tradeNo?: string): Promise; /** * 執行退款。 */ refund(merchantOrderNo: string, amt: number, indexType?: IndexType | string, tradeNo?: string): Promise; /** * 取消請退款。 */ cancelClose(merchantOrderNo: string, amt: number, closeType: CloseType | number, indexType?: IndexType | string, tradeNo?: string): Promise; /** * 執行請退款操作。 */ protected execute(merchantOrderNo: string, amt: number, closeType: CloseType | number, indexType?: IndexType | string, tradeNo?: string, cancel?: boolean): Promise; /** * 建立請求 Payload。 */ protected buildPayload(postData: Record): Record; /** * 解析回應。 */ protected parseResponse(response: { Status?: string; Message?: string; Result?: CreditCloseResult; }): CreditCloseResult; /** * 取得 AES256 編碼器。 */ private getAesEncoder; } /** * 取消授權結果。 */ interface CreditCancelResult { MerchantID?: string; MerchantOrderNo?: string; TradeNo?: string; Amt?: number; [key: string]: unknown; } /** * 信用卡取消授權。 * * 取消尚未請款的信用卡授權交易。 */ declare class CreditCancel { protected merchantId: string; protected hashKey: string; protected hashIV: string; /** * API 版本。 */ protected version: string; /** * API 請求路徑。 */ protected requestPath: string; /** * 是否為測試環境。 */ protected isTest: boolean; /** * AES256 編碼器。 */ private aesEncoder?; /** * HTTP 客戶端。 */ protected httpClient: HttpClientInterface; /** * 建立取消授權物件。 */ constructor(merchantId: string, hashKey: string, hashIV: string, httpClient?: HttpClientInterface); /** * 從設定建立取消授權物件。 */ static create(merchantId: string, hashKey: string, hashIV: string, httpClient?: HttpClientInterface): CreditCancel; /** * 設定是否為測試環境。 */ setTestMode(isTest: boolean): this; /** * 取得 API 基礎網址。 */ getBaseUrl(): string; /** * 取得完整 API 網址。 */ getApiUrl(): string; /** * 執行取消授權。 */ cancel(merchantOrderNo: string, amt: number, indexType?: IndexType | string, tradeNo?: string): Promise; /** * 建立請求 Payload。 */ protected buildPayload(postData: Record): Record; /** * 解析回應。 */ protected parseResponse(response: { Status?: string; Message?: string; Result?: CreditCancelResult; }): CreditCancelResult; /** * 取得 AES256 編碼器。 */ private getAesEncoder; } /** * 電子錢包退款結果。 */ interface EWalletRefundResult { MerchantID?: string; MerchantOrderNo?: string; TradeNo?: string; Amt?: number; RefundAmt?: number; [key: string]: unknown; } /** * 支援的電子錢包類型。 */ type EWalletType = 'LINEPAY' | 'ESUNWALLET' | 'TAIWANPAY'; /** * 電子錢包退款。 * * 對 LINE Pay、玉山 Wallet、台灣 Pay 等電子錢包交易進行退款。 */ declare class EWalletRefund { protected merchantId: string; protected hashKey: string; protected hashIV: string; /** * API 版本。 */ protected version: string; /** * API 請求路徑。 */ protected requestPath: string; /** * 是否為測試環境。 */ protected isTest: boolean; /** * AES256 編碼器。 */ private aesEncoder?; /** * HTTP 客戶端。 */ protected httpClient: HttpClientInterface; /** * 建立退款物件。 */ constructor(merchantId: string, hashKey: string, hashIV: string, httpClient?: HttpClientInterface); /** * 從設定建立退款物件。 */ static create(merchantId: string, hashKey: string, hashIV: string, httpClient?: HttpClientInterface): EWalletRefund; /** * 設定是否為測試環境。 */ setTestMode(isTest: boolean): this; /** * 取得 API 基礎網址。 */ getBaseUrl(): string; /** * 取得完整 API 網址。 */ getApiUrl(): string; /** * 執行退款。 * * @param merchantOrderNo 特店訂單編號 * @param amt 退款金額 * @param paymentType 電子錢包類型 */ refund(merchantOrderNo: string, amt: number, paymentType: EWalletType): Promise; /** * 建立請求 Payload。 */ protected buildPayload(postData: Record): Record; /** * 解析回應。 */ protected parseResponse(response: { Status?: string; Message?: string; Result?: EWalletRefundResult; }): EWalletRefundResult; /** * 取得 AES256 編碼器。 */ private getAesEncoder; } /** * 藍新金流 SDK 自訂例外。 */ declare class NewebPayError extends Error { /** * 錯誤代碼。 */ readonly code: string | undefined; /** * HTTP 狀態碼(僅適用於 HTTP 錯誤)。 */ readonly httpStatus?: number; /** * 請求 URL(僅適用於網路相關錯誤)。 */ readonly url?: string; /** * 欄位名稱(僅適用於驗證錯誤)。 */ readonly field?: string; constructor(message: string, code?: string, options?: { httpStatus?: number | undefined; url?: string | undefined; field?: string | undefined; }); /** * 必要欄位未填寫。 */ static required(field: string): NewebPayError; /** * 欄位值過長。 */ static tooLong(field: string, maxLength: number): NewebPayError; /** * 欄位值無效。 */ static invalid(field: string, reason: string): NewebPayError; /** * 解密失敗。 */ static decryptFailed(): NewebPayError; /** * CheckValue 驗證失敗。 */ static checkValueFailed(): NewebPayError; /** * API 請求錯誤。 */ static apiError(message: string, code?: string): NewebPayError; /** * HTTP 錯誤。 */ static httpError(status: number, statusText: string, url?: string): NewebPayError; /** * 請求超時。 */ static timeout(timeoutMs: number, url?: string): NewebPayError; /** * 網路錯誤。 */ static networkError(message: string, url?: string): NewebPayError; /** * 轉換為 JSON 物件。 */ toJSON(): Record; } /** * 取得當前 Unix 時間戳(秒)。 * * @returns Unix 時間戳字串 */ declare function getTimestamp(): string; /** * 取得當前 Unix 時間戳數字(秒)。 * * @returns Unix 時間戳數字 */ declare function getTimestampNumber(): number; export { Aes256Encoder, AllInOnePayment, AtmNotify, type AtmNotifyResult, AtmPayment, type AtmResultData, BankType, BarcodePayment, type BasePaymentParams, BitoPayPayment, CheckValueEncoder, CloseType, Content, CreditCancel, type CreditCancelResult, CreditClose, type CreditCloseResult, CreditInstallment, CreditPayment, CvsNotify, type CvsNotifyResult, CvsPayment, type CvsResultData, CvscomNotify, type CvscomNotifyResult, CvscomPayment, type CvscomResultData, EWalletRefund, type EWalletRefundResult, type EWalletType, EsunWalletPayment, FormBuilder, type FormBuilderOptions, FulaPayment, IndexType, LgsType, LinePayPayment, NewebPayError, type NotifyHandlerInterface, type NotifyRawData, type PaymentConfig, type PaymentContent, type PaymentInterface, PaymentNotify, type PaymentNotifyResult, type PaymentResultData, PaymentType, QueryCreditDetail, type QueryCreditDetailResult, QueryOrder, type QueryOrderResult, StoreType, TaiwanPayPayment, TradeStatus, TwqrPayment, WebAtmPayment, getTimestamp, getTimestampNumber };