歐付寶串接教學：超商條碼- 建立訂單 | 金流，電子發票- 歐付寶O'Pay

請商店將網頁表單 POST 傳送至以下的介接網址，以建立「超商條碼」訂單。訂單建立後，歐付寶會回傳一組「繳費條碼」Barcode，消費者列印後，可至超商繳費完成付款。

立即體驗「線上模擬」自訂您的參數、建立超商條碼訂單。

小提醒 ：若是初次串接歐付寶，可先參考「快速串接教學」。

本頁內容

傳送參數建立訂單
範例程式（php、Java、C#、其它語言）
付款圖例
線上模擬

流程簡圖

傳送參數建立訂單[收合]

介接網址：

正式環境： https://payment.opay.tw/Cashier/AioCheckOut/V5

測試環境： https://payment-stage.opay.tw/Cashier/AioCheckOut/V5

請商店將以下參數 POST 傳送至介接網址，以建立超商條碼訂單：

必要參數

參數	說明
MerchantID string (10)	廠商編號 (必要) 註冊歐付寶會員時，歐付寶會提供一組商店代號。
MerchantTradeNo string (20)	商店交易編號 (必要) 商店交易編號不可重複，可英數字大小寫混合。
MerchantTradeDate string (20)	商店交易時間 (必要) 日期時間格式：yyyy/MM/dd HH:mm:ss
TotalAmount int	交易金額 (必要) 純數字格式，無千分位;最低金額限制為30元，最高20000元。
TradeDesc string (200)	交易描述 (必要) 交易的簡易描述。
ItemName string (200)	商品名稱 (必要) 如果商品名稱有多筆，需在金流選擇頁一行一行顯示商品名稱的話，商品名稱請以#號分隔。
ReturnURL string (200)	付款完成通知回傳網址 (必要) 接收歐付寶回傳付款完成通知的網址。
ChoosePayment string (20)	預設付款方式 (必要) 請固定填入"BARCODE"。
PaymentType string (20)	交易類型 (必要) 請固定填入"aio"。 ※如果您使用 php、Java、C#、Ruby on Rails 或 Node.js 的金流整合 SDK 工具包，可略過此參數。
CheckMacValue string (max)	檢查碼 (必要) ※如果您使用 php、Java、C#、Ruby on Rails 或 Node.js 的金流整合 SDK 工具包，可略過此參數。 ※請參考 CheckMacValue 產生步驟。

如果您需要進階的功能，傳送上述必要參數時，可一同傳送以下的選填參數：

選填參數[開啟]

