授權扣款 Authorization deduction request
授權扣款 transaction API
Method：POST
Domain：https://[Host]/platform/authpay/transaction
說明：
電商平台呼叫此API，發動該筆平台授權序號的授權扣款。
請求參數 (Request Parameter)
| 參數名稱 Parameter | 資料型態 Data Type | 最大長度 Maximum | 必要的 Required | 說明 | Description |
|---|---|---|---|---|---|
| auth_no | String | 30 | Y | 街口端授權編號 | Jkopay authorization number |
| order | AuthOrderUnit | Y | AuthOrderUnit |
AuthOrderUnit
| 參數名稱 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. |
| trade_name | String | 30 | Y | 交易名稱 （會顯示於app中授權交易記錄頁） | Transaction name (shown in the authorization record page in the JKOPay app) |
| currency | String | 3 | Y | 原始幣別 [ISO 4217] | Original currency [ISO 4217] |
| total_price | Decimal | 18,0 | Y | 訂單價格（原始幣別） | Total price (original currency) |
| final_price | Decimal | 18,0 | Y | 訂單應付價格（原始幣別） | Final price would be paid (original currency) |
| unredeem | Decimal | N | 訂單不可折抵回饋金額（原始幣別） 預設為0 | The amount that cannot be discounted or not qualified for reward (original currency) Default = 0 | |
| products | Product[] | N | 商品資訊 | Product information | |
| remark | String | 500 | N | 備註 | Memo |
Products
| 參數名稱 Parameter | 資料型態 Data Type | 最大長度 Maximum | 必要的 Required | 說明 | Description |
|---|---|---|---|---|---|
| name | String | 60 | N | 商品名稱（charset=utf-8） | |
| img | String | 500 | N | 商品網址 | |
| unit_count | Int | N | 商品數量 | ||
| unit_price | Decimal | 18,0 | N | 商品單價（原價） | |
| unit_final_price | Decimal | 18,0 | N | 商品單價（付款價格） | |
| category_path | List<string> | N |
返回參數 (Response JSON Body)
| 參數名稱 Parameter | 資料型態 Data Type | 最大長度 Maximum | 必要的 Required | 說明 | Description |
|---|---|---|---|---|---|
| result | String | Y | 回覆結果 | ||
| message | String | Y | 回覆訊息 (扣款金額驗證失敗時會提供error message) | ||
| result_object | Object (result_object) | N | 回覆物件 (成功才會有) |
result_object
| 參數名稱 Parameter | 資料型態 Data Type | 說明 | Description |
|---|---|---|---|
| result_object | Transaction | Transaction |
Transaction
| 參數名稱 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. |
| status | int | Y | （Status非0時，以下欄位不回覆） | (When the status does not equal 0, the following parameters will not be returned) | |
| tradeNo | String | 25 | Y | 街口端交易序號 | JKOPay transaction number |
| trans_time | String | Y | 交易時間 YYYY-mm-dd HH:MM:SS | Transaction time YYYY-mm-dd HH:MM:SS | |
| currency | String | 3 | Y | 原始幣別 [ISO 4217]（TWD） | Currency [ISO 4217]（TWD） |
| final_price | Decimal | 18,0 | Y | 訂單應付價格（原始幣別） | The final price would be paid (original currency) |
| redeem_amount | Decimal | 18,0 | Y | 折抵金額=街口幣折抵+官方街口券折抵+店家街口券折抵 | Discounted amount = amount of JKO coin + JKO official coupon + store coupon |
| redeem_detail | RedeemDetail[] | Y | |||
| debit_amount | Decimal | 18,0 | Y | 付款方式扣款金額（折抵後金額） | Amount paid (after discount) |
| refund_history | RefundTransaction[] | Y | |||
| invoice_vehicle | String | 20 | Y | 街口帳戶發票載具 | Jkopay account invoice carrier |
| maskNo | String | 16 | N | 付款工具使用信用卡時提供卡號前六後四碼 格式：222222******3333 | When channel_type is “credit card” then the JKOPay server will reply with the card number(The first six numbers and last four numbers) Format: 222222******3333 |
| channel_type | String | Y | 支付工具 account: 儲值帳戶 bank: 銀行帳戶 creditcard: 信用卡 | User’s payment method account: JKOPay balance bank: bank account creditcard: credit card (not available for crossborder payment) |
RefundTransaction
| 參數名稱 Parameter | 資料型態 Data Type | 最大長度 Maximum | 必要的 Required | 說明 | Description |
|---|---|---|---|---|---|
| refund_tradeNo | String | 25 | Y | 街口端退款交易序號 | Jkopay refund transaction number |
| amount | Decimal | 18,0 | Y | 退款金額 | Refund amount |
| redeem_amount | Decimal | 18,0 | Y | 退還折抵金額 | Amount redeemed |
| redeem_detail | RedeemDetail | Y | |||
| debit_amount | Decimal | 18,0 | Y | 消費者付款方式退款金額 | Amount refunded to the user’s payment method |
| time | String | Y | 退款時間(UTC+8) YYYY-mm-dd HH:MM:SS | Refund time YYYY-mm-dd HH:MM:SS |
RedeemDetail
| 參數名稱 Parameter | 資料型態 Data Type | 最大長度 Maximum | 必要的 Required | 說明 | Description |
|---|---|---|---|---|---|
| jko_coin_amount | Decimal | 18,0 | Y | 街口幣折抵金額 | JKO coin redeem amount |
| official_coupon_amount | Decimal | 20,0 | Y | 官方街口券折抵金額 | official coupon redeem amount |
| store_coupon_amount | Decimal | 20,0 | Y | 店家街口券折抵金額 | store coupon redeem amount |
範例 (Example)：
授權扣款 transaction API Request：
{
"auth_no": "605495635344494592",
"order": {
"platform_order_id": "test-roy-010",
"trade_name":"第X次扣款",
"currency": "TWD",
"total_price": 50,
"final_price": 50,
"unredeem": 0,
"products": [{
"name": "商品1",
"img": null,
"unit_count": 1,
"unit_price": 50,
"unit_final_price": 50,
"category_path": []}],
"remark": "備註"
}
}
授權扣款 transaction API Response (成功)：
{
"result": "000",
"message": null,
"result_object": {
"platform_order_id": "67ada7353b123",
"status": 0,
"tradeNo": "J0153402025021300123",
"trans_time": "2025-02-13 16:03:01",
"currency": "TWD",
"final_price": 225,
"redeem_amount": 0,
"redeem_detail": {
"jko_coin_amount": 0,
"official_coupon_amount": 0,
"store_coupon_amount": 0
},
"debit_amount": 225,
"refund_history": null,
"invoice_vehicle": "/JURT123",
"remain_JKO_fee": 0,
"maskNo": null,
"channel_type": "creditcard",
"re": 0,
"netPaid": 0,
"transaction_seq": null
}
}
授權扣款 transaction API Response (失敗)：
{
"result": "121",
"message": "Insufficient bank account balance.",
"result_object": null
}