應用場景
當訂單是使用信用卡定期定額的交易時，在每次授權成功後，綠界會傳送付款通知結果
- Step 1. 綠界：第二次授權是由綠界的排程進行授權，交易授權成功後以Server POST方式傳送付款通知至特店傳送的付款完成通知回傳網址[PeriodReturnURL]。
- Step 2. 特店：收到綠界的付款通知訊息後，需比對檢查碼是否相符。
注意事項：
- 第一次授權成功時，付款結果參數會回傳到付款完成通知回傳網址[ReturnURL]，
- 第二次授權成功是由綠界的排程進行授權，所以從第二次開始的資料，都是回傳到所設定的付款完成通知回傳網址[PeriodReturnURL]。
HTTPS 傳輸協定
- Accept ：text/html
- Content Type ：application/x-www-form-urlencoded
- HTTP Method ：POST
綠界回傳參數說明
MerchantID String(10)
特店編號
MerchantTradeNo String(20)
特店交易編號
訂單產生時傳送給綠界的特店交易編號。
StoreID String(20)
特店旗下店舖代號
RtnCode Int
交易狀態
- 若回傳值為1時，為付款成功
- 其餘代碼皆為交易異常，請至廠商管理後台確認後再出貨。
RtnMsg String(200)
交易訊息
PeriodType String(1)
訂單建立時所設定的週期種類
訂單建立時所設定的週期種類
Frequency Int
訂單建立時所設定的執行頻率
訂單建立時所設定的執行頻率
ExecTimes Int
訂單建立時所設定的執行次數
訂單建立時所設定的執行次數
Amount Int
本次授權金額
此次所授權的金額
Gwsr Int
授權交易單號
ProcessDate String (20)
處理時間
格式 yyyy/MM/dd HH:mm:ss
AuthCode String(6)
授權碼
授權碼
FirstAuthAmount Int
初次授權金額
定期定額交易的第一筆授權金額。
TotalSuccessTimes Int
已執行成功次數
目前已成功授權的次數。
CustomField1 String(50)
自訂名稱欄位1
提供合作廠商使用記錄用客製化使用欄位
CustomField2 String(50)
自訂名稱欄位2
提供合作廠商使用記錄用客製化使用欄位
CustomField3 String(50)
自訂名稱欄位3
提供合作廠商使用記錄用客製化使用欄位
CustomField4 String(50)
自訂名稱欄位4
提供合作廠商使用記錄用客製化使用欄位
CheckMacValue String
檢查碼
特店必須檢查檢查碼來驗證資料是否正確，請參考附錄檢查碼機制。
注意事項：
- 特店務必判斷檢查碼[CheckMacValue]是否正確，以及是否已經對該筆訂單的付款通知，做過相對應的處理，以免造成交易狀態無法同步的損失。
- [PeriodReturnURL]每期僅會收到一次通知，如未收到通知，請利用信用卡定期定額訂單查詢取得實際授權結果。
- 若遇消費者已付款，但未收到綠界回傳付款完成資訊，此時請檢查接收回傳參數的伺服器是否服務正常，導致無法接收。請參考：無法收到綠界回傳的付款結果通知
- 當模擬付款[SimulatePaid]的值為1時，表示此筆訂單資訊是由綠界廠商後台模擬付款按鈕所發送的回傳付款通知測試資訊，並非是由消費者實際真的付款，所以綠界也不會撥款給特店，請勿對該筆交易做出貨等動作，以避免損失。
- 特店務必判斷交易狀態[RtnCode]是否為1，若非1時請勿對該筆交易做出貨動作，並取得交易訊息[RtnMsg] 記錄失敗原因。
特店回覆參數說明
回傳值為純字串並無參數名稱。
若收到綠界回傳結果通知，請回傳1|OK，此訊息僅代表特店回應是否已收到綠界回傳通知，並不會影響訂單的狀態。
1|OK
YAML
提供的 YAML 文件用於定義 API 的配置、結構、操作和基礎設施管理等資訊，方便開發人員理解和使用 API。
openapi: 3.1.0
info:
title: ECPay Periodic Payment Result Notification API
version: 1.0.0
servers:
- url: PeriodReturnURL
description: Production Environment
- url: PeriodReturnURL
description: Testing Environment
paths:
/payment/periodic/Result:
post:
summary: Periodic Payment Result Notification
description: Notify the merchant of the periodic payment result.
requestBody:
required: true
content:
html/text:
schema:
type: object
required:
- MerchantID
- MerchantTradeNo
- RtnCode
properties:
MerchantID:
type: string
maxLength: 10
description: Merchant ID
MerchantTradeNo:
type: string
maxLength: 20
description: Merchant trade number, sent to ECPay when the order is created
StoreID:
type: string
maxLength: 20
description: Store ID under the merchant
RtnCode:
type: integer
description: Transaction status. If the return value is 1, it indicates successful payment. Other codes indicate transaction abnormalities. Please check in the merchant management backend before shipping.
RtnMsg:
type: string
maxLength: 200
description: Transaction message
TradeNo:
type: string
maxLength: 20
description: ECPay's transaction number. Please keep the relationship between ECPay's transaction number and the merchant trade number
TradeAmt:
type: integer
description: Transaction amount
PaymentDate:
type: string
maxLength: 20
format: date-time
description: Payment time
PaymentType:
type: string
maxLength: 20
description: Payment method selected by the merchant. Please refer to the list of payment methods returned
TradeDate:
type: string
maxLength: 20
format: date-time
description: Order creation time
SimulatePaid:
type: integer
enum: [0, 1]
description: Whether it is a simulated payment.
CustomField1:
type: string
maxLength: 50
description: Custom field 1, provided for cooperative partners for custom use
CustomField2:
type: string
maxLength: 50
description: Custom field 2, provided for cooperative partners for custom use
CustomField3:
type: string
maxLength: 50
description: Custom field 3, provided for cooperative partners for custom use
CustomField4:
type: string
maxLength: 50
description: Custom field 4, provided for cooperative partners for custom use
CheckMacValue:
type: string
description: Check code. Merchants must check the check code to verify
AlipayID:
type: string
maxLength: 10
description: Payee's system number in Alipay
AlipayTradeNo:
type: string
maxLength: 20
description: Alipay transaction number
TenpayTradeNo:
type: string
maxLength: 20
description: Tenpay transaction number
TWQRTradeNo:
type: string
maxLength: 64
description: Mobile payment transaction number. Returned only when the payment method is TWQR.
WebATMAccBank:
type: string
maxLength: 3
description: Payer's bank code for WebATM
WebATMAccNo:
type: string
maxLength: 5
description: Last five digits of the payer's bank account for WebATM
WebATMBankName:
type: string
maxLength: 10
description: Bank name
ATMAccBank:
type: string
maxLength: 3
description: Payer's bank code for ATM
ATMAccNo:
type: string
maxLength: 5
description: Last five digits of the payer's bank account for ATM
PaymentNo:
type: string
maxLength: 14
description: Payment code
PayFrom:
type: string
maxLength: 10
description: Payment store
enum: [family, hilife, okmart, ibon]
gwsr:
type: integer
description: Authorization transaction number. This parameter value is the same as CreditRefundID in credit card details query.
process_date:
type: string
maxLength: 20
format: date-time
description: Processing time
auth_code:
type: string
maxLength: 6
description: Authorization code
amount:
type: integer
description: Amount
stage:
type: integer
description: Number of installments
stast:
type: integer
description: Initial payment amount
staed:
type: integer
description: Subsequent payment amount
eci:
type: integer
description: 3D (VBV) return value (eci=5,6,2,1 represents 3D transaction)
card4no:
type: string
maxLength: 4
description: Last 4 digits of the card
card6no:
type: string
maxLength: 6
description: First 6 digits of the card
red_dan:
type: integer
description: Bonus point deduction
red_de_amt:
type: integer
description: Bonus redemption amount
red_ok_amt:
type: integer
description: Actual deduction amount
red_yet:
type: integer
description: Remaining bonus points
PeriodType:
type: string
maxLength: 1
description: Period type set when the order is created
Frequency:
type: integer
description: Execution frequency set when the order is created
ExecTimes:
type: integer
description: Execution frequency set when the order is created
PeriodAmount:
type: integer
description: Authorization amount per time set when the order is created
TotalSuccessTimes:
type: integer
description: Total number of successful authorizations at present
TotalSuccessAmount:
type: integer
description: Total amount of successful authorizations at present
responses:
'200':
description: Success
content:
text/plain:
schema:
type: string
example: 1|OK
'400':
description: Invalid request
'500':
description: Server error