# 接入前准备

::: tip  

本文档讲述了对接前置准备要求，帮助合作方高效的理解接入前的准备动作，顺利完成后续系统对接。
:::

## 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;
```

您在集成过程中的任何问题，都可以通过[提交工单](https://docs.payermax.com/202606-version/appendix/faq/ticket.md)咨询，PayerMax会尽快与您联系。

## 2. 注册成为开发者

### 2.1 邮箱注册

访问[**PayerMax开发者中心**](https://developer.payermax.com/welcome)，使用邮箱注册开发者。

- 1. 打开登录注册页面，点击注册按钮

![](https://img-cdn-sg.payermax.com/public/20260506-728f7955-4c0c-4884-9b35-f580b77d2d3b.png)

- 2. 完成注册邮箱录入及认证

![](https://img-cdn-sg.payermax.com/public/20260506-542a0f53-71cd-4e3f-84a5-4d4b9d03a40d.png)

### 2.2 测试参数说明

使用已注册的账号登录PayerMax开发者中心，进入 **基础设置** → **开发信息**，查看自动已创建的测试开发参数。

![](https://img-cdn-sg.payermax.com/public/20260506-67774483-ed81-43b6-bbd6-f3438d6434bf.png)

- 会员号、`商户号`、`appId`：系统自动生成供开发者测试环境使用的一套参数，PayerMax接口请求的必填信息；

- 密钥类型：RSA；

- 公钥上传：开发者需要上传商户公钥给PayerMax，用于验证商户签名，公私钥说明查看**3.2密钥说明及配置**；

- 邀请协作者：被邀请人和您共用同一个开发者平台商户号；

- 绑定产线商户号：**绑定产线商户号 完成自助验收**，才可以在商户平台配置获取对应产线商户号开发参数。（绑定正式商户号，需要产线商户号管理员[分配操作员权限](https://mmc.payermax.com/#/help-center?helpCenterType=GUIDE&helpCenterPath=%2Fhelp-center)） 

## 3. 参数配置及说明

### 3.1 配置异步通知地址

回调地址用于接入方服务端接收来自 PayerMax 服务端提供的订单异步回调结果。

该地址可通过调用接口的对应参数提交，也可通过商户管理平台设置。其中，接口提交的回调地址优先于商户管理平台内的。

- 测试环境（开发者平台）：**开发者平台** → **基础设置** → **开发信息** → **通知地址**

![](https://img-cdn-sg.payermax.com/public/20260506-4a456619-b929-428b-8f20-6869d4be98a1.png)

### 3.2 密钥说明及配置

#### 3.2.1  密钥说明

::: tip  

**密钥算法**：RSA  

**Key格式** ：PKCS8，需要去除开头、结尾、换行  

**签名算法**：SHA256WithRSA  

**密钥长度**：2048  

**注意**：请妥善保管密钥信息，若不慎泄漏密钥，请及时更新密钥  

:::

```mermaid
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#fcf4e4',
    'noteTextColor': '#00000',
    'noteBorderColor': '#FAECCC'
  }
}}%%
sequenceDiagram
    participant Merchant as 商户
    participant Platform as PayerMax

    rect rgb(235, 245, 255)
        Note over Merchant: 持有：商户私钥、PayerMax公钥
        Note over Platform: 持有：商户公钥、PayerMax私钥
    end

    Merchant->>Platform: 1. 使用「商户私钥」对 body 进行加签，发送请求至PayerMax
    Platform->>Platform: 2. PayerMax使用「商户公钥」进行验签
    
    Platform->>Merchant: 3. PayerMax用「PayerMax私钥」将回调数据签名后发给商户
    Merchant->>Merchant: 4. 商户使用「PayerMax公钥」进行验签
