付款方式 / 信用卡定期定額

快速導引

應用場景

有定期收款需求時，且收款金額相同，可使用此收款方式。消費者只需刷一次卡，之後綠界會透過排程並且依特店傳入的參數設定(PeriodType、Frequency、ExecTimes)，定期做信用卡授權。付款頁面會顯示每次刷卡的金額、週期及次數，可設定於「每幾天」或「每幾月」或「每一年」，扣幾次款（授權幾次）。

Step 1. 特店：將ChoosePayment 選擇預設付款方式設定為Credit、及傳入相關必填參數例如: PeriodAmount、PeriodType、Frequency、ExecTimes…等。
Step 2. 綠界：接受特店訂單並檢核資料。

注意事項：

不可以與信用卡紅利折抵、分期付款參數一起設定。
欲在測試環境進行刷卡功能，請使用綠界提供的信用卡測試卡號進行模擬付款。
如定期定額扣款失敗達六次，將會自動取消後續扣款。失敗扣款可透過定期定額訂單作業API進行補授權。

API介接網址

測試環境：https://payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5
正式環境：https://payment.ecpay.com.tw/Cashier/AioCheckOut/V5

注意事項：需透過前端網頁導轉(Submit)到綠界付款API網址。

HTTPS 傳輸協定

Content Type ：application/x-www-form-urlencoded
HTTP Method ：POST

特店傳入參數說明(共同參數)

MerchantID String(10)
特店編號 必填

特店編號

MerchantTradeNo String(20)
特店訂單編號 必填

特店訂單編號均為唯一值，不可重複使用。
英數字大小寫混合

注意事項：如何避免訂單編號重複請參考FAQ

MerchantTradeDate String(20)
特店交易時間 必填

格式為：yyyy/MM/dd HH:mm:ss

PaymentType String(20)
交易類型 必填

請固定填入 aio

TotalAmount Int
交易金額 必填

請帶整數，不可有小數點。
僅限新台幣

TradeDesc String(200)
交易描述 必填

請勿帶入特殊字元。

ItemName String(400)
商品名稱 必填

商品名稱

如果商品名稱有多筆，需在金流選擇頁一行一行顯示商品名稱的話，商品名稱請以符號#分隔。
商品名稱字數限制為中英數400字內，超過此限制系統將自動截斷。詳細的使用注意事項請參考FAQ。

ReturnURL String(200)
付款完成通知回傳網址 必填

ReturnURL為付款結果通知回傳網址，為特店server或主機的URL，用來接收綠界後端回傳的付款結果通知。
當消費者付款完成後，綠界會將付款結果參數以幕後回傳到該網址。詳細說明請參考付款結果通知

注意事項：

請勿設定與Client端接收付款結果網址OrderResultURL相同位置，避免程式判斷錯誤。
ReturnURL收到綠界後端回傳的付款結果通知後，請回應字串1|OK給綠界。
1|OK僅是廠商回應綠界是否收到通知，並不會改變付款狀態。
參數內容若有包含%26(&)及%3C(<) 這二個值時，請先進行urldecode() 避免呼叫API失敗。

ChoosePayment String(20)
選擇預設付款方式 必填

綠界提供下列付款方式：

Credit：信用卡

CheckMacValue String
檢查碼 必填

請參考檢查碼機制

EncryptType Int
CheckMacValue加密類型 必填

請固定填入1，使用SHA256加密。

StoreID String(10)
特店旗下店舖代號

提供特店填入分店代號使用，僅可用英數字大小寫混合。

ClientBackURL String(200)
Client端返回特店的按鈕連結

消費者點選此按鈕後，會將頁面導回到此設定的網址

注意事項：

導回時不會帶付款結果到此網址，只是將頁面導回而已。
設定此參數，綠界會在付款完成或取號完成頁面上顯示[返回商店]的按鈕。
設定此參數，發生簡訊OTP驗證失敗時，頁面上會顯示[返回商店]的按鈕。
若未設定此參數，則綠界付款完成頁或取號完成頁面，不會顯示[返回商店]的按鈕。
若導回網址未使用https時，部份瀏覽器可能會出現警告訊息。
參數內容若有包含%26(&)及%3C(<) 這二個值時，請先進行urldecode() 避免呼叫API失敗。

