介绍¶

概述¶

MTPay API 基于 REST 架构风格进行组织和管理。我们的 API 具有可预测的资源导向 URL，接受 JSON 编码的请求，返回 JSON 编码的响应，并使用标准的 HTTP 响应代码、身份验证和动词。

如果您需要在测试环境中访问 MTPay API，请联系我们的客户服务团队。我们将很高兴为您提供专门为测试目的设计的沙盒环境。

随着我们发布新版本和定制功能，我们将努力保持与 API 的向后兼容性。

请登录后台系统以查看您的 API 密钥和相关数据。

身份验证¶

所有请求 MTPay API 的请求都必须使用 API 密钥进行身份验证。这些密钥可以通过您账户仪表板中的 商户服务 > API 密钥管理 部分生成和管理。

⚠️ 安全提示： API 密钥授予对您账户的特权访问权限。请保密并且永远不要在公共仓库（例如，GitHub）、客户端代码或任何不可信的环境中暴露它们。

HTTPS 要求¶

所有 API 请求必须通过 HTTPS 发送。

身份验证头¶

每个 API 请求必须包含以下 HTTP 头：

头部	描述
access_key	您的唯一访问密钥，明文由系统提供。
timestamp	当前 UTC 时间戳，单位为毫秒。
signature	使用您的密钥和请求元数据生成的 HMAC-SHA256 签名。

签名生成¶

要生成签名，请按照以下步骤操作：

使用下划线 _ 将 access key 和 timestamp 连接起来： {access_key}_{timestamp}
使用您的 secret_key 作为密钥计算上面字符串的 HMAC-SHA256 哈希。
将结果转换为 十六进制字符串（大写）—— 这就是最终的 signature。

示例¶

access_key: B6QKwx0NnKaQ14zf24Ux5Oc9Gy1xlf2R
secret_key: WUYx7DTQZakugtP9gOAimYUphcnc3jWuPRi1UVnWmwXSnMnsCVBzz1ILdaxisvz9
timestamp: 1625546438154

步骤¶

连接：

B6QKwx0NnKaQ14zf24Ux5Oc9Gy1xlf2R_1625546438154

使用 secret_key 计算 HMAC-SHA256：

EDB15CF33C232128BDF118CEB147C453181939F8B37EC43886F68B3BCC2C19CD

响应结构¶

所有 API 响应都遵循统一的结构，以确保一致性和便于集成。

响应格式¶

{
  "data": {
    /* 响应有效载荷 */
  },
  "isSuccess": true,
  "statusCode": "SUCCESS",
  "message": "",
  "version": "2.0"
}

字段说明¶

字段	类型	描述
data	`Object` / null	一般类型 T 的响应有效载荷。
isSuccess	`Boolean`	表示请求是否成功。
statusCode	`APIResponseCode`	枚举值，表示请求的结果。
message	`String`	结果或错误消息的描述。
version	`String`	API 版本标识符。默认值："2.0"。

`APIResponseCode` 枚举¶

代码	描述
SUCCESS	请求成功完成。
ACCESS_KEY_ERROR	无效或缺少 accessKey。
ACCOUNT_STATUS_ERROR	账户被暂停或禁用。
SIGNATURE_ERROR	签名验证失败。
TIMESTAMP_ERROR	请求时间戳无效或已过期。
PARAMETER_ERROR	一个或多个请求参数不正确或缺失。
SYSTEM_ERROR	内部系统错误，请稍后再试。

示例 - 成功响应¶

{
  "data": {
    "orderId": "ORD-20250317-0001",
    "status": "PENDING"
  },
  "isSuccess": true,
  "statusCode": "SUCCESS",
  "message": "",
  "version": "2.0"
}

示例 - 失败响应¶

{
  "data": null,
  "isSuccess": false,
  "statusCode": "PARAMETER_ERROR",
  "message": "Missing required parameter: amount.",
  "version": "2.0"
}

介绍¶

概述¶