應用場景
提供特店利用信用卡卡號呼叫綠界API進行幕後交易授權。
注意事項：此 API 需與銀行連線，如遇銀行連線不穩定時可能導致回應時間增加。特店如需設定 API 連線逾時的時間，建議至少 30 秒以上。
API介接網址
- 測試環境: https://ecpayment-stage.ecpay.com.tw/1.0.0/Cashier/BackAuth
- 正式環境: https://ecpayment.ecpay.com.tw/1.0.0/Cashier/BackAuth
HTTPS 傳輸協定
- Content Type：application/json
- HTTP Method：POST
特店Request參數說明 (Json格式)
MerchantID String(10)
特店編號 必填
RqHeader Object
傳輸資料 必填
Timestamp Number
傳輸時間 必填
請將傳輸時間轉換為時間戳(GMT+8)，綠界會利用此參數將當下的時間轉為Unix TimeStamp來驗證此次介接的時間區間。
注意事項：
- 驗證時間區間為 10 分鐘內有效，若超過此驗證時間則此次訂單將無法建立，產生時間戳請參考相關資料。
- 合作特店須進行主機「時間校正」，避免主機產生時差，導致API無法正常運作。
Data String
加密資料 必填
此參數為加密過的 JSON 格式資料，加密方式請參考說明。
特店Request參數範例 (Json格式)
{
"MerchantID": "3002607",
"RqHeader": {
"Timestamp": 1234567890
},
"Data": "enter your data"
}
Data參數說明(Json格式)
注意事項：請在加密前對參數值進行 URLEncode
MerchantID String(10)
特店編號 必填
OrderInfo Object
交易訂單資訊 必填
MerchantTradeNo String(20)
特店交易編號 必填
僅支援a-zA-z0-9
MerchantTradeDate String(20)
特店交易時間 必填
格式為yyyy/MM/dd HH:mm:ss
TotalAmount Int
交易金額 必填
ItemName String(400)
商品名稱 必填
- 如有多項商品，商品名稱以分隔線#分開
- 請勿傳入超過長度 200 的內容，避免該欄位資訊被截斷
TradeDesc String(200)
交易描述 必填
ReturnURL String(200)
付款回傳結果URL 必填
請帶入可接收付款結果的URL
ChoosePayment Object
付款方式
固定為 Credit
CardInfo Object
信用卡資訊
CardNo String(19)
信用卡卡號
注意事項：美國運通卡需閘道商才能使用
CardValidMM String(2)
信用卡有效月份
CardValidYY String(2)
信用卡有效年份
CardCVV2 String(4)
信用卡安全碼
DirectCapture String(1)
是否立即請款
- 0 : 否 (預設值)
- 1 : 是
Redeem String(1)
信用卡紅利
有申請紅利的商家，紅利折抵參數才會有作用。不支援AE卡交易。
- N : 否 (預設值)
- Y : 是
CreditInstallment String(20)
刷卡分期期數
請帶入欲支援的分期期數，ex:3。如不須使用分期，可不帶值或是帶0。
PeriodAmount Int
定期定額授權金額
PeriodType String(1)
定期定額週期種類
- D：以天為週期
- M：以月為週期
- Y：以年為週期
Frequency Int
定期定額執行頻率
注意事項：
- 至少要大於等於 1 次以上
- 當 PeriodType 設為 D 時，最多可設 1~365(天)
- 當 PeriodType 設為 M 時，最多可設 1~12(月)
- 當 PeriodType 設為 Y 時，最多可設 1
注意事項：
- 當 PeriodType 設為 D 或 M 時，扣款日期為以當月是否有那一號做判斷，若無則以當月的最後一天扣款
ExecTimes Int
定期定額執行次數
注意事項：
- 當 PeriodType 設為 D 時，最多可設 999 次。
- 當 PeriodType 設為 M 時，最多可設 99 次。
- 當 PeriodType 設為 Y 時，最多可設 9 次。
PeriodReturnURL String(200)
定期定額執行結果回應網址
- 若交易為信用卡定期定額的方式，則每次執行授權結束後，會將定期定額授權結果回傳到這個設定的網址
- 請使用網域名稱(Domain Name System，DNS)，請勿使用IP
TravelStartDate String(20)
國旅卡旅遊起日
數字 mmddyyyy
注意事項：需閘道商才能使用
TravelEndDate String(20)
國旅卡旅遊迄日
數字 mmddyyyy
注意事項：需閘道商才能使用
TravelCounty String(20)
國旅卡旅遊縣市
注意事項：需閘道商才能使用
OrderResultURL String(200)
3D驗證回傳付款結果網址
注意事項：使用 3D 驗證時，當消費者付款完成後，綠界會將付款結果參數以前端頁面轉導的方式回傳到該網址。回傳參數請參考付款結果通知章節。
ConsumerInfo Object
持卡人資訊
Email String(30)
信用卡持卡人電子信箱
注意事項：檢核規則請參考正規表達式@”^([a-zA-Z\d._%-]+@[a-zA-Z\d.-]+\.[a-zA-Z]{2,6})*$”;
Phone String(60)
信用卡持卡人電話
可帶入國碼，但不可帶入+號。ex:886912345678
注意事項：若非台灣手機號碼，請在電話號碼前帶入國碼。 Name String(50)
信用卡持卡人姓名
- 該欄位可接受中文、英文與部分特殊符號
- 可支援的特殊符號為 : , . () / –
CountryCode String(3)
國別碼
- 持卡人帳單地址國別碼，請參考 ISO3166
- 臺灣請填寫 158
Address String(50)
地址
請帶入持卡人帳單地址
CustomField String(200)
自訂欄位
請勿傳入超過長度200的內容，避免該欄位資訊被截斷
Data參數範例(Json格式)
{
"MerchantID": "3002607",
"OrderInfo": {
"MerchantTradeDate" : "2022/05/23 14:10:00",
"MerchantTradeNo" : "1234567890",
"TotalAmount": 500,
"TradeDesc" : "交易描述",
"ItemName" : "泡麵#清潔用品",
"ReturnURL" : "https://aa.aa.aa"
}
}
綠界Response參數說明 (Json格式)
MerchantID String(10)
特店編號
RpHeader Object
回傳資料
Timestamp Number
回傳時間
時間戳 Unix timestamp
TransCode Int
回傳代碼
1 代表 API 傳輸資料 (MerchantID, RqHeader, Data) 接收成功，實際的API執行結果狀態請參考 RtnCode 參數
TransMsg String(200)
回傳訊息
Data String
加密資料
此參數為加密過的 JSON 格式資料
Data參數說明(Json格式) : 3D驗證或銀聯卡驗證
需進行3D驗證或銀聯卡驗證時，回傳以下參數
RtnCode Int
交易狀態
1 代表 API 執行成功，其餘代碼均為失敗，失敗代碼請參考交易訊息代碼表。
RtnMsg String(200)
回應訊息
MerchantID String(10)
特店編號
MerchantTradeNo String(20)
特店交易編號
ThreeDURL String(200)
3D或銀聯卡驗證網址
請把頁面導轉到銀行指定頁面，讓消費者進行驗證。
注意事項：驗證連結，請勿使用 iframe 方式開啟
Data參數說明(Json格式) :
當付款方式為信用卡一次付清、定期定額、分期付款且不需要進行3D或銀聯卡驗證時，將直接回傳以下授權結果
RtnCode Int
交易狀態
1 代表 API 執行成功，其餘代碼均為失敗，失敗代碼請參考交易訊息代碼表。
RtnMsg String(200)
回應訊息
MerchantID String(10)
特店編號
OrderInfo Object
交易訂單資訊
MerchantTradeNo String(20)
特店交易編號
TradeNo String(20)
綠界交易編號
請保存綠界的交易編號與特店交易編號MerchantTradeNo的關聯
TradeAmt Int
交易金額
TradeDate String(20)
訂單成立時間
格式為 yyyy/MM/dd HH:mm:ss
PaymentType String(20)
付款方式
- Credit: 信用卡
PaymentDate String(20)
付款時間
格式為 yyyy/MM/dd HH:mm:ss
ChargeFee Number
手續費
TradeStatus String(8)
交易狀態
若為 0 時，代表交易訂單付款失敗
若為 1 時，代表交易訂單付款成功
CardInfo Object
信用卡授權資訊
AuthCode String(6)
銀行授權碼
Gwsr Int
銀行授權碼
ProcessDate String(20)
交易時間
格式為 yyyy/MM/dd HH:mm:ss
Amount Int
金額
Card6No String(6)
信用卡卡號前六碼
Card4No String(4)
信用卡卡號末四碼
Eci Int
3D(VBV) 回傳值
Eci=5,6,2,1 代表該筆交易為3D交易，且付款方式為銀聯卡時不回傳
IssuingBank String(30)
發卡銀行名稱
IssuingBankCode String(10)
發卡銀行代碼
Stage Int
分期期數
分期付款時回傳
Stast Int
首期金額
分期付款時回傳
Staed Int
各期金額
分期付款時回傳
RedDan Int
紅利扣點
使用信用卡紅利時回傳
RedOkAmt Int
實際扣款金額
使用信用卡紅利時回傳
RedYet Int
紅利剩餘點數
使用信用卡紅利時回傳
RedDeAmt Int
紅利折抵金額
使用信用卡紅利時回傳
PeriodType String(1)
週期種類
定期定額時回傳，訂單所設定的週期種類
Frequency Int
執行頻率
定期定額時回傳，訂單所設定的執行頻率
ExecTimes Int
執行次數
定期定額時回傳，訂單所設定的執行次數
PeriodAmount Int
訂單每次要授權金額
定期定額時回傳
TotalSuccessTimes Int
目前已成功授權的次數
定期定額時回傳
TotalSuccessAmount Int
目前已成功授權的金額合計
定期定額時回傳
CoBrandingInfo Array[Object]
聯名卡資料
CoBrandingCode String(20)
聯名卡代號
Comment String(100)
備註
CustomField String(200)
自訂欄位
提供特店使用客制化欄位
綠界Response參數範例 (Json格式)
{
"RtnCode": 1,
"RtnMsg": "Success",
"MerchantID": "1234567890",
"CardInfo":
{
"Card6No": "123456",
"Card4No": "1234",
"IssuingBank": "中國信託商業銀行",
"IssuingBankCode ": "822",
"AuthCode": "654123",
"Gwsr": 125,
"ProcessDate": "2022/09/18 15:39:10",
"Amount": 2
"Eci": 1,
},
"OrderInfo":
{
"MerchantTradeNo": "test123466",
"TradeNo": "123456789",
"PaymentDate": "2022/09/18 15:39:10",
"TradeAmt": 2,
"PaymentType": "Credit",
"TradeDate": "2022/09/18 15:39:10",
"ChargeFee": 0,
"TradeStatus": "1",
}
}