ItemURLString(200)
商品銷售網址

Remark String(100)
備註欄位

OrderResultURL String(200)
Client端回傳付款結果網址

有別於ReturnURL (server端的網址)，OrderResultURL為特店的client端(前端)網址。消費者付款完成後，綠界會將付款結果參數以POST方式回傳到到該網址。詳細說明請參考付款結果通知。

注意事項：

若與[ClientBackURL]同時設定，將會以此參數為主。
銀聯卡及非即時交易( ATM、CVS、BARCODE )不支援此參數。
付款結果通知請依ReturnURL (server端的網址)為主,避免因前端操作或網路問題未收到OrderResultURL 特店的client端(前端)的通知。
參數內容若有包含%26(&)及%3C(<) 這二個值時，請先進行urldecode() 避免呼叫API失敗。

NeedExtraPaidInfo String(1)
是否需要額外的付款資訊

額外的付款資訊

若不回傳額外的付款資訊時，參數值請傳：Ｎ；
若要回傳額外的付款資訊時，參數值請傳：Ｙ，付款完成後綠界後端會以POST方式回傳額外付款資訊到特店的ReturnURL 與OrderResultURL。

注意事項：回傳額外付款資訊參數請參考-額外回傳的參數

PlatformID String(10)
特約合作平台商代號

為專案合作的平台商使用。

CustomField1 String(50)
自訂名稱欄位1

提供合作廠商使用記錄客製化欄位。

CustomField2 String(50)
自訂名稱欄位2

提供合作廠商使用記錄客製化欄位。

CustomField3 String(50)
自訂名稱欄位3

提供合作廠商使用記錄客製化欄位。

CustomField4 String(50)
自訂名稱欄位4

提供合作廠商使用記錄客製化欄位。

Language String(3)
語系設定

預設語系為中文，若要變更語系參數值請帶：

ENG：英語
KOR：韓語
JPN：日語
CHI：簡體中文

信用卡定期定額參數

PeriodAmount Int
每次授權金額 必填

每次要授權(扣款)的金額。

注意事項：

綠界會依此次授權金額 [PeriodAmount] 所設定的金額做為之後固定授權的金額。
交易金額 [TotalAmount] 設定金額必須和授權金額 [PeriodAmount] 相同。
請帶整數，不可有小數點。僅限新台幣。

PeriodType String (1)
週期種類 必填

週期種類，可設定以天為扣款週期，或以月份為扣款週期。例如: PeriodType=D、Frequency=1、ExecTimes=5→此筆訂單將每日扣款1次、執行扣款5次後就結束不再扣款。
可設定以下參數：

D：以天為週期
M：以月為週期
Y：以年為週期

Frequency Int
執行頻率 必填

此參數用來定義多久要執行一次。

注意事項：

當 PeriodType 設為 D 時，可設定值為 1~365 (天)。
當 PeriodType 設為 M 時，可設定值為 1~12 (月)。
當 PeriodType 設為 Y 時，只可設定值為 1 (年)。

ExecTimes Int
執行次數 必填

此參數用來定義總共要執行幾次。
次數不可小於2次

注意事項：

當 PeriodType 設為 D 時，最多可設 999 次。
當 PeriodType 設為 M 時，最多可設 99 次。
當 PeriodType 設為 Y 時，最多可設 9 次。

PeriodReturnURL String (200)
定期定額的執行結果回應URL 非必填

若交易是信用卡定期定額的方式，則每次執行授權完，會將授權結果回傳到這個設定的URL。
回覆內容請參考付款結果通知。
請使用網域名稱(Domain Name System，DNS)，請勿使用IP。
參數內容若有包含%26(&)及%3C(<) 這二個值時，請先進行urldecode() 避免呼叫API失敗。

注意事項：

