付款方式 / 信用卡一次付清

快速導引

應用場景

當特店提供消費者在綠界付款頁面使用信用卡一次付清或銀聯卡交易時。

Step 1. 特店：將 ChoosePayment 選擇預設付款方式設定為 Credit。
Step 2. 綠界：接受特店訂單並檢核資料。

注意事項：

由於一次付清、分期付款、定期定額此三種付款方式無法同時顯示於綠界付款頁，故無法同時設定信用卡定期定額、分期付款的相關參數。
欲在測試環境進行刷卡功能，請使用綠界提供的信用卡測試卡號進行模擬付款。

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：信用卡及銀聯卡(需申請開通)

注意事項：

若為手機版時不支援下列付款方式：WebATM
如需要不透過綠界畫面取得ATM、CVS、BARCODE的繳費代碼，請參考如何不經過綠界畫面取得ATM、CVS、BARCODE的繳費代碼。
當瀏覽器不為Safari時，不會顯示Apple Pay付款功能。

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：簡體中文

信用卡一次付清參數

Redeem String(1)
信用卡是否使用紅利折抵 非必填

設為 Y 時，當綠界特店選擇信用卡付款時，會進入紅利折抵的交易流程。

注意事項：紅利折抵請參考信用卡紅利折抵辦法

UnionPay Int
銀聯卡交易選項 非必填

可帶入以下選項：

0：消費者於交易頁面可選擇是否使用銀聯交易。
1：只使用銀聯卡交易，且綠界會將交易頁面直接導到銀聯網站。
2：不可使用銀聯卡，綠界會將交易頁面隱藏銀聯卡選項。

注意事項：

若需使用銀聯卡服務，請與綠界提出申請方可使用
測試環境提供的驗證URL為綠界模擬測試頁面
不支援信用卡分期付款及定期定額
不支援信用卡紅利折抵
不支援信用卡記憶卡號功能

信用卡記憶卡號參數

BindingCard Int
記憶卡號 非必填

使用記憶信用卡

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

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

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

注意事項：

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

交易流程圖

付款示意圖

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"]
                Redeem:
                  type: string
                  maxLength: 1
                  description: Credit card uses dividend discount
                  example: "Y"
                  enum: ["Y","N"]
                UnionPay:
                  type: integer
                  description: UnionPay Card Transaction Options
                  example: 1
                  enum: [0, 1, 2]
                MerchantMemberID:
                  type: string
                  maxLength: 30
                  description: Credit card uses Merchant MemberID.
                  example: "Y"
                  enum: ["Y","N"]
                BindingCard:
                  type: integer
                  description: Memorize credit card number.
                  example: 0
                  enum: [0, 1]
              required:
                  - MerchantID
                  - MerchantTradeNo
                  - MerchantTradeDate
                  - PaymentType 
                  - TotalAmount 
                  - TradeDesc 
                  - ItemName 
                  - ReturnURL 
                  - ChoosePayment 
                  - CheckMacValue 
                  - EncryptType

綠界官方網站