# 集成指引 ## 1. 整体流程 ```mermaid 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; ``` ::: tip 您在集成过程中的任何问题，都可以通过[**提交工单**](https://docs.payermax.com/202606-version/appendix/faq/ticket.md)咨询，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官网的[**联系我们**](https://www.payermax.com/zh-cn/contact)页面发送合作意向，与我司商务进行前期的沟通；确定好合作方式及选择需要接入的服务和产品。 同时，由PayerMax商务人员创建联调对接群，开展技术对接。 ### 3.2 注册成为开发者 访问[**PayerMax开发者中心**](https://developer.payermax.com/welcome)，使用邮箱注册开发者。 ### 3.3 获取测试环境的商户号和AppId 使用已注册的账号信息登录PayerMax开发者中心，进入 **基础设置** → **开发信息** → **密钥信息**，查看已创建的测试商户号（`merchantNo`）和`appId`。 `merchantNo`和`appId`是PayerMax接口请求的必填信息，如下是一个接口请求样例，其中标明两者的使用。 ```js 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开发者中心**](https://developer.payermax.com/welcome)，进入 **基础设置** → **开发信息** → **密钥信息**，选择已创建的测试商户，点击 **上传公钥**，可查看PayerMax公钥，并上传商户公钥。 ![](https://img-cdn-sg.payermax.com/public/20251204-c55fec47-7360-405a-a93f-cd3eca400c59.png) 请您务必妥善保管密钥信息，若不慎泄漏密钥，请及时登录开发者中心并更新密钥。 ::: warning 注意： 密钥是区分测试环境和生产环境的，因此，当您集成完毕，发布上线时，需要配置生产环境的密钥，具体参看后文`配置生产环境的密钥信息`。 ::: #### 3.4.2 配置测试环境的回调地址 回调地址用于接收来自PayerMax发送的订单异步回调结果，如：[支付结果回调通知](https://docs.payermax.com/202606-version/acquiring/start-integration/related-capabilities-integration/payment-result.md#_3-1-支付结果通知)、[退款结果回调通知等](https://docs.payermax.com/202606-version/acquiring/start-integration/related-capabilities-integration/refund-integration.md#_3-4-1-退款通知)。 登录[**PayerMax开发者中心**](https://developer.payermax.com/welcome) ，进入 **基础设置** → **开发信息** → **通知地址**，进行设置。 ![](https://img-cdn-sg.payermax.com/public/20251205-f5dfd84c-f84e-4640-b86b-e8142e8018d4.png) ### 3.5 设置测试环境的服务器IP白名单 如果您集成测试的网络环境，对访问IP有白名单安全限制，那么，请联系PayerMax技术支持，获取PayerMax服务器IP，并将其加入白名单。否则，PayerMax无法正常通过您[配置的回调地址](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-4-2-配置测试环境的回调地址)发起调用。 ### 3.6 开通集成的支付方式 登录[**PayerMax开发者中心**](https://developer.payermax.com/welcome)，进入 **基础设置** → **支付方式管理**，可以开通或关闭当前账号可使用的支付方式。 ## 4. 技术集成 根据商户接入能力的不同，PayerMax提供的集成文档如下。 | PayerMax产品 | | 对接模式 | 集成文档 | | ------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | | 收银台模式 | [收银台-全量收银台](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/cashier-payment/payermax-checkout.md) | | | | | [收银台-指定支付方式](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/cashier-payment/merchant-customized-checkout.md) | | | | | [前置组件-CARD](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/drop-in/card.md) | | | | 前置组件 | [前置组件-ApplePay](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/drop-in/applepay.md) | | | 标准收单 | | [前置组件-GooglePay](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/drop-in/googlepay.md) | | 全球收单 | | | [纯API-CARD](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/API/card.md) | | | | 纯API | [纯API-GooglePay](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/API/googlepay.md) | | | | | [纯API-ApplePay](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/API/applepay.md) | | | | | [纯API-APM](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/API/apm.md) | | | | | [PayerMax管理订阅计划](https://docs.payermax.com/202606-version/acquiring/start-integration/subscription-and-auto-debit/payermax-manage-subscription-plans.md) | | | 订阅代扣 | / | [商户管理订阅计划](https://docs.payermax.com/202606-version/acquiring/start-integration/subscription-and-auto-debit/merchants-manage-subscription-plans.md) | | | | | [非周期性代扣](https://docs.payermax.com/202606-version/acquiring/start-integration/subscription-and-auto-debit/non-periodic-auto-debit.md) | | 全球付款 | 全球付款 | API付款 | [API付款](https://docs.payermax.com/202606-version/disbursement/request/api-request.md) | | | | 平台付款 | [商户平台批量付款](https://docs.payermax.com/202606-version/disbursement/request/batch-disbursement.md)，[商户平台单笔付款](https://docs.payermax.com/202606-version/disbursement/request/single-disbursement.md) | | 全球收款 | 本地收款 | / | [本地收款流程](https://docs.payermax.com/202606-version/receipt/VA/collection-process.md) | ## 5. 测试验证 ### 5.1 检查支付方式状态 登录[**PayerMax开发者中心**](https://developer.payermax.com/welcome)，进入 **基础设置** → **支付方式管理**，查看要测试的支付方式是否已经开通。如果未开通，可先开通，再发起测试。 ### 5.2 发起连通性测试 商户可先构造一个简单的请求，验证网络连通性，确认加签验签、网络白名单等非功能性配置是否已正确设置。 ### 5.3 发起功能性测试 连通性测试完成后，请在测试环境发起一笔成功单和一笔失败单，并校验请求响应符合预期。 ## 6. 集成验收 在[**PayerMax开发者中心**](https://developer.payermax.com/welcome)完成以下操作： 1. 绑定产线商户号：在开发信息页面绑定产线商户号时需要您的邮箱是商户平台操作员。[**商户平台（MMC）**](https://mmc.payermax.com/#/login)的操作指南，如：添加操作员等，请查看[商户平台介绍](https://docs.payermax.com/202606-version/mmc/introduction.md)； 2. 测试完成：测试环境用开发者平台商户号联调测试； 3. 验收：在 **验收** → **简单验收** 菜单下申请验收检查； 4. 验收通过：可以看到产线配置菜单。 ![](https://img-cdn-sg.payermax.com/public/20251204-3d3adbc0-1876-4345-b3cc-f39ebb5a8123.png) ## 7. 发布上线 ### 7.1 激活商服服务平台的账号 - 管理员账号： 双方商务合作确认后，PayerMax 商务会绑定管理员邮箱。请管理员注意查收 PayerMax 下发的激活邮件，可根据邮件指引激活账号。 首次登录需要设置密码，请确保密码安全，以防外泄。 - 操作员账号：只能管理员添加，首次添加后会下发激活邮件。 具体可查看[商户平台介绍](https://docs.payermax.com/202606-version/mmc/introduction.md)。 ### 7.2 开通集成的支付方式 某些支付方式，需要PayerMax代替商户向支付渠道侧进行报备，报备通过后才能上送交易。在等待报备通过期间，商户无法开量。 您可以登录[**商户平台（MMC）**](https://mmc.payermax.com/#/login)，在 **设置服务** → **支付方式可用性** 查看支付方式的可用状态。 ### 7.3 配置生产环境的集成信息 1. 在[**PayerMax开发者中心**](https://developer.payermax.com/welcome)中的 **产线配置** → **密钥配置** 页面查看产线商户号、产线AppId、配置产线商户公钥； 2. 产线回调地址可在[**商户平台（MMC）**](https://mmc.payermax.com/#/login)中的开发参数下配置或者接口中传； 3. 切换生产环境请求地址。 ### 7.4 设置生产环境的服务器IP白名单 如果您生产测试的网络环境，对访问IP有白名单安全限制，那么，请联系PayerMax技术支持，获取PayerMax服务器IP，并将其加入白名单。否则，PayerMax无法正常通过您[配置的回调地址](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-4-2-配置测试环境的回调地址)发起调用。 ::: warning 注意： 如果接入付款产品且对接形式是API付款，请联系PayerMax技术支持，申请将贵司服务器的出口IP加白，否则产线下单会失败。 :::