街口幣發放 Issue JKOS Coins

URL: https://{baseURL}/jkocoin/exchange

Method: POST

說明：外部平台呼叫此 API 來發放街口幣給指定用戶；若帶入相同 exchangeId 重複呼叫此 API 會回覆同筆訂單結果。
The external platform calls this API to issue JKOS Coins to a specified user. If the same exchangeId is provided in repeated calls, the API will return the same order result.

整合流程 (Integration Workflow)

請求參數 (Request Parameter)

Request Header

參數名稱 Parameter	資料型態 Data Type	必要的 Required	說明	Description
Content-Type	string	Y	“*application/json*“	“application/json“
Api-Key	string	Y	帶入街口提供的 API Key	API key provided by Jkopay.
Digest	string	Y	加簽加密說明 (Signature Generation Rule)	Generating the digest

Request Body

參數名稱 Parameter	資料型態 Data Type	最大長度 Maximum	必要的 Required	說明	Description
clientId	string	100	Y	呼叫端識別碼（由街口提供）	Client iIdentifier provided by Jkopay.
exchangeId	string	64	Y	交易唯一識別碼（需為唯一值，不可重複）	Unique ID for every request. This ID needs to be unique and unrepeated.
amount	decimal	20,0	Y	發放金額（金額必須大於 0 元）	JKOSCoins issue amount. (Amount must be greater than zero)
jkosId	string	64	N	發放對象 UUID	Target user ID.

範例 (Example)

curl --location --request POST 'https://{街口路徑}/jkocoin/exchange' \
--header 'Api-Key: uOXwSoSkXhk-Nj_JWspyfYiNHgKahikk' \
--header 'Digest: 765f165847cf8cd45e2a00c51df3dd590de5a9956f7a0cd14f804fdf8bd052cb' \
--header 'Content-Type: application/json' \
--data '{"exchangeId":"testunique1758786827","amount":10,"jkosId":"user123","clientId":"310886531"}'

返回參數 (Response Parameter)

Response Body

參數名稱 Parameter	資料型態 Data Type	說明	Description
Result	string	請參照 API 回覆代碼（Response Code）	Please refer to API response code (Response Code).
Message	string	結果訊息或失敗理由	Result message or reason of error.
ResultObject	object
ResultObject.jkosId	string	發放對象	Target user ID.
ResultObject.issueTime	string	發放時間 ISO-8601 格式：`yyyy-MM-dd’T’HH:mm:ss.SSS’Z’`	Issued time. ISO-8601 Format: `yyyy-MM-dd’T’HH:mm:ss.SSS’Z’`
ResultObject.amount	string	發放金額	Issued amount.

範例 (Example)

{
  "Result": "0001",
  "Message": null,
  "ResultObject": {
    "jkosId": "user123",
    "issueTime": "2025-10-01T10:38:22.999Z",
    "amount": 20
  }
}

{
  "Result": "2-MT-9005",
  "Message": "Internal service error",
  "ResultObject": null
}

回覆代碼 (Response Code)

檢核類錯誤

Result Code	說明	Description
0001	成功	Success
2-GW-0997	服務維護中 (Gateway)	Service is under maintenance.
2-GW-0201	驗簽失敗 (Gateway)	Signature verification failed.
2-MT-9001	欄位檢核失敗	Validation failed.
2-MT-9002	發放對象不存在	Target user not found.
2-MT-9003	發放金額需大於 0	Amount must be greater than zero.
2-MT-9004	驗證失敗	Authentication failed.

其他錯誤

以下錯誤需用 同個 exchangeId retry 直到取得結果。(Please retry with the same exchangeId.)
若更換 exchangeId 會視為新的交易，無法得到原先交易結果也會有重複發放風險。

Result Code	說明	Description
2-MT-9005	Internal service error.	Internal service error.
2-MT-9999	非預期的錯誤	Unspecified Error.

為什麼需要重試？

該訂單因網路或系統問題狀態卡在「處理中」，背後可能已經發幣成功或失敗。

外部方需用該筆交易的 exchangeId 重新向街口發起發幣請求，街口確認狀態並更新為「成功」或「失敗」。

街口系統也會定期 retry 狀態卡在「處理中」的發放清單並更新狀態，需由外部再次用同個 exchangeId 發請求來確認結果。

– _{When an internal service error occurs, the order may remain in the “processing” state due to network or system issues.}
– _{The external party must resend the issuance request to JKOPay using the same exchangeId. JKOPay will retry the process and update the status to either “success” or “failure”.}
_{– JKOPay’s system also periodically retries orders stuck in the “processing” state and updates their status. The external party must either resend the request with the same exchangeId to confirm the result.}