應用場景
特店進行信用卡定期定額訂單交易作業。
- ReAuth：最新一筆定期定額交易授權失敗時，可發動進行補授權作業(於stage 測試環境無法測試)
- Cancel：終止本筆定期定額後續授權交易作業。
Step 1. 特店：以幕後方式傳送以下參數至API網址。
Step 2. 綠界：接受並檢核正確後，回傳信用卡定期定額作業結果。
注意事項：
- 目前API只提供補授權及終止定期定額交易作業，其他定期定額變更作業請登入廠商後台 -> 定期定額查詢作業進行。
- 當定期定額作業狀態為【暫停】、【終止】時，不能進行補授權作業。
介接路徑
- 測試環境：https://payment-stage.ecpay.com.tw/Cashier/CreditCardPeriodAction
- 正式環境：https://payment.ecpay.com.tw/Cashier/CreditCardPeriodAction
HTTPS 傳輸協定
- Content Type：application/x-www-form-urlencoded
- HTTP Method：POST
特店呼叫參數說明
MerchantID String(10)
Required
MerchantTradeNo String(20)
Required
- 訂單產生時傳送給綠界的特店交易編號。
Action String(20)
Required
- ReAuth：補授權失敗交易
- Cancel：終止定期定額後續交易
TimeStamp Int
Required
- 將當下的時間轉為UnixTimeStamp
用於驗證此次介接的時間區間。
CheckMacValue String
Required
- 請參考附錄檢查碼機制。
PlatformID String(10)
為專案合作的平台商使用。
- 一般特店或平台商本身介接，則參數請帶放空值。
- 若為專案合作平台商的特店使用時，則參數請帶平台商所綁的特店編號[MerchantID]。
注意事項：
- 定期定額信用卡補授權作業，限當筆交易最新一筆授權失敗時才能使用，例如第二期授權失敗，但第三期成功時，此時無法補授權第二期失敗的交易。
- 終止交易成功後，無法重新啟用，只能重新發動新定期定額訂單進行交易。
綠界回傳參數說明
RtnCode Int
交易狀態
- 1：成功，其餘為失敗
注意事項：
- 補授權交易，是由系統排程發發送補授權結果通知到[PeriodReturnURL]。
- 若RtnCode=90100149時，代表該訂單狀態已被停用，所以回傳作業失敗。
RtnMsg String(200)
交易訊息
MerchantID String(10)
特店編號
MerchantTradeNo String(20)
特店交易編號
- 訂單產生時傳送給綠界的特店交易編號。
CheckMacValue String
檢查碼
- 將收到的參數和參數值，加上特店的HashKey&HashIV所產生，請參考附錄檢查碼機制。
注意事項：特店務必判斷檢查碼[CheckMacValue]是否正確，以及是否已經對該筆訂單的付款通知，做過相對應的處理，以免造成交易狀態無法同步的損失。
YAML
提供的 YAML 文件用於定義 API 的配置、結構、操作和基礎設施管理等資訊，方便開發人員理解和使用 API。
openapi: 3.1.0
info:
title: ECPay Credit Card Recurring Order API
version: 1.0.0
description: API for managing ECPay credit card recurring orders, including reauthorization and cancellation.
servers:
- url: https://payment-stage.ecpay.com.tw
description: Test Environment
- url: https://payment.ecpay.com.tw
description: Production Environment
paths:
/Cashier/CreditCardPeriodAction:
post:
summary: Manage recurring credit card orders
description: API to reauthorize or cancel recurring credit card orders.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
MerchantID:
type: string
maxLength: 10
MerchantTradeNo:
type: string
maxLength: 20
Action:
type: string
enum: [ReAuth, Cancel]
TimeStamp:
type: integer
CheckMacValue:
type: string
PlatformID:
type: string
maxLength: 10
required:
- MerchantID
- MerchantTradeNo
- Action
- TimeStamp
- CheckMacValue
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
RtnCode:
type: integer
description: Transaction status (1 for success, others for failure)
RtnMsg:
type: string
maxLength: 200
description: Transaction message
MerchantID:
type: string
maxLength: 10
description: Merchant ID
MerchantTradeNo:
type: string
maxLength: 20
description: Merchant trade number
CheckMacValue:
type: string
description: Check code
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
schemas:
RequestData:
type: object
properties:
MerchantID:
type: string
maxLength: 10
MerchantTradeNo:
type: string
maxLength: 20
Action:
type: string
enum: [ReAuth, Cancel]
TimeStamp:
type: integer
CheckMacValue:
type: string
PlatformID:
type: string
maxLength: 10
required:
- MerchantID
- MerchantTradeNo
- Action
- TimeStamp
- CheckMacValue
ResponseData:
type: object
properties:
RtnCode:
type: integer
description: Transaction status (1 for success, others for failure)
RtnMsg:
type: string
maxLength: 200
description: Transaction message
MerchantID:
type: string
maxLength: 10
description: Merchant ID
MerchantTradeNo:
type: string
maxLength: 20
description: Merchant trade number
CheckMacValue:
type: string
description: Check code