參數	說明
ChooseSubPayment string (20)	預設子付款方式 (選填) 請固定填入"BARCODE"。
PaymentInfoURL string (200)	訂單建立通知回傳網址 (選填) 接收歐付寶回傳訂單建立通知的網址。
ClientBackURL string (200)	Client端返回廠商網址 (選填) 若需於歐付寶的付款完成頁面，顯示[回到廠商]的按鈕，請設定此參數，按鈕會連結至此網址。 ※頁面導回的時候，不會帶付款結果到此網址，僅會將頁面導回。
ItemURL string (200)	商品銷售網址 (選填)
OrderResultURL string (200)	Client端回傳付款結果網址 (選填) 若不使用歐付寶的付款完成頁面，可設定此參數，指定您的付款結果頁。
NeedExtraPaidInfo string (1)	是否需要額外的付款資訊 (選填) 若於付款完成通知及訂單查詢時，需接收「繳費超商」時，請填入"Y"。
DeviceSource string (10)	裝置來源 (選填) 此參數用來設定付款頁面的顯示，預設為空值，由 O'Pay 自動判定。 P：電腦版, M：行動裝置版
PlatformID string (10)	特約合作平台商代號 (選填) 平台商與歐付寶簽約時，歐付寶會提供一組平台商代號。一般商店不用帶此參數。
InvoiceMark string (1)	電子發票開立註記 (選填) 此參數為付款完成後開立電子發票。請參考 InvoiceMark 參數為 Y 所需參數若要開立發票，請將該參數設定為「Y」
HoldTradeAMT int	是否延遲撥款 (選填) 是否延遲撥款。否-請帶0(預設值)，是-請帶1。參數值如下: 0:買方付款完成後，歐付寶依合約約定之時間，撥款給廠商(此為預設值)。 1:買方付款完成後，需再呼叫「廠商申請撥款／退款」API，讓歐付寶撥款給廠商，或退款給買方。倘若廠商一直不申請撥款，此筆訂單款項會一直放在歐付寶，直到廠商申請撥款。 ※延遲撥款不適用「信用卡」、「財付通」之付款方式。
EncryptType int	CheckMacValue 簽章類型 (選填) 請固定帶 1，使用 SHA256 簽章。
UseRedeem string(1)	是否可以使用購物金/紅包折抵 (選填) 用來設定此筆交易是否可以使用購物金/紅包折抵。參數設定： Y：可使用， N：不可使用(預設為N) 註1：折抵方式可於「廠商後台／紅包折抵設定」功能新增您的折抵條件，若已開啟折抵設定，需再配合此參數，來決定此筆交易是否可以使用購物金/紅包折抵。註2：折抵的購物金/紅包金額，需由廠商自行負擔。註3：若可使用購物金/紅包折抵時，需注意接收付款結果通知時，請以TradeAmt做訂單金額的檢查。註4：於V1.1.30新增此欄位。
StoreExpireDate int	超商繳費截止時間(選填) 以天為單位。
ClientRedirectURL string(200)	Client端回傳付款相關資訊 (選填) 此網址為訂單建立完成後(非付款完成後)，歐付寶會將付款相關資訊以Client端方式回傳給特約商店，內容包含繳費銀行代碼、繳費虛擬帳號與繳費期限(yyyy/MM/dd)，沒帶此參數則會顯示歐付寶的訂單成立頁。如果要將訂單成立頁顯示在貴公司，請設定此網址。 ※有設定此參數ClientBackURL參數將會失去作用。

使用 php SDK 範例程式：

小提醒 ：若是初次使用歐付寶 SDK，可參考「下載及使用 SDK 元件」。


/*
 *  產生訂單的範例程式碼。
 */
try
{
    $oPayment = new AllInOne();
    /* 服務參數 */
    $oPayment->ServiceURL ="[您要呼叫的服務位址]";
    $oPayment->HashKey = "[O'Pay提供給您的Hash Key]";
    $oPayment->HashIV = "[O'Pay提供給您的Hash IV]";
    $oPayment->MerchantID ="[O'Pay提供給您的特店編號]";
    /* 基本參數 */
    $oPayment->Send['ReturnURL'] = "[您要收到付款完成通知的伺服器端網址]";
    $oPayment->Send['ClientBackURL'] = "[您要歐付寶返回按鈕導向的瀏覽器端網址]";
    $oPayment->Send['OrderResultURL'] = "[您要收到付款完成通知的瀏覽器端網址]";
    $oPayment->Send['MerchantTradeNo'] = "[您此筆訂單交易編號]";
    $oPayment->Send['MerchantTradeDate'] = date('Y/m/d H:i:s');
    $oPayment->Send['TotalAmount'] = (int) "[您此筆訂單的交易總金額]";
    $oPayment->Send['TradeDesc'] = "[您該筆訂單的描述]";
    $oPayment->Send['ChoosePayment'] = PaymentMethod::Barcode;
    $oPayment->Send['Remark'] = "[您要填寫的其他備註]";
    $oPayment->Send['ChooseSubPayment'] = PaymentMethodItem::None;
    $oPayment->Send['NeedExtraPaidInfo'] = ExtraPaymentInfo::No;
    $oPayment->Send['DeviceSource'] = DeviceType::PC;
    // 加入選購商品資料。
    array_push($oPayment->Send['Items'], array('Name' => "[產品A]", 'Price' => (int)"[單價]",
'Currency' => "[幣別]", 'Quantity' => (int) "[數量]", 'URL' => "[產品說明位址]"));
    array_push($oPayment->Send['Items'], array('Name' => "[產品B]", 'Price' => (int)"[單價]",
'Currency' => "[幣別]", 'Quantity' => (int) "[數量]", 'URL' => "[產品說明位址]"));
    array_push($oPayment->Send['Items'], array('Name' => "[產品C]", 'Price' => (int)"[單價]",
'Currency' => "[幣別]", 'Quantity' => (int) "[數量]", 'URL' => "[產品說明位址]"));
    $oPayment->SendExtend['PaymentInfoURL'] = "[您要收到付款相關資訊的伺服器端網址]";
    /* 產生訂單 */
    $oPayment->CheckOut();
    /* 產生產生訂單 Html Code 的方法 */
    $szHtml = $oPayment->CheckOutString();
}
catch (Exception $e)
{
    // 例外錯誤處理。
    throw $e;
}

