链接支付集成

该文档介绍PayerMax链接支付集成模式的集成流程。

链接支付时，商户先创建支付链接，用户支付时使用该支付链接进行支付。PayerMax提供两种方式使用链接支付功能：

基于PayerMax 商户平台（MMC）：无须集成任何API，只需注册开通MMC平台账号，即可创建和管理支付链接。
基于链接支付API：须集成若干API，商户可满足个性化、更灵活的链接创建和管理。

关于链接支付集成模式的更多信息，请查看集成模式概览。

1. 集成准备

注册开发者中心账号；
上传测试商户公钥，获取平台公钥、AppID、测试商户号等集成信息；
配置回调地址（WebHook），包括支付结果回调地址、退款结果回调地址等；
设置测试环境服务器IP白名单；
配置并开通相应支付方式；
查看不同环境的请求地址；
理解请求报文加签和验签的原理，用于生成每次HTTP请求Header的sign签名字符串。

2. 交互流程

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant User as 用户
    participant Client as 商户端
    participant Checkout as PayerMax收银页
    participant PMServer as PayerMax服务器
    participant Channel as 支付渠道
钱包/银行等

    %% 1. 创建链接阶段
    Client->>PMServer: 1.1 创建链接
通过PayerMax商户平台或 API
    PMServer-->>Client: 1.2 返回支付链接

    %% 2. 提供链接阶段
    Client-->>User: 2.1 提供链接
线上链接 或 线下二维码

    %% 3. 访问与支付阶段
    User->>Checkout: 3.1 访问链接
    Checkout->>Checkout: 3.2 渲染PayerMax收银页
加载订单信息
    User->>Checkout: 4.1 选择支付方式
点击支付
    Checkout->>PMServer: 4.2 支付请求
    PMServer->>Channel: 4.3 支付请求
    PMServer-->>Checkout: 4.4 支付结果
可能redirectUrl
    Checkout->>Checkout: 4.5 重定向，跳转至PayerMax支付结果页

    %% 4. 获取支付结果 (逻辑框)
    rect rgb(235, 245, 255)
        Note over Client, PMServer: 获取支付结果
        
        Note over Client, PMServer: 通过支付结果通知
        PMServer->>Client: 5.1 支付结果异步通知
        Client->>Client: 5.2 更新支付结果
        Client-->>PMServer: 5.3 返回响应

        Note over Client, PMServer: 通过支付订单查询
        Client->>PMServer: 6.1 查询支付交易单
        Client->>Client: 6.2 更新支付结果
    end

    %% 5. 链接管理阶段
    Client->>PMServer: 7.1 失效商户链接
    PMServer-->>Client: 7.2 返回请求结果
    Client->>PMServer: 8.1 查询支付链接详情
    PMServer-->>Client: 8.2 返回请求结果

3. 接口列表

关联交互时序	调用方向	接口PATH
1.1 创建链接	`商户` -> `PayerMax`	/createPaybylink
5.1 支付结果异步通知	`PayerMax` -> `商户`	/payLinkResultNotifyUrl
6.1 查询支付交易	`商户` -> `PayerMax`	/orderQuery
7.1 失效支付链接	`商户` -> `PayerMax`	/expirePaybylink
8.1 查询支付链接详情	`商户` -> `PayerMax`	/queryPaybylink

4. 环境信息

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

5. 集成步骤

5.1 创建支付链接

PayerMax提供两种方式创建支付链接。

5.1.1 通过商户后台创建

目前PayerMax允许商户登录商户平台（MMC）创建一次性支付链接并生成二维码，具体路径为：收单产品 → 链接支付 → 创建链接 。

分四步完成:

(a) 创建链接；

(b) 录入订单信息；

(d) 发送至用户完成支付（用户支付完成后后可通过登录mmc或API查询结果）。

5.1.2 通过API创建

商户可以集成/createPaybylink API 接口，通过系统调用创建支付链接。

/createPaybylink API 接口请求示例：

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/createPaybylink \
  --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": "2022-01-22T10:00:00.500+08:00",
  "appId": "6666c8b036a24579974497c2f9a33333",
  "merchantNo": "010213834784554",
  "data": {
    "merchantLinkId": "paylinktest001",
    "linkType": "ONETIME",
    "expiresTime": "86400",
    "country": "ID",
    "currency": "IDR",
    "totalAmount": "40000",
    "language": "en",
    "description": "冬季新款运动鞋",
    "linkDescription": "链接收款衣物鞋帽",
    "userInfo": {
      "userId": "98",
      "username": "孟艳"
    },
    "goodsDetails": [
      {
        "goodsName": "运动鞋",
        "goodsDescription": "冬季新款减震跑步运动鞋",
        "quantity": "2",
        "price": "20000",
        "goodsCurrency": "IDR",
        "showUrl": "http://dummyimage.com/400x400"
      }
    ],
    "merchantInfo": {
      "logoUrl": "http://dummyimage.com/logo/100x100",
      "contactEmail": "i.bbnettq@qq.com"
    },
    "notifyUrl": "http://srprnjkx.bv/ifgarmv"
  }
}'

/createPaybylink API 接口响应示例：

json

{
  "code": "APPLY_SUCCESS",
  "msg": "SUCCESS.",
  "data": {
    "linkId": "iwockllp",
    "merchantLinkId": "paylinktest001",
    "linkUrl": "https://www.payermax.link/qltvlsd",
    "linkStatus": "ACTIVE",
    "qrCodeUrl": "https://www.payermax.link/imagesqrcode",
    "expiresAt": "2022-11-01T10:00:00.000+08:00"
  }
}

