本章节帮助你快速了解从入驻 PayMatrix 到完成第一笔支付的完整流程。
整体架构
PayMatrix 为商户提供以下核心服务：
- OpenAPI 网关：商户服务端调用接口的入口，支持 RSA 签名鉴权
- 托管收银台：面向消费者的支付页面，支持银行卡、电子钱包等多种支付方式
- 商户门户：商户管理后台，用于交易查询、结算管理、开发者配置
- Webhook 通知：异步推送支付、退款、争议等事件到商户服务端
接入流程总览
- 商户入驻 — 在商户门户注册企业信息，提交资质材料，等待审核通过
- 获取 API 密钥 — 审核通过后，在「开发者设置」中上传 RSA 公钥、获取商户 ID
- 配置 Webhook — 设置接收事件通知的回调地址和签名密钥
- 沙盒测试 — 在沙盒环境中调用 API，验证签名和业务流程
- 集成收银台 — 选择托管收银台或自建方案完成前端支付流程
- 上线 — 切换到生产环境密钥，正式对外提供服务
环境与地址
| 环境 | OpenAPI 地址 | 说明 |
|---|
| 沙盒环境 | https://api-sbx.paymetrixpay.com/api | 用于联调测试，无真实资金 |
| 生产环境 | https://openapi.paymatrixpay.com/api | 正式环境，需审核后开通 |
- 支付接口：
/api/merchant/payment
- 订单查询：
/api/merchant/order
第一步：注册商户账号
前往商户门户完成注册，提交以下材料：
- 企业营业执照
- 法人身份证明
- 银行账户信息（用于结算）
- 网站/应用信息
详见 入驻指南。
第二步：配置 API 密钥
审核通过后，登录商户门户进入「开发者设置」：
- 生成 RSA 密钥对（2048 位，SHA256WithRSA）
- 上传公钥至平台
- 获取商户 ID（
merchantId），后续所有 API 调用需要携带
妥善保管私钥，不要泄露或提交到代码仓库。建议使用密钥管理服务（KMS）存储。
第三步：完成第一笔支付
1. 商户服务端创建支付订单
curl -X POST "https://api-sbx.paymetrixpay.com/api/merchant/payment/create" \
-H "Content-Type: application/json" \
-H "X-Merchant-Id: YOUR_MERCHANT_ID" \
-H "X-Timestamp: 1737004800000" \
-H "X-Nonce: a3f7b2c1d4e5" \
-H "X-Signature: <RSA_SIGNATURE>" \
-d '{
"merchant_transaction_id": "TXN20260101001",
"amount": 100.00,
"currency_code": "USD",
"redirect_url": "https://your-site.com/payment/return",
"cancel_url": "https://your-site.com/payment/cancel",
"products": [
{
"product_id": "PROD001",
"name": "Example Product",
"price": 100.00,
"quantity": 1
}
],
"customer": {
"full_name": "John Doe"
}
}'
2. 引导用户跳转收银台
成功响应中包含 pay_url，将用户重定向到该地址完成支付。
{
"code": 200,
"msg": "success",
"data": {
"order_id": "1000126011700000100001",
"pay_url": "https://cashier-api.paymatrixpay.com/pay/xxx"
}
}
3. 接收 Webhook 通知
支付完成后，平台会向你的 Webhook 地址推送 order.payment.succeeded 事件。
4. 查询支付状态（可选）
curl -X GET "https://api-sbx.paymetrixpay.com/api/merchant/order/payment/query/TXN20260101001" \
-H "X-Merchant-Id: YOUR_MERCHANT_ID" \
-H "X-Timestamp: 1737004800000" \
-H "X-Nonce: a3f7b2c1d4e5" \
-H "X-Signature: <RSA_SIGNATURE>"
下一步
