集成指引

1. 整体流程

graph LR
    direction LR

    %% 定义样式
    %% 1. 子图外框：去除背景色，仅留边框
    classDef subStyle fill:#ebf5ff,stroke:#01579b,stroke-width:1px;
    %% 2. 蓝色节点样式
    classDef blueNode fill:#0056b3,stroke:#4169E1,stroke-width:2px,color:#ffffff,font-weight:bold;
    %% 3. 隐形标题样式：无边框、无背景、深蓝色加粗文字
    classDef titleStyle fill:none,stroke:none,color:#01579b,font-weight:bold,font-size:16px;

    subgraph S1 [ ]
        direction TB
        t1[商务洽谈] ~~~ n1_1[商务沟通] --> n1_2[开通商户平台]
    end

    subgraph S2 [ ]
        direction TB
        t2[集成准备] ~~~ n2_1[注册开发者中心] --> n2_2[配置测试集成信息]
    end

    subgraph S3 [ ]
        direction TB
        t3[技术集成] ~~~ n3_1[查看集成文档] --> n3_3[技术开发]
    end

    subgraph S4 [ ]
        direction TB
        t4[集成测试] ~~~ n4_1[开启测试环境支付方式]
        n4_1 --> n4_2[发起支付测试流程]
    end

    subgraph S5 [ ]
        direction TB
        t5[集成验收] ~~~ n5_1[提交测试信息]
        n5_1 --> n5_2[检查测试单据及日志]
    end

    subgraph S6 [ ]
        direction TB
        t6[发布上线] ~~~ n6_1[配置生产集成环境]
        n6_1 --> n6_2[开通线上支付方式并开量]
    end

    %% 连线逻辑
    S1 --> S2 --> S3 --> S4 --> S5 --> S6

    %% 应用样式
    class S1,S2,S3,S4,S5,S6 subStyle;
    class n1_1,n1_2,n2_1,n2_2,n3_1,n3_3,n4_1,n4_2,n5_1,n5_2,n6_1,n6_2 blueNode;
    class t1,t2,t3,t4,t5,t6 titleStyle;

您在集成过程中的任何问题，都可以通过提交工单咨询，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": "<您的appId>",
    "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产品		对接模式	集成文档
全球收单	标准收单	收银台模式	收银台-全量收银台
			收银台-指定支付方式
		前置组件	前置组件-CARD
			前置组件-ApplePay
			前置组件-GooglePay
		纯API	纯API-CARD
			纯API-GooglePay
			纯API-ApplePay
			纯API-APM
	订阅代扣	/	PayerMax管理订阅计划
			商户管理订阅计划
			非周期性代扣
全球付款	全球付款	API付款	API付款
		平台付款	商户平台批量付款，商户平台单笔付款
全球收款	本地收款	/	本地收款流程

5. 测试验证

5.1 检查支付方式状态

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

5.2 发起连通性测试

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

5.3 发起功能性测试

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

6. 集成验收

在PayerMax开发者中心完成以下操作：

1. 绑定产线商户号：在开发信息页面绑定产线商户号时需要您的邮箱是商户平台操作员。商户平台（MMC）的操作指南，如：添加操作员等，请查看商户平台介绍；

2. 测试完成：测试环境用开发者平台商户号联调测试；

3. 验收：在 验收 → 简单验收 菜单下申请验收检查；

4. 验收通过：可以看到产线配置菜单。

7. 发布上线

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

• 管理员账号： 双方商务合作确认后，PayerMax 商务会绑定管理员邮箱。请管理员注意查收 PayerMax 下发的激活邮件，可根据邮件指引激活账号。 首次登录需要设置密码，请确保密码安全，以防外泄。

• 操作员账号：只能管理员添加，首次添加后会下发激活邮件。

具体可查看商户平台介绍。

7.2 开通集成的支付方式

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

您可以登录商户平台（MMC），在 设置服务 → 支付方式可用性 查看支付方式的可用状态。

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

1. 在PayerMax开发者中心中的 产线配置 → 密钥配置 页面查看产线商户号、产线AppId、配置产线商户公钥；

2. 产线回调地址可在商户平台（MMC）中的开发参数下配置或者接口中传；

3. 切换生产环境请求地址。

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

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

注意：

如果接入付款产品且对接形式是API付款，请联系PayerMax技术支持，申请将贵司服务器的出口IP加白，否则产线下单会失败。