5.2 失效支付链接

创建支付链接后，商户可以通过/expirePaybylink API 接口，主动将支付链接置为失效。

/expirePaybylink API 接口请求示例：

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/expirePaybylink \
  --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": "2022-01-22T10:00:00.500+08:00",
  "appId": "6666c8b036a24579974497c2f9a33333",
  "merchantNo": "010213834784554",
  "data": {
    "merchantLinkId": "paybylinktest001" # 支付链接ID
  }
}'

/expirePaybylink API 接口响应示例：

json

{
  "code": "APPLY_SUCCESS",
  "msg": "SUCCESS.",
  "data": {
    "linkId": "jyirffse",
    "merchantLinkId": "paybylinktest001", # 支付链接ID
    "linkStatus": "ACTIVE",
    "expiresAt": "2022-10-20T10:00:00.500+08:00",
    "linkUrl": "https://www.payermax.link/mtfbpomjw",
    "qrCodeUrl": "https://www.payermax.link/images/mtfbpomjwquc/qrcode"
  }
}

5.3 跳转PayerMax收银页

用户通过支付链接或二维码，可以跳转到PayerMax收银页。选择支付方式后，发起支付请求，支付流程和体验与收银台支付类似。

5.4 查询支付结果

参看收银台支付集成-5.4 获取支付结果。

5.5 查询链接详情

/queryPaybylink API 接口请求示例：

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/queryPaybylink \
  --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.1",
  "keyVersion": "1",
  "requestTime": "2022-01-22T10:00:00.500+08:00",
  "appId": "6666c8b036a24579974497c2f9a33333",
  "merchantNo": "010213834784554",
  "data": {
    "merchantLinkId": "paybylinktest001"
  }
}'

/queryPaybylink API 接口响应示例：

json

{
  "code": "APPLY_SUCCESS",
  "msg": "SUCCESS.",
  "data": {
    "linkId": "jyirffse",
    "merchantLinkId": "paybylinktest001",
    "totalAmount": "10000",
    "country": "ID",
    "currency": "IDR",
    "linkStatus": "ACTIVE",
    "expiresAt": "2022-11-22T10:00:00.500+08:00",
    "linkUrl": "https://www.payermax.link/mtfbpomjw",
    "qrCodeUrl": "https://www.payermax.link/images/mtfbpomjwquc/qrcode",
    "description": "冬季新款运动鞋",
    "linkDescription": "链接收款衣物鞋帽",
    "payByLinkInfo": [ # 支付信息。如果链接已支付，则非空。
      {
        "outTradeNo": "order2022001",
        "status": "SUCCESS",
        "completeAt": "2022-10-20T10:00:00.500+08:00",
        "paymentDetails": [
          {
            "targetOrg": "",
            "paymentMethodType": "CARD",
            "cardInfo": {
              "cardOrg": "VISA",
              "cardIdentifierNo": "625244*********9483"
            }
          }
        ]
      }
    ],
    "goodsDetails": { # 商品信息。如果链接已支付，则非空。
      "goodsId": "ZAK1002",
      "goodsName": "MacPro 14",
      "quantity": "1",
      "price": "14999.00",
      "showUrl": "https: //xxx.xxx.com/SKU1239438283"
    }
  }
}

6. 测试上线

在商户完成上述集成步骤后，可以发起实际支付请求进行初步测试验证，具体步骤请查看集成测试-发起测试。

在测试通过后，最终发布上线前，须联系PayerMax技术支持，提交测试的订单信息，以便于PayerMax检查请求日志和数据，确认您已经正确集成相关能力，具体步骤请查看集成测试-发起验收。

验收通过后，商户可以配置生产环境的集成信息，并准备开量事宜。

另外，在收单产品集成下有PayerMax支持的各类支付方式的集成文档，其中包含每种支付方式的测试上线说明。

7. 错误排除

测试或验收过程中的响应错误，可以查看错误排查-错误码。同时，在常见问题中，总结列举各类常见的问题及其处理方式。

您还可以直接联系PayerMax技术支持团队，咨询集成、测试、验收过程中的任何问题。

集成模式详细介绍

收单基础产品

CARD

GOOGLEPAY

APPLEPAY

订阅代扣

PayerMax管理订阅计划

商户管理订阅计划

非周期性代扣

前置组件

Tokenization

Auth-Capture

争议

业务风险管控

错误排查

支付方式分类介绍

国家支付方式详情

亚太

中亚

中东及非洲

欧洲

北美拉美

全球

链接支付集成 ​

1. 集成准备 ​

2. 交互流程 ​

3. 接口列表 ​

4. 环境信息 ​

5. 集成步骤 ​

5.1 创建支付链接 ​

5.1.1 通过商户后台创建 ​

5.1.2 通过API创建 ​

5.2 失效支付链接 ​

5.3 跳转PayerMax收银页 ​

5.4 查询支付结果 ​

5.5 查询链接详情 ​

6. 测试上线 ​

7. 错误排除 ​

链接支付集成

1. 集成准备

2. 交互流程

3. 接口列表

4. 环境信息

5. 集成步骤

5.1 创建支付链接

5.1.1 通过商户后台创建

5.1.2 通过API创建

5.2 失效支付链接

5.3 跳转PayerMax收银页

5.4 查询支付结果

5.5 查询链接详情

6. 测试上线

7. 错误排除