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

请求是否已成功执行。