授權創建 Authorization Binding

授權扣款:
定期定額 (Authorized Payment-regular)
不定期不定額 (Authorized Payment-limited)

說明：
平台依照需求擇一呼叫API取得街口付款的URL(authpay_url)等資訊

注意事項：
1. 平台授權綁定編號為唯一值不可重複
2. 當授權綁定未完成前，重複呼叫此API會回覆同一街口綁定網址
3. 定期定額API與不定期不定額API Request/Response規格相同

請求參數 (Request Parameter)

參數名稱 Parameter	資料型態 Data Type	最大長度 Maximum	必要的 Required	說明	Description
authpay_name	string	60	Y	授權扣款項目	Authorization payment name.
store_id	string	36	Y	商店編號 請依街口提供的測試/正式商店 代碼更新。	Store ID. Please update according to the test and production environment ID provided by JKOPAY.
cancelable	bool		N	是否可由用戶解除的授權， 預設為true,可由用戶解除。	Whether the authorization binding can be canceled by the user. Default set as true, which means the authorization can be canceled by the user.
platform_authpay_id	string	60	N	平台授扣編號（留存用）	Platform’s authorization ID (for record-keeping).
identities	string[]		N	授扣授權綁定人驗證	The ID of the authorized person.
billing_amount	decimal	20,0	Y	原始扣款金額	Original deduction amount; required for recurring fixed amount payment.
billing_currency	string		N	原始扣款幣別，預設TWD	Original currency deducted, default = TWD.
billing_cycle fields			定期定額: Y 不定期不定額: N	定期定額扣款週期與次數定義	Deduction cycle and times (For type is regular).
billing_cycle.period	string			扣款週期，時區限制為UTC+8，限帶入以下字串(e.g.week) week: 週（Sun～Mon） month: 月 quarter: 季 year: 年	Deduction cycle period, timezone is UTC+8, and input the following string only (e.g.week) week: (from Sunday to Monday). month quarter year
billing_cycle.times	int			每週期內，扣款次數。 （限帶入整數，如未帶此參數，系統預設為1次） Week <= 7次 Month <= 7次 Quarter <= 7次 Year <= 12次	The deduction time in regular period (input int only, default = 1). If the period is a week, then the times-limit <= 7 If the period is a month, then the times-limit <= 7 If period is a quarter, then the times-limit <= 7 If the period is a year, then the times-limit <= 12
result_url	string	500	Y	由平台實作此callback URL ( 必須 https )。 消費者綁定完成後，街口服務器訪問此平台服務器網址，並在參數中提供授扣編號與綁定交易狀態代碼。	Callback URL (https) implemented by the merchant platform. After the user has completed authorization binding, JKO calls the platform’s server and provides the authorization ID and binding status code.
result_display_url	string	500	N	由平台實作此客戶端 ( 可以是 http/https url )。 消費者授權同意後，消費者會被導向的平台客戶端結果網頁。	Client http/https url implemented by the platform. After the user has granted authorization, the user will be directed to the merchant platform’s result page.
custom_items fields			N
custom_items.name	string			客製化項目名	Custom items’ name.
custom_items.value	string			客製化項目內容	The description of custom items.

範例 (Example)：

定期定額 regular API Request：

POST https://{街口路徑}/platform/authpay/regular
Content-Type: application/json
api-key: 054e3b308708370ea029dc2ebd1646c498d59d7203c9e1a44cf0484df98e581a
digest: e5efae3b79817a2469df9403ae7b8ef3b67feafe414b8a4837c10712ace8629e

{
  "authpay_name": "regular authorized payment",
  "store_id": "35f12dff-1581-11e9-a054-00505684fd45",
  "platform_authpay_id": "authpay_001",
  "billing_amount": 1000,
  "billing_currency": "TWD",
  "result_url": "https://test-platform/authpay/result",
  "billing_cycle": {
    "period": "month",
    "times": 2
  }
}

不定期不定額 limited API Request：

POST https://{街口路徑}/platform/authpay/limited
Content-Type: application/json
api-key: 28c42b4854360183b2ffa2e0d116026de7aa5deeaeed24eb0cd11c38a6e3c3c4
digest: a10901aa0a69a3fdafe517794ca2cd552490aabe856f1a5e2590175c02066f97

{
  "authpay_name": "limited authorized payment",
  "store_id": "8a392ff5-69c4-11ef-94d5-005056b665e9",
  "platform_authpay_id": "authpay_002",
  "result_url": "https://test-platform/authpay/result"
}

返回參數 (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 fields
result_object.auth_no	string	街口端授權編號	JKOPay authorization number.
result_object.authpay_url	string	授權綁定導向網址，街口 Server 判斷 : – 電腦或平板網頁交易環境，提供街口付款QRCode導向網址。 – 行動裝置支付環境，從消費者手機重新導向到街口App付款頁面。	Authorization binding URL where users will be directed to. JKO Server will systematically determine whether the user is on : — Personal computer or notebook device payment environment, will provide 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 – an online merchant platform may integrate QRCode image into its own payment flow according to web page style.
result_object.qr_timeout	timestamp	QRCode/authpay_url 失效時間。回覆的 authpay_url與 QRCode 可在 20 分鐘內使用。	QRCode/authpay_url timeout time. The returned authpay_url and QRCode are valid within 20 minutes.

範例 (Example)：

成功 success response：

{
  "result": "000",
  "message": null,
  "result_object": {
    "auth_no": "650660555924205568",
    "authpay_url": "https://test-authpay.jkopay.app/web/authpay/url?j=cDpxcl90aW1lb3V0PTE2MzUyOTcyMjk3MjksYXV0aF9ubz02NTA2NjA1NTU5MjQyMDU1Njg7czo3MWEwYjIyOTkxMDEwZGRkY2FmNThhNDgwYTgxMTQyNzJhYmIzMTU1YWU5ZDJjMDQ5NGNhYjRmNjZhNjY2ODI5",
    "qr_img": "https://test-authpay.jkopay.app/web/authpay/url?j=cDpxcl90aW1lb3V0PTE2MzUyOTcyMjk3MjksYXV0aF9ubz02NTA2NjA1NTU5MjQyMDU1Njg7czo3MWEwYjIyOTkxMDEwZGRkY2FmNThhNDgwYTgxMTQyNzJhYmIzMTU1YWU5ZDJjMDQ5NGNhYjRmNjZhNjY2ODI5",
    "qr_timeout": 1635297229729
  }
}

失敗 failure response：

{
  "result": "200",
  "message": "Bad request",
  "result_object": null
}