Auth-Capture 集成

1. 业务介绍

Auth-Capture模式和Sales模式都是支付处理（常见于卡支付）的基本交互模式：

Sales 模式（一次交互）：用户支付时，同时完成授权与扣款，资金立即从用户银行卡中扣除；
Auth-Capture 模式（二次交互）：交易分为两步进行，首先是授权（Authorization），冻结用户的资金；之后再由商户发起请款（Capture），实际完成扣款。

1.1 授权 (Authorization)

商家/机构向用户的发卡行请求授权特定金额。

发卡行对用户的银行卡进行校验，如：资金/信用额度是否充足、卡片是否有效（未被冻结或挂失）；
授权成功，发卡行会对该笔资金进行冻结；
此时尚未有资金流发生，只是临时冻结；
授权在有效期（7天）内如果未被请款，则会过期失效，冻结金额释放。

1.2 请款 (Capture)

商家确认完成交易后，请求转移已授权的资金；
资金流发生：从持卡人的银行账户扣款；
当前支持一次请款，不支持超额请款。

2. 适用场景

酒店与旅游行业：用户预订酒店或租车时，先通过授权冻结信用卡资金作为押金，待用户离店或还车时，根据实际消费金额发起请款，完成扣款；
充电宝租借场景：用户租借充电宝时，商户通过授权冻结充电宝押金，用户归还充电宝时，根据实际消费金额发起请款，完成扣款；
大型电商平台：消费者在电商平台下单后，支付时先进行授权，待商家发货后进行请款，完成支付流程。

3. 集成准备

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

4. 交互流程

5. 接口列表

关联交互时序	调用方向	接口PATH
1.3 创建支付，调用收银台下单接口	`商户` -> `PayerMax`	/orderAndPay
5.1 支付结果异步通知	`PayerMax` -> `商户`	/authResultNotifyUrl
6.1 查询支付交易	`商户` -> `PayerMax`	/orderQuery
7.1 发起请款	`商户` -> `PayerMax`	/capture
8.1 请款结果异步通知	`PayerMax` -> `商户`	/captureResultNotifyUrl
9.1 发起撤销	`商户` -> `PayerMax`	/cancel
10.1 撤销结果异步通知	`PayerMax` -> `商户`	/cancelResultNotifyUrl

6. 环境信息

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

7. 集成步骤

7.1 授权申请

授权模式分为三种不同集成模式授权：

【收银台授权】
【纯API授权】
【前置组件授权】

7.2 获取授权结果

授权结果集成参考获取支付结果集成对接步骤，功能相同。若使用了Auth-capture功能，在支付结果通知或支付订单查询返回中，则会返回如下字段：

字段名称	字段类型	是否必填	描述
`captureMode`	`string`	`是`	请款模式：`MANUAL`
`authorizationType`	`string`	`否`	授权类型：`PRE_AUTH`，`FINAL_AUTH`；默认为`FINAL_AUTH`

7.2.1 授权通知

授权通知可查看授权通知/authResultNotifyUrl API。

示例如下：

json

{
  "code": "APPLY_SUCCESS",
  "msg": "",
  "keyVersion": "1",
  "appId": "3b242b56a8b64274bcc37dac281120e3",
  "merchantNo": "020213827212251",
  "notifyTime": "2022-01-17T09:33:54.540+00:00",
  "notifyType": "PAYMENT",
  "data": {
    "outTradeNo": "P1642410680681",
    "tradeToken": "T2024062702289232000001",
    "totalAmount": 10000,
    "captureMode":"MANUAL",
    "authorizationType":"FINAL_AUTH",
    "currency": "IDR",
    "country": "ID",
    "status": "SUCCESS",
    "completeTime": "2023-10-20T03:28:23.092Z",
    "paymentDetails": [
      {
        "paymentMethodType": "CARD"
      }
    ],
    "reference": "020213827524152"
  }
}

7.2.2 通过支付订单查询

商户还可以通过调用交易查询/orderQuery API，获取支付结果。

交易查询/orderQuery API 接口请求示例：

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderQuery \
  --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-17T07:51:15.597+00:00",
  "appId": "a0dddd1f622243cb9aa1b676e808b5f8",
  "merchantNo": "02021382719993",
  "data": {
    "outTradeNo": "P1642410680681" # 商户单号
  }
}'

交易查询/orderQuery API 接口响应示例：

json

