Skip to main content
本文档面向需要对接 PayMatrix OpenAPI 的商户开发者，帮助你了解整体接入流程与技术要求。

​
接入流程

1

完成商户入驻

在商户门户注册并完成资质审核，获取商户 ID 和生产环境权限。
2

生成并上传 RSA 密钥

生成 2048 位 RSA 密钥对，将公钥上传至商户门户「开发者设置」。
3

配置安全信息

设置 IP 白名单、Webhook 回调地址和签名密钥。
4

沙盒联调

使用沙盒环境密钥和地址完成接口联调，验证签名和业务流程。
5

切换生产环境

联调通过后，将 API 地址和密钥切换为生产环境配置，正式上线。

​
通信协议

项目说明
协议HTTPS（强制）
请求方式POST / GET
数据格式JSON
字符编码UTF-8
Content-Typeapplication/json

​
安全机制

PayMatrix OpenAPI 提供多层安全防护：

​
RSA 签名鉴权

所有支付相关接口需要携带 RSA 签名。商户使用自己的私钥对请求内容签名，平台使用商户公钥验签。 详见 签名与鉴权。

​
IP 白名单

可配置允许调用 OpenAPI 的服务器 IP 地址，非白名单 IP 的请求将被拒绝。 详见 IP 白名单。

​
防重放攻击

平台会校验请求的时间戳和随机数，防止恶意重放请求：
  • 时间戳有效窗口：±2 分钟
  • Nonce 去重周期：同一商户 5 分钟内不可重复

​
Webhook 签名

平台推送的 Webhook 事件使用 HMAC-SHA256 签名，商户服务端需要验签以确保回调来源可信。 详见 Webhook 签名验签。

​
请求头规范

所有需要签名的接口必须携带以下请求头：
Header必填说明
Content-Type是application/json
X-Merchant-Id是平台分配的商户 ID
X-Timestamp是请求时间戳（Unix 毫秒）
X-Nonce是随机字符串，每次请求唯一
X-Signature是RSA 签名（Base64 编码）

​
接口前缀

所有 OpenAPI 接口统一使用以下前缀：
  • 沙盒环境：https://api-sbx.paymetrixpay.com/api
  • 生产环境：https://openapi.paymatrixpay.com/api
具体接口路径：
  • 支付创建：POST /api/merchant/payment/create
  • 支付查询：GET /api/merchant/order/payment/query/{transactionId}
  • 退款发起：POST /api/merchant/payment/refund
  • 退款查询：GET /api/merchant/order/refund/query/{transactionId}

​
响应格式

所有接口统一返回以下 JSON 结构： 
{
  "code": 200,
  "msg": "success",
  "data": { ... }
}
字段类型说明
codeInteger业务状态码，200 表示成功
msgString提示信息
dataObject / null业务数据，失败时为 null

​
下一步