綁定信用卡 / 取得廠商驗證碼

應用場景

在使用綠界特店會員信用卡綁定服務之前，特店Server必須先向綠界Server取得一組廠商驗證碼(Token)。特店Server得到驗證碼後，必須將驗證碼傳給特店Web做產生綁定信用卡畫面功能之用。

注意事項：

如果廠商擁有一個以上特店編號MerchantID或綠界會員身分為平台商時，且特店的會員編號必須共享時，必須向綠界業務單位申請加入特約合作平台商PlatformID綁卡白名單。串接該API時，任一特店編號MerchantID請帶入參數PlatformID，且串接方式切換為平台商模式。
一個特店會員最多只能綁定5張信用卡。

API介接網址

測試環境: https://ecpg-stage.ecpay.com.tw/Merchant/GetTokenbyBindingCard
正式環境: https://ecpg.ecpay.com.tw/Merchant/GetTokenbyBindingCard

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

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

為專案合作的平台商使用
一般特店或平台商本身介接，則參數請帶空值
專案合作平台商的特店使用時，參數請帶平台商所綁的特店編號 MerchantID

注意事項：如果有帶入此參數，則外層MerchantID必須與PlatformID帶入相同值。

MerchantID String(10)
特店編號 必填

ConsumerInfo Object
消費者資訊 必填

消費者綁卡及3D 2.0驗證欄位資訊

注意事項：可降低3D驗證機率，避免失敗

MerchantMemberID String(60)
消費者會員編號 必填

為特店的會員系統中的會員編號(會員ID)
一個特店會員最多只能綁定5張信用卡

Email String(30)
信用卡持卡人電子信箱 必填

與參數Phone擇一必填

注意事項：檢核規則請參考正規表達式@”^([a-zA-Z\d._%-]+@[a-zA-Z\d.-]+\.[a-zA-Z]{2,6})*$”;

Phone String(60)
信用卡持卡人電話 必填

與參數Email擇一必填。

可帶入國碼，但不可帶入+號。ex:886912345678

Name String(50)
信用卡持卡人姓名

該欄位可接受中文、英文與部分特殊符號
可支援的特殊符號為 : , . () / –

CountryCode String(3)
國別碼

持卡人帳單地址國別碼，請參考 ISO3166
臺灣請填寫 158

Address String(50)
地址

請帶入持卡人帳單地址

OrderInfo Object
綁卡訂單資訊 必填

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

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

MerchantTradeNo String(20)
特店交易編號 必填

為唯一值，不可重複使用。僅支援a-zA-z0-9

TotalAmount Int
綁卡交易授權金額 必填

綁定信用卡前必須輸入該特店的最低交易金額，作為綁定信用卡3D驗證使用。

注意事項：

交易金額不可超過20萬元。
最低交易金額可於綠界廠商管理後台>>廠商專區>>金物流、電子發票合約及費率中查詢。
此金額為實際的交易授權金額，特店必須於綁定信用卡成功後將此交易取消授權。

TradeDesc String(200)
綁卡交易描述 必填

請自行帶入綁卡交易的描述

ItemName String(400)
交易名稱 必填

ReturnURL String(200)
綁卡回傳結果 必填

當消費者綁卡完成後，綠界會將綁卡結果參數以幕後方式回傳到該網址。

CreditInstallment String(20)
刷卡分期期數

欲支援的分期期數，如支援多期數，請以逗號分隔ex:3,6,9,12。如不支援分期，此欄位可不帶入參數值。

OrderResultURL String(200)
3D驗證綁卡回傳結果 必填

綁定信用卡需使用3D驗證。當3D驗證完成後，綠界會將綁卡結果參數以幕前方式回傳到該網址。

CustomField String(200)
自訂欄位

提供特店使用客制化欄位
請勿傳入超過長度 200 的內容，避免該欄位資訊被截斷

Data參數範例(Json格式)

				
					{
    "MerchantID": "3002607",
    "ConsumerInfo": {
        "MerchantMemberID": "test123456",
        "Email": "customer@email.com",
        "Phone": "0912345678",
        "Name": "Test",
        "CountryCode": "158"
    },
    "OrderInfo": {
　　    "MerchantTradeDate" : "2022/05/23 14:10:00",
        "MerchantTradeNo" : "1234567890",
        "TotalAmount":  500,
        "TradeDesc" : "綁定信用卡",
        "ItemName" : "V4綁定信用卡",
        "ReturnURL" : "https://aa.aa.aa"
    },
    "OrderResultURL": "https://bb.bb.bb"
}

綠界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 格式資料

綠界Response參數範例 (Json格式)

				
					{
    "MerchantID": "3002607",
    "RpHeader": {
        "Timestamp": 1234564848
    },
    "TransCode": 1,
    "TransMsg": "Success",
    "Data": "…"
}

Data參數說明(Json格式)

RtnCode Int
交易狀態

1 代表 API 執行成功，其餘代碼均為失敗，失敗代碼請參考交易訊息代碼表。

RtnMsg String(200)
回應訊息

PlatformID String(10)
平台商編號

MerchantID String(10)
特店編號

Token String(64)
代碼

代碼可使用的效期為 30 分鐘

TokenExpireDate String(20)
代碼到期時間

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

Data參數範例(Json格式)

				
					{
    "RtnCode": 1,
    "RtnMsg": "Success",
    "PlatformID": "1234567890",
    "MerchantID": "1234567890",
    "Token": "m12dae4846446sq",
    "TokenExpireDate": "2020/09/18 15:39:10"
}

綠界官方網站