{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "reference": "reference查询和回调返回",
    "country": "SA",
    "totalAmount": 10,
    "outTradeNo": "DEVTest1669616467952",
    "currency": "SAR",
    "channelNo": "DMCP000000000177005",
    "thirdChannelNo": "4ikqJ6ktEqyRawE1dvqb9c",
    "paymentCode": "2312121212",
    "tradeToken": "T2024062702289232000001",
    "completeTime": "2023-10-20T03:28:23.092Z",
    "captureMode":"MANUAL",
    "authorizationType":"FINAL_AUTH",
    "paymentDetails": [
      {
        "targetOrg": "*",
        "cardInfo": {
          "cardOrg": "VISA",
          "country": "SA",
          "cardIdentifierNo": "400555******0001",
          "cardIdentifierName": "**ngwei"
        },
        "payAmount": 10,
        "exchangeRate": "1",
        "paymentMethod": "CARD",
        "payCurrency": "SAR",
        "paymentMethodType": "CARD"
      }
    ],
    "fees": {
      "merFee": {
        "url": "https://cashier-n-test-new.payermax.com/static/invoice.html?country=AE&merchantNo=P01010113843429&timestamp=1687769788704&version=1.0&orderTaxToken=XWXFKKBOPExplK4aX0r7wgiMtiAMLBKObPFdCMpM9HmCq3AAOob%252BcAZOkP27Kh3W",
        "amount": "100",
        "currency": "SAR"
      }
    },
    "status": "SUCCESS",
    "resultMsg": ""
  }
}

7.3 发起请款

在授权成功后，当业务需要请款时，需再发起一笔请款请求。接口内容可查看请款/capture API 接口。

注意：

原授权必须是授权成功；
以原订单号 outTradeNo 发起请款请求，并传入需要请款的金额。

关键参数：

字段名称	字段类型	是否必填	描述
`requestId`	`string`	`是`	商户请款请求的唯一id
`outTradeNo`	`string`	`是`	商户订单号
`currency`	`string`	`是`	请款币种（与下单币种一致）
`amount`	`number`	`是`	请款金额（不能超过授权金额）

请款/capture API 接口请求示例：

{
    "version": "1.4",
    "keyVersion": "1",
    "requestTime": "2024-11-06T11:56:13.000+08:00",
    "appId": "8f8b0895b60f41abbdb05405052971c8",
    "merchantNo": "P01010114178824",
    "data": {
        "requestId": "xxxxx",
        "outTradeNo": "xxxxxxxx",
        "currency": "USD",
        "amount": 100
    }
}

请款/capture API 接口响应示例：

{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "captureNo": "20230806235954ED7856775040587834005", // paymermax 唯一的请款单号
        "requestId":"xxxxx", // 本次请求受理的requestId
        "outTradeNo":"xxxxxxxx", 
        "amount":10,
        "currency":"SAR"
        "status": "PENDING", // SUCCESS FAILED
        "isFinal": true,
        "createdTime": "2023-08-06T23:50:59 +0000",
        "succeededTime": null, // 成功时间
        "failedTime": null, //  失败时间
        "errorCode": null,  // 失败原因 
        "errorMsg": null
    }
}

当请款接口同步响应请款结果，请款状态如下：

状态	描述	备注
`FAILED`	失败	请款失败
`PENDING`	处理中	请款中
`SUCCESS`	成功	请款完成

注意：

目前只支持请款 一次，请款金额小于等于授予金额即可。暂不支持多次请款。

7.4 获取请款结果

请款成功或失败后，也会回调请款状态通知到商户的服务器.通知内容可查看请款通知/captureResultNotifyUrl API 接口。集成回调通知可参考获取支付结果集成对接步骤。

关键参数：

字段名称	字段类型	是否必填	描述
`notifyType`	`string`	`否`	通知类型：`CAPTURE`

当 notifyType = CAPTURE 时，为请款的回调，示例如下：

json

{
    "keyVersion": "1",
    "appId": "5f843bfc8cec49c2b8e9e99847325548",
    "merchantNo": "P01010114418097",
    "notifyTime": "2023-07-23T00:00:01 +0000",
    "notifyType": "CAPTURE", // 请款的类型
    "data": { 
        "captureNo": "20230806235954ED7856775040587834005", // paymermax 唯一的请款单号
        "requestId":"xxxxx", // 本次请求受理的requestId
        "outTradeNo":"xxxxxxxx", 
        "status": "SUCCESS", // SUCCESS FAILED
        "isFinal": true,
        "createdTime": "2023-08-06T23:50:59 +0000",
        "succeededTime": "2023-08-06T23:50:59 +0000", // 成功时间
        "failedTime": null, //  失败时间
        "errorCode": null,  // 失败原因 
        "errorMsg": null
      }
}

7.5 发起撤销

发起撤销时，必须是授权成功并且没有发起请款。可查看撤销/cancel API 接口。

以原订单号 outTradeNo 发起撤销请求，关键参数为：

