應用場景
當特店提供消費者在綠界付款頁面使用WebATM交易時。
- Step 1. 特店：將 ChoosePayment 選擇預設付款方式設定為WebATM。
- 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
特店傳入參數說明(共同參數)
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)
選擇預設付款方式 必填
綠界提供下列付款方式：
- WebATM：網路ATM
注意事項：
- 若為手機版時不支援下列付款方式：WebATM
- 如需要不透過綠界畫面取得ATM、CVS、BARCODE的繳費代碼，請參考如何不經過綠界畫面取得ATM、CVS、BARCODE的繳費代碼。
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)
備註欄位
ChooseSubPayment String(20)
付款子項目
若設定此參數，建立訂單將轉導至綠界訂單成立頁，依設定的付款方式及付款子項目帶入訂單，無法選擇其他付款子項目。請參考付款方式一覽表
注意事項：因板信銀行會於每月進行例行維護，當遇銀行維護時，將會建立訂單失敗。
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：簡體中文
交易流程圖
付款示意圖
選擇WebATM銀行畫面
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: "WebATM"
enum: ["WebATM"]
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"]
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"]
required:
- MerchantID
- MerchantTradeNo
- MerchantTradeDate
- PaymentType
- TotalAmount
- TradeDesc
- ItemName
- ReturnURL
- ChoosePayment
- CheckMacValue
- EncryptType