訂單創建 Entry API

Domain：https://{Please update according to test/production path provided by JKOPAY}/platform/entry

Method：POST

說明：電商平台呼叫此 API 取得街口付款 payment_url，電商平台交易序號
為唯一值不可重複；當訂單付款未完成前，重複呼叫此 API 會回覆
同一街口付款網址。

Online merchant platform calls this API to obtain JKOPAY payment_url. Online merchant platform order ID is unique and cannot be repeated. Before a payment is completed, the same payment URL is returned every time this API is called.

整合流程 (Integration Workflow)

請求參數 (Request Parameter)

參數名稱 Parameter	資料型態 Data Type	最大長度 Maximum	必要的 Required	說明	Description
platform_order_id	String	60	Y	電商平台端交易序號 需為唯一值，不可重複。	The ID of the order is saved on the platform. This ID needs to be unique and unrepeated.
store_id	String	36	Y	商店編號 請依街口提供的測試/正式商店 代碼更新。	Store ID. Please update according to the test and production environment ID provided by JKOPAY.
currency	String	3	Y	付款貨幣[ISO 4217]，請帶入 TWD。	Platform’s order currency [ISO 4217].
total_price	decimal	20,0	Y	訂單原始金額。	Original price with order currency.
final_price	decimal	20,0	Y	訂單實際消費金額。	Final price with order currency.
unredeem	decimal	20,0	Y	不可折抵金額。	Unredeemed amount(Consumer can’t pay in JKO coins & JKO ticket).
valid_time	String	19	N	訂單有效期限，依 UTC+8 時 區。 格式 : YYYY-mm-dd HH:MM:SS	Valid time of order in UTC+8 time zone. User can only complete the transaction within the time limitation. Format : YYYY-mm-dd HH:MM:SS
confirm_url	String	500	N	由商家實作此callback URL (https)。 買家在街口確認付款頁面輸入 密碼後，街口服務器訪問此電 商平台服務器網址確認訂單正 確性與存貨彈性。	Optional for platform to implement the callback URL. After user enters passcode inside JKOPAY app’s payment page, JKOPAY server will access platform’s server URL to confirm the order accuracy and inventory availability.
result_url	String	500	Y	由電商平台實作此callback URL (https)。 消費者付款完成後，街口服務 器訪問此電商平台服務器網 址，並在參數中提供街口交易 序號與訂單交易狀態代碼。	When user completes a payment, JKOPAY server will callback platform’s server URL and provide JKOPAY transaction record
result_display_url	String	500	N	由電商平台實作此客戶端http/s url。 消費者付款完成後點選完成按 鈕，將消費者導向此電商平台 客戶端付款結果頁網址。	For platform to implement client side http/s URL. When User selects the ‘complete’ button in app after completing payment, JKOPAY app will direct user to online platform’s client side web page where the payment result is displayed.
payment_type	String		N	付款模式 : “onetime”為一次性 付款，”regular”為定期定額付 款；預設為一次性付款。
escrow	Bool		N	是否支持價金保管，預設為 False 不支持。
products fields				支援 JSON/String 格式，陣列 帶入以下資訊。 當使用 products 欄位時，則除 了 products.img 其餘皆為必要 欄位。	Supports JSON/Strong format; use product array to insert these attributes. Necessary attributes for currency exchange declaration.
products.name	String	60	N	商品名稱（charset=utf-8）	Product name(charset=utf-8)
products.img	String	500	N	商品網址	Product’s image URL.
products.unit_count	int		N	商品數量	Quantity of product.
products.unit_price	decimal	20,0	N	商品單價（原價）	Original price with order currency per unit.
products.unit_final_price	decimal	20,0	N	商品單價（付款價格）	Final price with order currency per unit.

範例 (Example)：

POST https://{街口路徑}/platform/entry
Content-Type: application/json
API-KEY: 4h0Ms
DIGEST: fd9f2e875a9a3baa1daf082fd137b8ae81d7b483f6a701a5aeb1c843cea30c68

{"store_id": "d7120db2-8c76-4124-bf08-02e5b775d8fe", "platform_order_id": 87, "currency": "TWD", 
"total_price": 1000, "final_price": 1000, "escrow": false, "payment_type": "onetime"}   

返回參數 (Response JSON Body)

參數名稱 Parameter	資料型態 Data Type	說明	Description
result	String	請參照 API 回覆代碼（ResponseCode）。	Please refer to API response code(responseCode).
message	String	結果訊息或失敗理由。	Result message or reason of error.
result_object.payment_url	String	付款導向網址，街口 Server 判斷 : – 電腦或平板網頁交易環境，提供街口付款QRCode導向網址。Web 串接說明 – 行動裝置支付環境，從消費者手機重新導向到街口App付款頁面。App 串接說明	Payment direct URL，JKOPAY Server determines : — Personal computer or notebook device payment environment, will provides JKOPAY payment QRCode web URL. — Mobile device payment environment and directs users to JKOPAY app’s payment interface.
result_object.qr_img	String	QRCode 圖檔，電商平台可將 QRCode 嵌入付款網頁。	QRCode image – online merchant platform may integrate QRCode image into his own payment flow according to webpage stype.
result_object.qr_timeout	timestamp	QRCode/payment_url 失效時間。回覆的 payment_url 與 QRCode 可在 20 分鐘內使用，只要在 valid_time 期限前 都可使用同筆 platform_order_id 請求 entry API 更新 QRCode/payment_url 時限。	QRCode/payment_url timeout time。 The returned payment_url and QRCode is valid within 20 minutes. Before valid_time expires, the same platform_order_id can be used to request entry API again to extend QRCode/payment_url timeout duration another 20 minutes.

