链接支付集成

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

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

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

关于链接支付集成模式的更多信息，参看【产品介绍 - 集成模式】。

1. 集成准备

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

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）后，可登录PayerMax 商户平台（MMC），进入 收单管理 → 链接支付 → 创建链接，创建一次性支付链接并生成二维码，如下图所示。

创建支付链接后，商户还需要录入订单信息，包括收单国家/地区、订单金额、订单描述、链接有效期、链接备注等。

订单金额：商品单价 * 商品数量；
订单描述：支付时，展示给用户，可以是商品的描述信息或者收款目的等；
链接备注：不展示给用户，会通过支付结果通知 API 的linkDescription字段，返回给商户。

信息填写完毕后，就可以生成支付链接及其二维码，如下图所示。

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技术支持团队，咨询集成、测试、验收过程中的任何问题。

8. 关联文档

【按照支付方式集成】

集成

收银台支付

支付方式列表

纯API支付

前置组件

卡支付

ApplePay

GooglePay

订阅代扣

Tokenization支付

链接支付

相关能力（退款/争议等）

交易结果

争议

业务风险管控

集成

API付款

支付方式列表

欧洲

相关能力（交易查询/通知）

交易对账

全球收单

链接支付集成

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. 错误排查

8. 关联文档

收银台支付

支付方式列表

纯API支付

前置组件

卡支付

ApplePay

GooglePay

订阅代扣

Tokenization支付

链接支付

交易结果

争议

业务风险管控

API付款

支付方式列表

欧洲

链接支付集成 ​

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. 错误排查 ​

8. 关联文档 ​

链接支付集成

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. 错误排查

8. 关联文档