2. Home
  4. Docs
  6. 授權扣款 Authorized Payment
  8. API列表 (API Lists)
  10. 授權創建 Authorization Binding

授權創建 Authorization Binding

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

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

Method：POST

說明：平台呼叫此API取得街口付款authpay_url，平台授權綁定邊號為唯一值不可重複；當授權綁定未完成前，重複呼叫此API會回覆同一街口綁定網址。

Merchant platform calls this API to obtain JKO’s payment authpay_url. The platform’s authorization binding number is unique and unrepeated. Before an authorization binding is completed, the same authpay_url will be returned when this API is called repeatedly.

整合流程 (Integration Workflow)

User authorization workflow
PC or Tablet
Mobile device

請求參數 (Request Parameter)

參數名稱
Parameter		資料型態
Data Type		最大長度
Maximum		必要的
Required		說明Description
authpay_nameString60Y授權扣款項目Authorization payment name
store_idString36Y商店編號
請依街口提供的測試/正式商店
代碼更新。		Store ID. Please update according to the test and production environment ID provided by JKOPAY.
cancelableBooleanN是否可由用戶解除的授權，
預設為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 String60N平台授扣編號（留存用）Platform’s authorization ID (for record-keeping)
identitiesidentities[]N授扣授權綁定人驗證The ID of the authorized person
billing_amountDecimal20,0Y原始扣款金額Original deduction amount; required for recurring fixed amount payment.
billing_currencyDecimalN原始扣款幣別，預設TWDOriginal currency deducted, default = TWD
billing_cyclebilling_cycle[]Y扣款週期與次數定義，時區限制為UTC+8Original currency deducted, default = TWD
custom_itemscustom_items[]N客製化項目Custom items
result_urlHTTPS URL500Y由平台實作此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_urlHTTP(S) URL500N 由平台實作此客戶端http/s url。
消費者授權同意後，消費者會被導向的平台客戶端結果網頁。		Client http/s url implemented by the platform.
After the user has granted authorization, the user will be directed to the merchant platform’s result page.

範例 (Example)：

{
	"platform_authpay_id": "AUTHPAY_001",
	"authpay_name": "XX Authorized payment", 
	"store_id": "35f12dff-1581-11e9-a054-00505684fd45",
	"result_url": "https://test-platform/authpay/result",
	"result_display_url":"https://platform-dispaly/main",
	"identities": ["X21234xxx"],
	"billing_amount": 1000,
	"billing_currency": "TWD",
	"billing_cycle":{
		"period": "month",
		"times": 2
	},
	"custom_items":[
		{"name":"Premium","value":"Free music listening"}
	]
}

返回參數 (Response JSON Body)

參數名稱
Parameter		資料型態
Data Type		說明Description
auth_noString街口端授權編號JKOPay authorization number
authpay_urlHTTPS URL授權綁定導向網址，街口 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.
qr_imgHTTPS URLQRCode 圖檔，平台可將 QRCode 嵌入平台網頁。QRCode image – an online merchant platform may integrate QRCode image into its own payment flow according to webpage style.
qr_timeouttimestampQRCode/authpay_url 失效時間。回覆的 authpay_url與
QRCode 可在 20 分鐘內使用，只要在 valid_time 期限前
都可使用同筆 auth_no 請求 entry API 更新
QRCode/authpay_url 時限。		QRCode/authpay_url timeout time。
The returned authpay_url and QRCode are valid within 20 minutes. Before valid_time expires, the same auth_no can be used to request entry API again to extend the QRCode/authpay_url timeout duration to another 20 minutes.

範例 (Example)：

{
    "result": "000",
    "message": null,
    "result_object": {
        "auth_no": "650660555924205568",
        "authpay_url": "https://test-onlinepay.jkopay.com/web/authpay/url?j=cDpxcl90aW1lb3V0PTE2MzUyOTcyMjk3MjksYXV0aF9ubz02NTA2NjA1NTU5MjQyMDU1Njg7czo3MWEwYjIyOTkxMDEwZGRkY2FmNThhNDgwYTgxMTQyNzJhYmIzMTU1YWU5ZDJjMDQ5NGNhYjRmNjZhNjY2ODI5",
        "qr_img": "https://test-onlinepay.jkopay.com/web/authpay/qr?j=cDpxcl90aW1lb3V0PTE2MzUyOTcyMjk3MjksdXNlcl90ZXJtaW5hbD1wYyxhdXRoX25vPTY1MDY2MDU1NTkyNDIwNTU2ODtzOjFkYzQ4Y2M4ZTNiZTA3NGI4MGEyMDAzY2ExZWFjZTE1ODAxMTViYmJiY2ZhNGIxZTczNzlhODA0NDRlYmU0YjU%3D",
        "qr_timeout": 1635297229729
    }
}

AuthPay_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 Authorization Binding process is completed and succeeds, JKOPAY Service will callback online merchant platform’s server URL to notify Authorization Binding 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
authpayGrantedAuthPayY授權資料Granted authpay information

範例 (Example)：

{
    "authpay": {
        "type": "regular",
        "auth_no": "591692855148417024",
        "status": "granted",
        "platform_authpay_id": "AUTHPAY_001",
        " jkos_account ": "987654321"

    }
}

HTTP Response

範例 (Example)：

HTTP 200