字段名称	字段类型	是否必填	描述
`requestId`	`string`	`是`	商户撤销请求的唯一id
`outTradeNo`	`string`	`是`	商户订单号

撤销是全额撤销，不需要指定金额。示例如下：

json

// 入参
{
"version": "1.4",
"keyVersion": "1",
"requestTime": "2024-11-06T11:56:13.000+08:00",
"appId": "8f8b0895b60f41abbdb05405052971c8",
"merchantNo": "P01010114178824",
"data": {
    "requestId": "xxxxx", // 本次请求单号
    "outTradeNo": "xxxxxxxx", // 原单号
  }
}

json

// 出参
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "cancelNo": "20230806235954ED7856775040587834005", // PayerMax 唯一的撤销单号
        "requestId":"xxxxx", // 本次请求受理的requestId
        "outTradeNo":"xxxxxxxx", 
        "status": "SUCCESS", // SUCCESS FAILED
        "createdTime": "2023-08-06T23:50:59 +0000",
        "succeededTime": null, // 成功时间
        "failedTime": null, //  失败时间
        "errorCode": null,  // 失败原因 
        "errorMsg": null
    }
}

调用撤销接口会同步响应撤销结果，撤销状态为：

状态	描述	备注
`FAILED`	失败	撤销失败
`PENDING`	处理中	撤销中
`SUCCESS`	成功	撤销成功

7.6 获取撤销结果

撤销成功或失败后，也会回调撤销状态通知到商户的服务器，通知内容可查看撤销通知/cancelResultNotifyUrl API 接口。集成回调通知可参考获取支付结果集成对接步骤。

关键参数：

字段名称	字段类型	是否必填	描述
`notifyType`	`string`	`是`	通知类型：`CANCEL`

当 notifyType=CANCEL 时，为撤销的回调：

json

{
    "keyVersion": "1",
    "appId": "5f843bfc8cec49c2b8e9e99847325548",
    "merchantNo": "P01010114418097",
    "notifyTime": "2023-07-23T00:00:01 +0000",
    "notifyType": "CANCEL", 
    "data": { 
        "cancelNo": "20230806235954ED7856775040587834005", // paymermax 唯一的请款单号
        "requestId":"xxxxx", // 本次请求受理的requestId
        "outTradeNo":"xxxxxxxx", 
        "status": "SUCCESS", // SUCCESS FAILED
        "createdTime": "2023-08-06T23:50:59 +0000",
        "succeededTime": "2023-08-06T23:50:59 +0000", // 成功时间
        "failedTime": null, //  失败时间
        "errorCode": null,  // 失败原因 
        "errorMsg": null
      }
}

8. 测试上线

以下介绍Auth-Capture的集成测试模拟规则。

8.1 授权测试

授权测试可参考发起测试。

注意：

请款、撤销必须在授权成功后才可发起。

8.2 请款测试

请款接口参数amount指定以下值可以mock请款结果：

失败：amount = 500,1000,1500,2000;
PENDING：amount = 6000,900;
成功：其他金额。

8.3 撤销测试

授权接口参数totalAmount指定以下值可以mock撤销结果：

失败：amount = 2000,2500;
PENDING：amount = 6500;
成功：其他金额。

集成模式概览

收单基础产品

CARD

GOOGLEPAY

APPLEPAY

订阅代扣

前置组件

争议

业务风险管控

错误排查

API付款

支付方式列表

欧洲

Auth-Capture 集成 ​

1. 业务介绍 ​

1.1 授权 (Authorization) ​

1.2 请款 (Capture) ​

2. 适用场景 ​

3. 集成准备 ​

4. 交互流程 ​

5. 接口列表 ​

6. 环境信息 ​

7. 集成步骤 ​

7.1 授权申请 ​

7.2 获取授权结果 ​

7.2.1 授权通知 ​

7.2.2 通过支付订单查询 ​

7.3 发起请款 ​

7.4 获取请款结果 ​

7.5 发起撤销 ​

7.6 获取撤销结果 ​

8. 测试上线 ​

8.1 授权测试 ​

8.2 请款测试 ​

8.3 撤销测试 ​

Auth-Capture 集成

1. 业务介绍

1.1 授权 (Authorization)

1.2 请款 (Capture)

2. 适用场景

3. 集成准备

4. 交互流程

5. 接口列表

6. 环境信息

7. 集成步骤

7.1 授权申请

7.2 获取授权结果

7.2.1 授权通知

7.2.2 通过支付订单查询

7.3 发起请款

7.4 获取请款结果

7.5 发起撤销

7.6 获取撤销结果

8. 测试上线

8.1 授权测试

8.2 请款测试

8.3 撤销测试