範例 (Example)：

{
 "result": 000,
 "message": null,
 "result_object": {
 "payment_url": "https://test-onlinepay.jkopay.com/web/paymentUrl?xxxx"
 "qr_img": "https://test-onlinepay.jkopay.com/web/qr?xxxx",
 "qr_timeout": 1528447912
 }
}  

confirm_url 實作規格

Method：POST

說明：非必要電商平台實作功能；為確保付款時訂單正確性與付款彈性，在執行付款流程前，街口 Server callback 此電商平台 Server url 確認訂單，回覆正確後才會執行付款流程。

連線規則：Connection timeout 5 秒，Read timeout 10 秒，Retry 3 次

Optional for merchant；to ensure the accuracy of payment and flexibility of payment process, JKOPAY Server will callback online merchant platform’s Server URL to confirm order before executing payment process. Payment process continues only when confirmation is received.

Connection timeout: 5 seconds
Read timeout: 10 seconds
Retry: 3 times

請求參數 (Request Parameter)

範例 (Example)：

參數名稱 Parameter	資料型態 Data Type	最大長度 Maximum	必要的 Required	說明	Description
platform_order_id	String	60	Y	電商平台端交易序號	Online merchant platform order ID

{
 “platform_order_id”: 87
}

返回參數 (Response JSON Body)

參數名稱 Parameter	資料型態 Data Type	說明	Description
valid	bool	回覆訂單是否可以允許扣款	Response “true” value once order pass the validation.

範例 (Example)：

{
 "valid": true
}

result_url 實作規格

Method：POST

說明：電商平台實作功能；當付款流程結束且交易成功時，街口服務端 callback 此電商平台 Server url 通知交易結果。

連線規則：Connection timeout 5 秒，Read timeout 10 秒，每間隔 2^指數時間(秒數)Retry，最多 12 次，約在 2 小時內完成。舉例說明 callback 失敗後，間隔 1 秒後第一次Retry，如果失敗再間隔 2 秒第二次 Retry，如果失敗再間隔 4 秒第三次 Retry 依此類推。

When payment process is completed and transaction succeeds, JKOPAY Service will callback online merchant platform’s server URL to notify transaction result.

Connection timeout: 5 seconds
Read timeout: 10 seconds
Retry 12 times. Will try again with 2^ error times as time interval.

請求參數 (Request Parameter)

參數名稱 Parameter	資料型態 Data Type	最大長度 Maximum	必要的 Required	說明	Description
platform_order_id	String	60	Y	電商平台端交易序號	ID of order saved in the platform.
status	Int		Y	請參照 OrderStatusCode	Please refer to orderStatusCode.
tradeNo	String	25	Y	街口端交易序號	JKOPAY trade number.
trans_time	String		Y	交易時間	Time of transaction in UTC+8 time zone. Format: YYYY-mm-dd HH:MM:SS
currency	String	3	Y	付款貨幣[ISO 4217]，請帶入 TWD。	Payment currency [ISO 4217].
final_price	decimal	20	Y	訂單實際消費金額。	Final price of order with payment currency.
redeem_amount	decimal	20	Y	折抵金額=街口幣折抵+官方街口 券折抵+店家街口券折抵	Redeemed amount(JKO coins & JKO ticket).
redeem_detail	RedeemDyail
redeem_detail.jko_coin_amount	decimal	18	Y	街口幣折抵	JKO coin redeem amount
redeem_detail.official_coupon_amount	decimal	18	Y	官方街口券折抵	Official coupon redeem amount
redeem_detail. store_coupon_amount	decimal	18	Y	店家街口券折抵	Store coupon redeem amount
debit_amount	decimal	20	Y	付款方式扣款金額（折抵後金 額）	Payment method debit amount (after deduct JKO coins) with payment currecny. (final_price = redeem_amount + debit_amount)
invoice_vehicle	String	20	N	街口帳戶發票載具
maskNo	String	16	N	付款工具使用信用卡時提供卡號 前六後四碼 格式：222222******3333
channel_type	String		Y	支付工具 “account”: 儲值帳戶 “bank”: 銀行帳戶 “creditcard”: 信用卡	Pay tool account : JKOPay account bank : bank account credicard

範例 (Example)：

{
 "transaction": {
 "platform_order_id": 87,
 "status": 0,
"tradeNo": "J0026910118070413C4",
"trans_time": "2018-07-01 12:00:00",
"final_price": "1000",
"redeem_amount": "300",
"redeem_detail": {
 "jko_coin_amount": 200,
"official_coupon_amount": 0,
"store_coupon_amount": 100,
},
"debit_amount": "700"
}
}

HTTP Response

範例 (Example)：

HTTP 200