全方位金流API技術文件

付款方式 / 信用卡分期付款

應用場景

當特店提供消費者在綠界付款頁面使用信用卡分期付款交易時。

  • 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，用來接收綠界後端回傳的付款結果通知。
  • 當消費者付款完成後，綠界會將付款結果參數以幕後回傳到該網址。詳細說明請參考付款結果通知

❗ 注意事項：

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

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

綠界提供下列付款方式：

  • Credit：信用卡

CheckMacValue String
檢查碼 必填

請參考檢查碼機制

EncryptType Int
CheckMacValue加密類型 必填

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

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

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

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

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

❗ 注意事項：

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

ItemURLString(200)
商品銷售網址

Remark String(100)
備註欄位

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

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

❗ 注意事項：

  1. 若與[ClientBackURL]同時設定，將會以此參數為主。
  2. 銀聯卡及非即時交易( ATM、CVS、BARCODE )不支援此參數。
  3. 付款結果通知請依ReturnURL (server端的網址)為主,避免因前端操作或網路問題未收到OrderResultURL 特店的client端(前端)的通知。
  4. 參數內容若有包含%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：簡體中文

信用卡分期付款參數

CreditInstallment String(20)
刷卡分期期數 

提供刷卡分期期數

  • 一般分期：可用參數為：3,6,12,18,24
  • 圓夢彈性分期：可用參數為: 30N，交易金額須大於圓夢彈性分期最低交易金額，最低交易金額可於廠商後台查詢

❗ 注意事項：

  1. 使用的期數必須先透過申請開通後方能使用，並以申請開通的期數為主。
  2. 不可以與信用卡定期定額、紅利折抵參數一起設定。
  3. 若使用分期付款功能，後續分期的款項會由銀行執行確認，相關銀行可使用分期期數請參考銀行分期期數。
  4. 欲在測試環境進行刷卡功能，請使用綠界提供的信用卡測試卡號進行模擬付款。
  5. 串接時請帶訂單的刷卡分期的總付款金額，無須自行計算各分期金額，除不盡的金額銀行會於第一期收取。舉例：總金額 1733元 分 6 期，除不盡的放第一期，293，288，288，288，288，288。
  6. 銀聯卡不支援分期付款方式。
  7. 若廠商未開通刷卡分期期數時，交易會自動改為信用卡一次付清。

信用卡記憶卡號參數

BindingCard Int
記憶卡號 非必填

使用記憶信用卡

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

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

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

❗ 注意事項：

  1. 「欲使用 BindingCard、MerchantMemberID 這兩個參數功能，特店必須有會員系統。」
  2.  若記憶卡號識別碼為平台商的會員識別碼時，要特別向綠界申請使用。
  3.  記憶卡號功能僅支援 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: "All"
                  enum: ["All"]
                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"]
                CreditInstallment :
                  type: string
                  maxLength: 20
                  description: Credit card Installment
                  example: "3,6"
                
              required:
                  - MerchantID
                  - MerchantTradeNo
                  - MerchantTradeDate
                  - PaymentType 
                  - TotalAmount 
                  - TradeDesc 
                  - ItemName 
                  - ReturnURL 
                  - ChoosePayment 
                  - CheckMacValue 
                  - EncryptType

Copyright © Green World FinTech Service Co., Ltd. All rights reserved.

綠界官方網站