使用 Java SDK 範例程式：

小提醒 ：若是初次使用歐付寶 SDK，可參考「下載及使用 SDK 元件」。


/*
 *  產生訂單的範例程式碼。
 */
List<String> enErrors = new ArrayList<String>();
try {
	AllInOne oPayment = new AllInOne();
	
	/* 服務參數 */
	oPayment.ServiceMethod = HttpMethod.HttpPOST;
	oPayment.ServiceURL =  "[您要呼叫的服務位址]";
	oPayment.HashKey = "[O'Pay提供給您的Hash Key]";
	oPayment.HashIV = "[O'Pay提供給您的Hash IV]";
	oPayment.MerchantID = "[O'Pay提供給您的特店編號]";
	
	/* 基本參數 */
	oPayment.Send.ReturnURL = "[您要收到付款完成通知的伺服器端網址]";
	oPayment.Send.ClientBackURL = "[您要歐付寶返回按鈕導向的瀏覽器端網址]";
	oPayment.Send.OrderResultURL = "[您要收到付款完成通知的瀏覽器端網址]";
	oPayment.Send.MerchantTradeNo = "[您此筆訂單交易編號]";
	oPayment.Send.MerchantTradeDate = new Date();//"[您此筆訂單的交易時間]"
	oPayment.Send.TotalAmount = new Decimal("[您此筆訂單的交易總金額]");
	oPayment.Send.TradeDesc = "[您該筆訂單的描述]";
	oPayment.Send.ChoosePayment = PaymentMethod.Barcode;
	oPayment.Send.Remark = "[您要填寫的其他備註]";
	oPayment.Send.ChooseSubPayment = PaymentMethodItem.None;
	oPayment.Send.NeedExtraPaidInfo = ExtraPaymentInfo.No;
	oPayment.Send.DeviceSource = DeviceType.PC;
	
	// 加入選購商品資料。
	Item a1 = new Item();
	a1.Name = "[產品A]";
	a1.Price = new Decimal("[單價]");
	a1.Currency = "[幣別]";
	a1.Quantity = 0;//[數量]
	a1.URL = "[產品說明位址]";
	oPayment.Send.Items.add(a1);
	
	Item a2 = new Item();
	a2.Name = "[產品B]";
	a2.Price = new Decimal("[單價]");
	a2.Currency = "[幣別]";
	a2.Quantity = 0;//[數量]
	a2.URL = "[產品說明位址]";
	oPayment.Send.Items.add(a2);
	
     oPayment.SendExtend.PaymentInfoURL = "[您要收到付款相關資訊的伺服器端網址]";
     oPayment.SendExtend.ClientRedirectURL = "[您要收到(超商)條碼相關資訊的伺服器端網址]";
	/* 產生訂單 */
	enErrors.addAll(oPayment.CheckOut(response.getWriter()));
	/* 產生產生訂單 Html Code 的方法 */
	StringBuilder szHtml = new StringBuilder();
	enErrors.addAll(oPayment.CheckOutString(szHtml));
	
}
catch (Exception e) {
	// 例外錯誤處理。
	enErrors.add(e.getMessage());
}
finally {
	// 顯示錯誤訊息。
	if (enErrors.size() > 0)
		out.print(enErrors);
}

使用 C# SDK 範例程式：

小提醒 ：若是初次使用歐付寶 SDK，可參考「下載及使用 SDK 元件」。