不可以與信用卡分期參數一起使用。
每次授權金額相同。
若第一次授權失敗，此訂單將不會進入排程，請重新建立一筆訂單。
若未設定接收定期定額的執行結果回傳PeriodReturnURL時，請特店要自行到綠界廠商管理後台確認每次授權狀態為成功時，才進行出貨。綠界廠商管理後台查詢路徑:信用卡收單 >> 定期定額查詢，設定查詢條件，依據查詢結果點選要查的訂單的「明細/編輯」，可參考下方範例圖示。
詳細範例請參考定期定額範例說明II。
若要停用某一筆訂單的定期定額收款，有兩種方式: 請使用定期定額訂單作業，或登入綠界廠商管理後台停用此筆訂單，綠界廠商後台查詢路徑請參考下方圖示。
銀聯卡不支援信用卡定期定額。
是否支援海外卡，是依照特店是否設定開通海外卡功能而定。支援的信用卡種類為VISA, JCB, MASTER。
網址參數內容若urlencode內容值時，請先對內容進行urldecode 避免呼叫API失敗。

信用卡記憶卡號參數

BindingCard Int
記憶卡號 非必填

使用記憶信用卡

使用：請傳 1
不使用：請傳 0

MerchantMemberID String(30)
記憶卡號識別碼 非必填

記憶卡號識別碼 ( 特店代號MerchantID+特店會員系統的會員編號 )

注意事項：

「欲使用 BindingCard、MerchantMemberID 這兩個參數功能，特店必須有會員系統。」
若記憶卡號識別碼為平台商的會員識別碼時，要特別向綠界申請使用。
記憶卡號功能僅支援 Visa / MasterCard / JCB，不支援銀聯卡。

第一次定期定額交易流程圖

第二次以後定期定額交易流程圖

付款示意圖

範例說明I （定期定額正常作業)

例1. 在音樂平台訂閱音樂，收費方式為每月月租費150元，合約期為一年，於2016/1/31日申請服務並付費開始使用服務，付費方式為信用卡定期定額，每月自動扣款。

注意事項：

若設定週期為每月或每年時，扣款日期為以當月是否有那一號做判斷，若無則以當月的最後一天扣款

範例說明II （定期定額重新授權作業)

例2. 在商店購買半年份的維他命，每月自動扣款680元，一共要付6次(半年)，於2016/1/10刷卡付款。
於2016/3/10 執行第3次扣款，但因為授權失敗(可能消費者信用卡額度不足等原因造成)造成扣款失敗，
特店若要進行再次授權，以登入綠界廠商管理後台自行操作或使用信用卡定期定額訂單作業API 進行手動補授權。

注意事項：

當定期定額授權失敗時，若未手動補授權，會等到下次扣款時間才會再進行扣款作業。

登入綠界廠商管理後台自行重新授權步驟：

登入綠界廠商管理後台https://vendor.ecpay.com.tw/
(1)信用卡收單＝＞(2)定期定額查詢＝＞(3)查詢要授權的訂單
找到要授權的訂單，點選明細/編輯

範例說明III（停用定期定額作業)

例3. 消費者欲不再購買商品，需停用定期定額付款方式，特店可以登入綠界廠商管理後台自行停用或使用信用卡定期定額訂單作業API

登入綠界廠商管理後台自行停用步驟：

登入綠界廠商管理後台https://vendor.ecpay.com.tw/
(1)信用卡收單＝＞(2)定期定額查詢＝＞(3)查詢要停用的訂單
找到要停用的訂單，點選明細/編輯

YAML

提供的 YAML 文件用於定義 API 的配置、結構、操作和基礎設施管理等資訊，方便開發人員理解和使用 API。

				
					openapi: 3.1.0
info:
  title: ECPay All-in-One Payment API
  description: API for creating orders and redirecting to ECPay's payment page, allowing various payment methods.
  version: 1.0.0
servers:
  - url: https://payment-stage.ecpay.com.tw
    description: Test Environment
  - url: https://payment.ecpay.com.tw
    description: Production Environment