```

#### 3.2.2 密钥生成（已有密钥可跳过此步骤）

商户公私钥可通过如下两种方式进行生成（任选其一即可），生成的 `商户私钥` 请商户自己妥善保管，用于请求PayerMax报文的加签操作，`商户公钥` 通过Merchant Dashboard平台上传给PayerMax用于验证商户签名防止报文在网络传输过程中被篡改，同时在平台上获取 `PayerMax公钥` 放到自己程序中，用于验证PayerMax加签报文的签名。

1. **在线快速生成密钥对**

点击 [PayerMax密钥生成工具](https://developer.payermax.com/devtool/generate "PayerMax密钥生成工具") 快速生成密钥对。

2. **openssl生成**

通过openssl命令生成pem公私钥文件并手动去除开头、结尾、换行符得到公私钥信息。

- 下载并安装openssl，参考文档：https://www.openssl.org/source/

执行如下命令：

```
#私钥
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -out private.key.pem
#公钥
openssl rsa -in private.key.pem -pubout > public.key.pem
```
执行完上述命令后，会生成两个文件内容如下（示例）：

```
公钥文件public.key.pem-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzN6tx98b4KZB1uqEuT7P
/nWHrYqFdiy+Kzs9KZ6JtSQWb3b45loOsdUxFeaCAt+ZJ0+fNJRDnwc7AiKOlgbw
0HT93WRVZXP6cwQV1Bg1XybBxtQE4OcEq+Uzzmd7RoBkQuNmjIUgDYtWPBSekSpZ
AhWkk4dh8Nd7Qv2BvJNNOISVFcROFgMgbGz80v6WofR4nnTEdTB+j4pR/Q4dhnIR
OlaWrai+hBPn95sahQ+Ujf7LZgLyhpyQeS+/xsLv29lDI6D+8neR1tsOYdOp8f8Q
NwDkOroMlzxkQeYsJDLpLG8p58zHSdcLOsopVe2u41uzdrQ8qjhw4FU9eBOmFite
iwIDAQAB
```

```
私钥文件private.key.pem-----BEGIN PRIVATE KEY-----
MIIEwAIBADANBgkqhkiG9w0BAQEFAASCBKowggSmAgEAAoIBAQDM3q3H3xvgpkHW
6oS5Ps/+dYetioV2LL4rOz0pnom1JBZvdvjmWg6x1TEV5oIC35knT580lEOfBzsC
Io6WBvDQdP3dZFVlc/pzBBXUGDVfJsHG1ATg5wSr5TPOZ3tGgGRC42aMhSANi1Y8
FJ6RKlkCFaSTh2Hw13tC/YG8k004hJUVxE4WAyBsbPzS/pah9HiedMR1MH6PilH9
Dh2GchE6VpatqL6EE+f3mxqFD5SN/stmAvKGnJB5L7/Gwu/b2UMjoP7yd5HW2w5h
06nx/xA3AOQ6ugyXPGRB5iwkMuksbynnzMdJ1ws6yilV7a7jW7N2tDyqOHDgVT14
E6YWK16LAgMBAAECggEBAKFLC8yZdixHGPzohHgH4N94jsptjae9kDcfG4dB3y8y
60r0gv9wlbMiotOYOHGkssKFaFWQCTESEz4aEOJDMqMcCKaeELGgPuUAqWLjcFmq
fNNaJ0EeAMqI2GG/jQmzmbwjpqApS1P+iHUi0rh9e7gta/YOl2hzbgMO7W6XFivQ
pMIQZQE0WpmpK8cNgev/Xog8ZnHFC6XGUgK+mDVvJMYwmywUPIfLw2fvAZ29Qogt
qiGeFCJSwAL1VkxryXSjJJBKuoc3cXEcq/hjhz6G9rvd50Lj2kCWMd8iqm/dtFyh
DnT5WSFYNPIH0Up9qtqeP+TqgI/SrztAVHgUXVB2ABkCgYEA9cSeHG04Pj3p9ZCe
Cc6qb6L2kFphb62BhmUSHZ50p6X1KsSMw4wnzbrgrvcSe97iWZNLC536eQVHE5gL
4ZjIxylYkp+FuuPHMIDseASR2pNmY2sJ83iTB4C9Y+37+64wBceFiXWBERdJA1t2
MnzWLR8ijFfmHQ4KX3DJOhR05qUCgYEA1WYroahttPyvMFHdmcCphF9jhF3U6SGu
VndwTtqaGLHzCmSvHxLFyd8ziw/F344IGIn8fIbOqhFAijyliD53kGMiKSUqMH4Q
eP2RfxGrZqek3f6pvyUtxfjXAh6+7pfL46u0AzmyvcpaGXqQToecCF43MCdbxh7Z
3CViGfBcWW8CgYEAvJRcufU4ddHuJoYMLfxNHRIPXV5sa1PYEjaVevKuEkGuaF2e
oSF3HU4qvzZIEZJJXnA94jEbEydwjWFapIUmcmOQWhlbdLb4jYgvajwfanc11k04
uoAnWVd4eygN9OWIZbbeCUaHfYS/ensAq+bMNJ0yVjvQDzVJ0kfpr84okR0CgYEA
mBroNKTx9ZQ6Zu2jT2lVKuY27+1VygpY0ob1xS7psXp9asYTUMm3s0ll2tQWTV9W
g+8uya/o9K2xXBcYQgGMhZ0zhzJXXRMuOJ88qt70VgpeaGGRqo4cj0TsNDWoEDag
fJoxiC8DKWZnTEvhOihM3mYRXkBfmNr6nIEE6Mo7eP8CgYEA8KqzIk+5On3xmeES
fQcLPYiaO9Hlttc7flyIpUL52Og7S1T/ekdiBVIDlePpjRx5H0iCtANyWmQq0Xbf
SseQ9SFJ/4DLvDMawhvolmxHs98PNa8xZ9KdXgUNc7RcewUVhK2aLkxUQKNO0lww
GGDGWfvePWzlVotJd0bM+a/X4qg=
```

#### 3.2.3  密钥配置

商户生成公私钥后，公钥通过商户管理平台上传，同时下载PayerMax的公钥。

**上传测试商户公钥**：登录开发者平台，进入 **基础设置** → **开发信息** → **密钥信息** → **公钥上传**。

![](https://img-cdn-sg.payermax.com/public/20260507-07f74cff-8a78-46e5-9202-dad77ab79ee5.png)

**下载平台公钥**：

![](https://img-cdn-sg.payermax.com/public/20260507-eff8a8a7-0105-44a2-ab8c-a8146a9a02dd.png)

#### 3.2.4  加签验签说明

1. **商户加签**

- **建议**：序列化成字符串 → 用该字符串加签 → 直接作为请求 Body 发送

- **禁止**：对象加签 + 框架二次序列化发送（字段顺序/空字段差异会导致验签失败）

::: warning  
注意加签格式区分：
1. 使用商户私钥进行加签的报文字符串要保证和http body中的字符串是一致的，否则会导致payermax验签不通过。比如下面两个json内容含义一致，但是因为格式化原因导致加签结果是不一致。
2. 您可以通过开发者[【自助加签小工具】](https://developer.payermax.com/devtool/rsa-sign)体验加签过程。

:::

- 格式化的json字符串：

```json
{
    "key1":"val1",
    "key2": "val2",
    "key3": "val3"
}