/*
 *  產生訂單的範例程式碼。
 */
List<string> enErrors = new List<string>();

try
{
    using (AllInOne oPayment = new AllInOne())
    {
        /* 服務參數 */
        oPayment.ServiceMethod = HttpMethod.HttpPOST;
        oPayment.ServiceURL = "[您要呼叫的服務位址]";
        oPayment.HashKey = "[O'Pay提供給您的Hash Key]";
        oPayment.HashIV = "[O'Pay提供給您的Hash IV]";
        oPayment.MerchantID = "[O'Pay提供給您的特店編號]";
        /* 基本參數 */
        oPayment.Send.ReturnURL = "[您要收到付款完成通知的伺服器端網址]";
        oPayment.Send.ClientBackURL = "[您要歐付寶返回按鈕導向的瀏覽器端網址]";
        oPayment.Send.OrderResultURL = "[您要收到付款完成通知的瀏覽器端網址]";
        oPayment.Send.MerchantTradeNo = "[您此筆訂單交易編號]";
        oPayment.Send.MerchantTradeDate = DateTime.Parse("[您此筆訂單的交易時間]");
        oPayment.Send.TotalAmount = Decimal.Parse("[您此筆訂單的交易總金額]");
        oPayment.Send.TradeDesc = "[您該筆訂單的描述]";
        oPayment.Send.ChoosePayment = PaymentMethod.Barcode; 
        oPayment.Send.Remark = "[您要填寫的其他備註]";
        oPayment.Send.ChooseSubPayment = PaymentMethodItem.None;
        oPayment.Send.NeedExtraPaidInfo = ExtraPaymentInfo.Yes;
        oPayment.Send.HoldTrade = HoldTradeType.No;
        oPayment.Send.DeviceSource = DeviceType.PC;
        // 加入選購商品資料。
        oPayment.Send.Items.Add(new Item() { Name = "[產品A]", Price = Decimal.Parse("[單價]"), Currency = "[幣別]", Quantity = Int32.Parse("[數量]"), URL = "[產品說明位址]" });
        oPayment.Send.Items.Add(new Item() { Name = "[產品B]", Price = Decimal.Parse("[單價]"), Currency = "[幣別]", Quantity = Int32.Parse("[數量]"), URL = "[產品說明位址]" });
        oPayment.Send.Items.Add(new Item() { Name = "[產品C]", Price = Decimal.Parse("[單價]"), Currency = "[幣別]", Quantity = Int32.Parse("[數量]"), URL = "[產品說明位址]" });

        oPayment.SendExtend.PaymentInfoURL = "[您要收到付款相關資訊的伺服器端網址]";
        oPayment.SendExtend.ClientRedirectURL = "[您要收到(超商)條碼相關資訊的伺服器端網址]";
        /* 產生訂單 */
        enErrors.AddRange(oPayment.CheckOut());
    }
}
catch (Exception ex)
{
    // 例外錯誤處理。
    enErrors.Add(ex.Message);
}
finally
{
    // 顯示錯誤訊息。
    if (enErrors.Count() > 0)
    {
        string szErrorMessage = String.Join("\\r\\n", enErrors);
    }
}

其它程式語言，可點此下載參考範例程式（php、C#），請參考前述建立訂單的參數，串接歐付寶的 API。

付款圖例[收合]

付款流程示例：

超商條碼付款流程

線上模擬[收合]

可於下方自訂您的訂單參數，點擊按鈕，開始建立訂單：

自訂您的參數

參數
MerchantID (必要) 商店代號 string (10)
MerchantTradeNo (必要) 商店交易編號 string (20)
MerchantTradeDate (必要) 商店交易時間 string (20)
PaymentType (必要) 交易類型 string (20)
TotalAmount (必要) 交易金額 int
TradeDesc (必要) 交易描述 string (200)
ItemName (必要) 商品名稱 string (200)
ReturnURL (必要) 付款完成通知回傳網址 string (200)
ChoosePayment (必要) 預設付款方式 string (20)
ChooseSubPayment (選填) 預設子付款方式 string (20)
ClientBackURL (選填) Client端返回廠商網址 string (200)
CheckMacValue 檢查碼 string (max) ※ 請見 CheckMacValue 產生步驟

