接入前准备

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

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. 注册成为开发者

2.1 邮箱注册

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

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

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

2.2 测试参数说明

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

会员号、商户号、appId：系统自动生成供开发者测试环境使用的一套参数，PayerMax接口请求的必填信息；
密钥类型：RSA；
公钥上传：开发者需要上传商户公钥给PayerMax，用于验证商户签名，公私钥说明查看3.2密钥说明及配置；
邀请协作者：被邀请人和您共用同一个开发者平台商户号；
绑定产线商户号：绑定产线商户号完成自助验收，才可以在商户平台配置获取对应产线商户号开发参数。（绑定正式商户号，需要产线商户号管理员分配操作员权限）

3. 参数配置及说明

3.1 配置异步通知地址

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

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

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

3.2 密钥说明及配置

3.2.1 密钥说明

密钥算法：RSA

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

签名算法：SHA256WithRSA

密钥长度：2048

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

%%{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加签报文的签名。

在线快速生成密钥对

点击 PayerMax密钥生成工具快速生成密钥对。

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的公钥。

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

下载平台公钥：

3.2.4 加签验签说明

商户加签

建议：序列化成字符串 → 用该字符串加签 → 直接作为请求 Body 发送
禁止：对象加签 + 框架二次序列化发送（字段顺序/空字段差异会导致验签失败）

注意加签格式区分：

使用商户私钥进行加签的报文字符串要保证和http body中的字符串是一致的，否则会导致payerma x验签不通过。比如下面两个json内容含义一致，但是因为格式化原因导致加签结果是不一致。
您可以通过开发者【自助加签小工具】体验加签过程。

格式化的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=="

商户验签

商户验签时必须使用 PayerMax 平台公钥；
必须使用原始 HTTP Body 验签,不可使用反序列化后的对象进行验签；

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

4. 设置服务器IP白名单

如果您集成测试的网络环境，对访问IP有白名单安全限制，那么，请如下图所示提交工单，获取PayerMax服务器IP，并将其加入白名单。否则，PayerMax无法正常通过您配置的回调地址发起调用。

5. 开通支付方式

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

6. 集成验收

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

6.1 发起功能性测试

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

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

PayerMax产品		对接模式	集成文档
全球收单	标准收单	收银台模式	收银台-全量收银台
			收银台-指定支付方式
		前置组件	前置组件-CARD
			前置组件-ApplePay
			前置组件-GooglePay
		纯API	纯API-CARD
			纯API-GooglePay
			纯API-ApplePay
			纯API-APM
	订阅代扣	/	PayerMax管理订阅计划
			商户管理订阅计划
			非周期性代扣
全球付款	全球付款	API付款	API付款
		平台付款	商户平台批量付款，商户平台单笔付款
全球收款	本地收款	/	本地收款流程

集成模式详细介绍

收单基础产品

CARD

GOOGLEPAY

APPLEPAY

订阅代扣

PayerMax管理订阅计划

商户管理订阅计划

非周期性代扣

前置组件

Tokenization

Auth-Capture

争议

业务风险管控

错误排查

支付方式分类介绍

国家支付方式详情

亚太

中亚

中东及非洲

欧洲

北美拉美

全球

接入前准备 ​

1. 整体流程 ​

2. 注册成为开发者 ​

2.1 邮箱注册 ​

2.2 测试参数说明 ​

3. 参数配置及说明 ​

3.1 配置异步通知地址 ​

3.2 密钥说明及配置 ​

3.2.1 密钥说明 ​

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

3.2.3 密钥配置 ​

3.2.4 加签验签说明 ​

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

5. 开通支付方式 ​

6. 集成验收 ​

6.1 发起功能性测试 ​

接入前准备

1. 整体流程

2. 注册成为开发者

2.1 邮箱注册

2.2 测试参数说明

3. 参数配置及说明

3.1 配置异步通知地址

3.2 密钥说明及配置

3.2.1 密钥说明

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

3.2.3 密钥配置

3.2.4 加签验签说明

4. 设置服务器IP白名单

5. 开通支付方式

6. 集成验收

6.1 发起功能性测试