使用示例私钥加签结果：
"FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A=="
```

- 压缩的json字符串：

```json
{"key1":"val1","key2":"val2","key3":"val3"}

使用示例私钥加签结果：
"W/unZQUH9366PZDhYlCghA7q66VmPDBN/7OvVKhigQNfLJPxGnbhrH6JV4rYlsyfduPt4QKZalaafvs/tJ+CVOr2RGt3815hcAPB7MN/u4y3W+IfbwTXkT7gWujT652YDfMls2dwRCYun++DSOVFHkP8FUp8/Rb6e8CuKbA40RwfHfUTek24TMq0JmiYZDfRYbMUE30Pm8PXDAStoTTOqjJ+5zVAMWCzUwId1/P3iNWue+DUwCyLEA6tHFIJX8dUoSlbtjRs1p4Q8ahSFg5Dx+RORtLclnp8g38hgWFNsvcSuW3RXTkwIYmmbp5Qguw16af9P8Li82zI4M8TqgI08g=="
```

2. **商户验签**

- 商户验签时必须使用 PayerMax 平台公钥；

- 必须使用原始 HTTP Body 验签,不可使用反序列化后的对象进行验签；

平台升级可能新增/下线某些字段，框架反序列化可能丢失空字段或未知字段，导致验签失败。

## 4. 设置服务器IP白名单

如果您集成测试的网络环境，对访问IP有白名单安全限制，那么，请如下图所示提交工单，获取PayerMax服务器IP，并将其加入白名单。否则，PayerMax无法正常通过您[配置的回调地址](https://docs.payermax.com/202606-version/acquiring/start-integration/pre-integration-preparation.md#_3-1-配置异步通知地址)发起调用。

![](https://img-cdn-sg.payermax.com/public/20260507-4db53796-264f-4080-8d6b-05eb9e7433f2.png)

## 5. 开通支付方式

测试环境支付方式开通，登录[**PayerMax开发者中心**](https://developer.payermax.com/welcome)，进入 **基础设置** → **支付方式管理**，可以开通或关闭当前账号可使用的支付方式。

![](https://img-cdn-sg.payermax.com/public/20260507-0127e88c-419e-43eb-8633-5f8f87bfd3c8.png)

## 6. 集成验收

>在开发者平台发起 验收检查 通过后，可以配置产线环境的开发参数配置

![](https://img-cdn-sg.payermax.com/public/20260507-7fd5cd2a-1992-4e09-aee9-31aa193595ef.png)

### 6.1 发起功能性测试

::: tip  

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

:::

>请在测试环境发起一笔成功单和一笔失败单，并校验请求响应符合预期。  
>请求详情参考：

| 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)                                                                                                                           |