網頁原始碼（點此複製，以建立訂單）


<form id="formBarcode" method="post" accept-charset="UTF-8"
 action="https://payment-stage.opay.tw/Cashier/AioCheckOut/V5">

MerchantID 商店代號: 
<input type="text" name="MerchantID" value="" /><br />
MerchantTradeNo 商店交易編號: 
<input type="text" name="MerchantTradeNo" value="" /><br />
MerchantTradeDate 商店交易時間: 
<input type="text" name="MerchantTradeDate" value="" /><br />
PaymentType 交易類型: 
<input type="text" name="PaymentType" value="" /><br />
TotalAmount 交易金額: 
<input type="text" name="TotalAmount" value="" /><br />
TradeDesc 交易描述: 
<input type="text" name="TradeDesc" value="" /><br />
ItemName 商品名稱: 
<input type="text" name="ItemName" value="" /><br />
ReturnURL 付款完成通知回傳網址: 
<input type="text" name="ReturnURL" value="" /><br />
ChoosePayment 預設付款方式: 
<input type="text" name="ChoosePayment" value="" /><br />
ChooseSubPayment 預設子付款方式: 
<input type="text" name="ChooseSubPayment" value="" /><br />
ClientBackURL Client端返回廠商網址: 
<input type="text" name="ClientBackURL" value="" /><br />
CheckMacValue 檢查碼: 
<input type="text" name="CheckMacValue" value="" /><br />
<input type="submit" value="送出訂單" />

</form>

CheckMacValue 產生步驟[收合]

如果您使用 php、Java 或 C# 的金流整合 SDK 工具包，可略過此步驟。

CheckMacValue（檢查碼）用來確保訂單的資訊安全，您的 HashKey 與 HashIV 金鑰請參考「取得串接資訊」。

請小心 ：為避免網頁前端洩漏您的 HashKey、HashIV 金鑰，請於伺服器端產生 CheckMacValue。

Step. 1　先依參數名稱之字順（由 A 至 Z）排序各組參數，用「參數名稱＝參數值」形式，以 & 符號相連：

Step. 2　最前面加上您的 HashKey、最後面加上您的 HashIV：

Step. 3　以 UTF-8 的編碼 UrlEncode：

Step. 4　轉為小寫：

Step. 5　由於 UrlEncode 的結果可能不同，請依照 UrlEncode對照表取代 UrlEncode 的結果，以和歐付寶(IIS+.NET) UrlEncode 的結果一致：

以 php 為例：php urlencode 函式會將「!」轉為「%21」，這和歐付寶(IIS+.NET) UrlEncode 的結果不同，為了 UrlEncode 的結果一致，請依照 UrlEncode對照表，使用 str_replace 函式將結果「%21」取代為「!」，php 程式如下：


$sMacValue = str_replace('%2d', '-', $sMacValue);
$sMacValue = str_replace('%5f', '_', $sMacValue);
$sMacValue = str_replace('%2e', '.', $sMacValue);
$sMacValue = str_replace('%21', '!', $sMacValue);
$sMacValue = str_replace('%2a', '*', $sMacValue);
$sMacValue = str_replace('%28', '(', $sMacValue);
$sMacValue = str_replace('%29', ')', $sMacValue);

UrlEncode 對照表[開啟]

符號	歐付寶(IIS+.NET) UrlEncode
-	-
_	_
.	.
!	!
~	%7e
*	*
(	(
)	)
space 空格	+
@	40%
#	23%
$	24%
%	25%
^	%5e
&	26%
=	%3d
+	%2b
;	%3b
?	%3f
/	%2f
\	%5c
>	%3e
<	%3c
%	25%
`	60%
[	%5b
]	%5d
{	%7b
}	%7d
:	%3a
'	27%
"	22%
,	%2c
\|	%7c

Step. 6　轉為 SHA256 雜湊，並轉為大寫，即成功產生 CheckMacValue：

　下一頁：歐付寶回傳建立訂單結果