集成指引

1. 整体流程

您在集成过程中的任何问题，都可以通过提交工单咨询，PayerMax会尽快与您联系。

2. 环境信息

• 测试环境：https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/ <接口PATH>

• 集成环境：https://pay-gate.payermax.com/aggregate-pay/api/gateway/ <接口PATH>

3. 前置准备

3.1 商务洽谈

通过PayerMax官网的联系我们页面发送合作意向，与我司商务进行前期的沟通；确定好合作方式及选择需要接入的服务和产品。

同时，由PayerMax商务人员创建联调对接群，开展技术对接。

3.2 注册成为开发者

访问PayerMax开发者中心，使用邮箱注册开发者。

3.3 获取测试环境的商户号和AppId

使用已注册的账号信息登录PayerMax开发者中心，进入 「基础设置」 → 「开发信息」 → 「密钥信息」，查看已创建的测试商户号（merchantNo）和appId。

merchantNo和appId是PayerMax接口请求的必填信息，如下是一个接口请求样例，其中标明两者的使用。

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'sign: FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \
  --data '{
    "version": "1.4",
    "keyVersion": "1",
    "requestTime": "2025-05-14T06:29:50.085+00:00",
    "appId": "<您的merchantNo>",
    "merchantNo": "<您的merchantNo>",
    "data": <请求数据JSON>
}'

3.4 配置测试环境的集成信息

3.4.1 配置测试环境的密钥信息

为了保障网络通信的安全性，PayerMax采用非对称密钥对，对通信报文进行加签和验签，签名使用的是SHA256WithRSA签名算法。您可以查看如何生成密钥对，采用其中一种方式生成密钥对。

在生成自己的密钥对（公钥和私钥）后，登录PayerMax开发者中心，进入 「基础设置」 → 「开发信息」 → 「密钥信息」，选择已创建的测试商户，点击 「上传公钥」，可查看PayerMax公钥，并上传商户公钥。

请您务必妥善保管密钥信息，若不慎泄漏密钥，请及时登录开发者中心并更新密钥。

注意：

密钥是区分测试环境和生产环境的，因此，当您集成完毕，发布上线时，需要配置生产环境的密钥，具体参看后文【配置生产环境的密钥信息】。

3.4.2 配置测试环境的回调地址

回调地址用于接收来自PayerMax发送的订单异步回调结果，如：【支付结果回调通知】、【退款结果回调通知等】。

登录PayerMax开发者中心 ，进入 「基础设置」 → 「开发信息」 → 「通知地址」，进行设置。

3.5 设置测试环境的服务器IP白名单

如果您集成测试的网络环境，对访问IP有白名单安全限制，那么，请联系PayerMax技术支持，获取PayerMax服务器IP，并将其加入白名单。否则，PayerMax无法正常通过您【配置的回调地址】发起调用。

3.6 开通集成的支付方式

登录PayerMax开发者中心，进入 「基础设置」 → 「支付方式管理」，可以开通或关闭当前账号可使用的支付方式。

4. 技术集成

根据商户接入能力的不同，PayerMax提供的集成文档如下。

PayerMax产品		集成模式
全球收单	标准收单	【收银台】
		【纯API】
		【前置组件】
		【链接支付】
	订阅代扣	【收银台】
		【纯API】
		【前置组件】
		【链接支付】
全球付款	全球付款	【API付款】
		【商户服务平台付款】
全球收款	本地收款	/

在标准收单下，如果您只关注某个支付方式的集成，还可以查看【按支付方式集成】。

5. 测试验证

5.1 检查支付方式状态

登录PayerMax开发者中心，进入 「基础设置」 → 「支付方式管理」，查看要测试的支付方式是否已经开通。如果未开通，可先开通，再发起测试。

5.2 发起连通性测试

商户可先构造一个简单的请求，验证网络连通性，确认加签验签、网络白名单等非功能性配置是否已正确设置。

5.3 发起功能性测试

连通性测试完成后，请在测试环境发起一笔成功单和一笔失败单，并校验请求响应符合预期。

6. 集成验收

在您完成测试后，可点击商户平台（MMC）右下角「咨询中心」图标提交订单号和产线环境的商户号，PayerMax技术支持会进行必要的校验。我们会检查您的测试执行情况，通过后会将生产环境的商户号置为可用状态。

7. 发布上线

7.1 激活商服服务平台的账号

双方商务合作确认后，PayerMax 将根据《商户接入申请表》中所填写的“管理员账号信息”，创建可供商户登录商户服务平台（MMC）的管理员账号。 届时，请注意查收 PayerMax 下发的激活邮件，商户可根据邮件指引激活管理员账号。 首次登录需要设置密码，请确保密码安全，以防外泄。

7.2 获取生产环境的商户号和AppId

登录商户平台（MMC），进入 「设置服务」 → 「开发参数」 → 「正式环境」查看生产环境的商户号和appId。

更多商户平台（MMC）的操作指南，如：添加操作员等，参看【此处】。

7.3 配置生产环境的集成信息

7.3.1 配置生产环境的密钥信息

登录商户平台（MMC），进入 「设置服务」 → 「开发参数」 → 「密钥管理」，设置生产环境的密钥。

7.3.2 配置生产环境的回调地址

登录商户平台（MMC），进入 「设置服务」 → 「开发参数」 → 「地址管理」，设置生产环境的密钥。

7.4 设置生产环境的服务器IP白名单

如果您生产测试的网络环境，对访问IP有白名单安全限制，那么，请联系PayerMax技术支持，获取PayerMax服务器IP，并将其加入白名单。否则，PayerMax无法正常通过您【配置的回调地址】发起调用。

如果接入付款产品，请联系PayerMax技术支持，将您服务器的出口IP提交给我们，我们会将其加入PayerMax白名单。

7.5 开通集成的支付方式

某些支付方式，需要PayerMax代替商户向支付渠道侧进行报备，报备通过后才能上送交易。在等待报备通过期间，商户无法开量。

您可以登录商户平台（MMC），查看支付方式的可用状态。