跳轉至

API 介紹

最後更新於: 2023-01-08

介紹

MTPay API 是基於 REST 架構風格進行組織和管理的。 我們的 API 採用可預測的資源導向的 URL，接受 JSON 編碼的請求，傳回 JSON 編碼的回應，並利用標準的 HTTP 回應代碼、身份驗證和動詞。

如果您需要在測試環境中存取 MTPay API，請聯絡我們的客戶服務團隊。 我們將很樂意協助您設定一個專門用於測試目的的沙盒環境。

在發布新版本和自訂功能時，我們努力保持與 API 的向後相容性。

請登入後台系統以查看您的 API 金鑰和關聯資料。

身份驗證

MTPay API 使用 API 金鑰進行請求的身份驗證。 您可以在我們系統的「商家服務」-「API 令牌管理」部分中檢視和管理您的 API 金鑰。

您的 API 金鑰具有許多特權，請務必確保其安全性。 建議不要在公開可存取的網域（如 GitHub、客戶端程式碼和類似平台）中公開您的機密 API 密鑰。

所有 API 請求必須透過 HTTPS 進行。 使用純 HTTP 進行的呼叫將會失敗。 沒有身份驗證的 API 請求也將失敗。

為了作為連線帳戶，用戶端可以使用以下特殊標頭發出請求：

access_key

您可以取得系統產生的 access_key 和 private_key 資訊。 在這個特殊的 HTTP 標頭中，您需要傳遞的是 access_key 值的明文。

timestamp

需要輸入的值是請求的 UTC 時間戳，確保精確到**毫秒**。

signature

在取得了 access_key 和 secret_key 後，您需要使用 HmacSHA256 演算法計算這個資料：

{access_key}_{timestamp}

例如，如果您的 access_key 是 B6QKwx0NnKaQ14zf24Ux5Oc9Gy1xlf2R，secret_key 是 WUYx7DTQZakugtP9gOAimYUphcnc3jWuPRi1UVnWmwXSnMnsCVBzz1ILdaxisvz9，目前時間為 1625546438154。 需要計算的數據是：

B6QKwx0NnKaQ14zf24Ux5Oc9Gy1xlf2R_1625546438154

透過將 secret_key 作為 HmacSHA256 的計算密碼，產生的簽章值即為此項目的值：

EDB15CF33C232128BDF118CEB147C453181939F8B37EC43886F68B3BCC2C19CD

程式碼範例：

String originSignature = String.format("%s_%s", accessKey, timestamp);

Mac hashInstance = Mac.getInstance("HmacSHA256");
hashInstance.init(new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"));

byte[] hash = hashInstance.doFinal(originSignature.getBytes());

String signature = DatatypeConverter.printHexBinary(hash);

結構

當 API 以 JSON 編碼傳回資料時，預設的回應結構是：

{
   "data": {},
   "statusCode": "SUCCESS",
   "message": null,
   "success": true
}

data

編碼後的回應資料以通用泛型提供。

statusCode

  • SUCCESS: 請求成功處理。
  • TIMESTAMP_ERROR: 時間戳驗證失敗，請確保時間戳傳遞正確。
  • SIGNATURE_ERROR: 簽章驗證失敗。 請參考身份驗證部分進行驗證。 如果問題仍然存在，請聯絡我們的支援團隊尋求協助。
  • ACCESS_KEY_ERROR: 提供的 access_key 不正確。
  • PARAMETER_ERROR: 其他參數不正確。
  • ACCOUNT_STATUS_ERROR: 帳戶狀態異常。
  • SYSTEM_ERROR: 系統遇到異常。
  • NO_ADVERTISEMENT: 已棄用。

message

響應訊息作為輔助手段，用於識別定位錯誤的原因。

success

請求是否已成功執行。