# 链接支付集成

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

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

+ **基于**[**PayerMax 商户平台（MMC）**](https://mmc.payermax.com/#/login)：无须集成任何API，只需注册开通MMC平台账号，即可创建和管理支付链接。

+ **基于链接支付API**：须集成若干API，商户可满足个性化、更灵活的链接创建和管理。

## 1. 集成准备

+ [注册开发者中心账号](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-2-注册成为开发者)；

+ [上传测试商户公钥](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-4-1-配置测试环境的密钥信息)，获取平台公钥、AppID、测试商户号等集成信息；

+ [配置回调地址（WebHook）](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-4-2-配置测试环境的回调地址)，包括支付结果回调地址、退款结果回调地址等；

+ [设置测试环境服务器IP白名单](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-5-设置测试环境的服务器ip白名单)；

+ [配置并开通相应支付方式](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-6-开通集成的支付方式)；

+ [查看不同环境的请求地址](https://docs.payermax.com/202606-version/developer/integration-guide.md#_2-环境信息)；

+ [理解请求报文加签和验签的原理](https://docs.payermax.com/202606-version/developer/config-settings.md)，用于生成每次HTTP请求Header的`sign`签名字符串。

## 2. 交互流程

```mermaid
%%{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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-createPaybylink/post) |
| 5.1 支付结果异步通知 | `PayerMax` -> `商户` | [/payLinkResultNotifyUrl](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/payLinkResultNotifyUrl/post)             |
| 6.1 查询支付交易     | `商户` -> `PayerMax` | [/orderQuery](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderQuery/post)           |
| 7.1 失效支付链接     | `商户` -> `PayerMax` | [/expirePaybylink](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-expirePaybylink/post) |
| 8.1 查询支付链接详情 | `商户` -> `PayerMax` | [/queryPaybylink](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-queryPaybylink/post)   |

## 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）**](https://mmc.payermax.com/#/login)创建一次性支付链接并生成二维码，具体路径为：**收单产品** → **链接支付** → **创建链接** 。

分四步完成:

  (a) 创建链接；
  
  (b) 录入订单信息；
  
  (c) 生成链接/二维码；
  
  (d) 发送至用户完成支付（用户支付完成后后可通过登录mmc或API查询结果）。

#### 5.1.2 通过API创建

商户可以集成[/createPaybylink API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-createPaybylink/post) 接口，通过系统调用创建支付链接。

[/createPaybylink API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-createPaybylink/post) 接口请求示例：

``` js
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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-createPaybylink/post) 接口响应示例：

``` 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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-expirePaybylink/post) 接口，主动将支付链接置为失效。

[/expirePaybylink API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-expirePaybylink/post) 接口请求示例：

``` js
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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-expirePaybylink/post) 接口响应示例：

``` 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收银页。选择支付方式后，发起支付请求，支付流程和体验与[收银台支付](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/cashier-payment/payermax-checkout.md)类似。

### 5.4 查询支付结果

参看[获取支付结果](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/cashier-payment/payermax-checkout.md#_4-4-获取支付结果)。

### 5.5 查询链接详情

[/queryPaybylink API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-queryPaybylink/post) 接口请求示例：

``` js
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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-queryPaybylink/post) 接口响应示例：

``` 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. 测试上线

在商户完成上述集成步骤后，可以发起实际支付请求进行初步测试验证，具体步骤请查看[集成测试-发起测试](https://docs.payermax.com/202606-version/acquiring/integration-testing-and-troubleshooting/start-a-test.md)。

在测试通过后，最终发布上线前，须联系PayerMax技术支持，提交测试的订单信息，以便于PayerMax检查请求日志和数据，确认您已经正确集成相关能力，具体步骤请查看[集成测试-发起验收](https://docs.payermax.com/202606-version/acquiring/start-integration/golive-confirmation.md)。

验收通过后，商户可以[配置生产环境的集成信息](https://docs.payermax.com/202606-version/developer/integration-guide.md#_7-3-配置生产环境的集成信息)，并准备开量事宜。

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

## 7. 错误排除

测试或验收过程中的响应错误，可以查看[错误排查-错误码](https://docs.payermax.com/202606-version/acquiring/integration-testing-and-troubleshooting/troubleshooting/error-code.md)。同时，在[常见问题](https://docs.payermax.com/202606-version/appendix/faq/collection/cashier-direct-api.md)中，总结列举各类常见的问题及其处理方式。

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