paths:
  /Cashier/AioCheckOut/V5:
    post:
      summary: Create an order and redirect to ECPay's payment page
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                MerchantID:
                  type: string
                  maxLength: 10
                  description: Merchant ID
                  example: "2000132"
                MerchantTradeNo:
                  type: string
                  maxLength: 20
                  description: Unique merchant trade number
                  example: "1234567890"
                MerchantTradeDate:
                  type: string
                  format: date-time
                  description: Merchant trade date and time
                  example: "2024/05/27 12:34:56"
                PaymentType:
                  type: string
                  description: Payment type (fixed as aio)
                  example: "aio"
                  enum: ["aio"]
                TotalAmount:
                  type: integer
                  description: Total transaction amount (in TWD)
                  example: 1000
                TradeDesc:
                  type: string
                  maxLength: 200
                  description: Transaction description
                  example: "Test transaction"
                ItemName:
                  type: string
                  maxLength: 400
                  description: Names of the items
                  example: "Item1#Item2"
                ReturnURL:
                  type: string
                  maxLength: 200
                  description: URL for payment completion notification
                  example: "https://www.yourdomain.com/receive"
                ChoosePayment:
                  type: string
                  maxLength: 20
                  description: Default payment method
                  example: "Credit"
                  enum: ["Credit"]
                CheckMacValue:
                  type: string
                  description: Check Mac value for security
                  example: "6A7A8F08F6BCB08C3B0E60C90B7A8F14"
                EncryptType:
                  type: integer
                  description: Encryption type (fixed as 1)
                  example: 1
                  enum: [1]
                ClientBackURL:
                  type: string
                  maxLength: 200
                  description: URL to redirect client back to the merchant's site
                  example: "https://www.yourdomain.com"
                ItemURL:
                  type: string
                  maxLength: 200
                  description: URL of the item being sold
                  example: "https://www.yourdomain.com/item"
                Remark:
                  type: string
                  maxLength: 100
                  description: Remark field
                  example: "Additional notes"
                OrderResultURL:
                  type: string
                  maxLength: 200
                  description: URL to send payment result to client
                  example: "https://www.yourdomain.com/result"
                NeedExtraPaidInfo:
                  type: string
                  maxLength: 1
                  description: Whether extra payment info is needed (Y/N)
                  example: "Y"
                  enum: ["Y","N"]
                IgnorePayment:
                  type: string
                  maxLength: 100
                  description: Payment methods to hide
                  example: "ATM#CVS"
                PlatformID:
                  type: string
                  maxLength: 10
                  description: Platform ID for partnership
                  example: ""
                CustomField1:
                  type: string
                  maxLength: 50
                  description: Custom field 1
                  example: "Custom value 1"
                CustomField2:
                  type: string
                  maxLength: 50
                  description: Custom field 2
                  example: "Custom value 2"
                CustomField3:
                  type: string
                  maxLength: 50
                  description: Custom field 3
                  example: "Custom value 3"
                CustomField4:
                  type: string
                  maxLength: 50
                  description: Custom field 4
                  example: "Custom value 4"
                Language:
                  type: string
                  maxLength: 3
                  description: Language setting (default is CHI)
                  example: "ENG"
                  enum: ["ENG","KOR","JPN","CHI"]
                PeriodAmount:
                  type: integer
                  description: Period amount
                PeriodType:
                  type: string
                  maxLength: 1
                  description: Period type (D, M, Y)
                Frequency:
                  type: integer
                  description: Frequency
                ExecTimes:
                  type: integer
                  description: Execution times
                PeriodReturnURL:
                  type: string
                  maxLength: 200
                  description: Period return URL
              required:
                  - MerchantID
                  - MerchantTradeNo
                  - MerchantTradeDate
                  - PaymentType 
                  - TotalAmount 
                  - TradeDesc 
                  - ItemName 
                  - ReturnURL 
                  - ChoosePayment 
                  - CheckMacValue 
                  - EncryptType

綠界官方網站