--- title: 预授权请款 permalink: /notes/zh/integrate/modify/Capture/ createTime: '2025/03/07 16:02:01' description: '说明如何对 AUTH_SUCCESS 的预授权交易发起请款，覆盖请求参数、结果通知、查询和状态处理建议。' --- 对于支持单独 Authorization / Capture 的支付方式（如国际信用卡支付），支付通常分为两个阶段： - [Authorization](/notes/zh/technicalterm/Authorization/)：验证买家支付信息并预留资金。 - [Capture](/notes/zh/technicalterm/Capture/)：将已预留的资金正式请款并结算。 如果您希望在发货、库存确认、风控复核等业务节点之后再扣款，则可使用手动 Capture，在原交易达到 `AUTH_SUCCESS` 后由商户服务端主动调用预授权请款接口。 ## 请款方式 PingPongCheckout 支持以下两种请款方式： 1. 自动 Capture：默认方式。 2. 手动 Capture：商户在支付请求中设置 `captureDelayHours=-1`，待交易达到 `AUTH_SUCCESS` 后，再主动调用预授权请款接口完成扣款。 如果您使用自动 Capture，本页的预授权请款接口通常无需额外接入；支付最终结果请以[交易异步通知](/notes/zh/notify/payment/notify/)或[交易查询](/notes/zh/checkout/api/getOne/)为准。下面的集成步骤主要针对手动 Capture。 ## 预授权请款流程 ```mermaid sequenceDiagram participant Server as 🏪 商户服务端 participant PP as 🔄 PingPongCheckout PP-->>Server: 1. 返回 AUTH_SUCCESS（同步响应或交易通知） Server->>PP: 2. 调用预授权请款 PP-->>Server: 3. 返回请款结果（SUCCESS / FAILED / PROCESSING） opt [status = PROCESSING] Server->>PP: 4. 调用预授权请款查询获取结果 PP-->>Server: 5. 返回请款状态 end PP-->>Server: 6. 推送预授权请款通知（成功 / 失败） ``` 流程说明： 1. 商户通过支付同步响应或交易异步通知确认原交易状态达到 `AUTH_SUCCESS`。 2. 商户服务端调用 [预授权请款](/notes/zh/checkout/api/modifications/capture/) 发起请款。 3. 同步响应可能直接返回 `SUCCESS`、`FAILED` 或 `PROCESSING`。 4. 如果同步响应为 `PROCESSING`，商户可调用 [预授权请款查询](/notes/zh/checkout/api/getCapture/) 主动查询请款状态。 5. PingPongCheckout 也会通过 [预授权请款通知](/notes/zh/notify/status/captureNotify/) 返回最终请款结果。 ## 请款状态机 预授权请款只能在原支付单处于 `AUTH_SUCCESS` 时发起。请款成功后，原支付单完成最终扣款并进入 `SUCCESS`；请款失败时，请以请款对象的 `status` 记录失败原因，并结合业务场景决定是否重新发起请款或改为撤销预授权。 ```mermaid flowchart LR ORIGINAL[原支付单状态: AUTH_SUCCESS] -.-> START((发起预授权请款)) START --> PROCESSING[PROCESSING] PROCESSING -->|请款成功| SUCCESS[SUCCESS] PROCESSING -.->|请款失败| FAILED[FAILED] SUCCESS --> END((END)) FAILED --> END ``` ## 集成步骤 请按以下步骤完成集成： 1. [发起预授权请款请求](#步骤-1-发起预授权请款请求) 2. [获取预授权请款结果](#步骤-2-获取预授权请款结果) ### 步骤 1：发起预授权请款请求 授权成功后，调用 [预授权请款](/notes/zh/checkout/api/modifications/capture/) API 发起请款。请根据原交易流水号和本次请款流水号组装请求；如果希望在 `PROCESSING` 场景下异步接收最终结果，建议正确配置 `notificationUrl`。 预授权请款请求关键字段： | 字段 | 必填 | 说明 | |:---|:---:|:---| | `bizContent.merchantTransactionId` | 是 | 商户网站的原交易流水号 | | `bizContent.merchantCaptureId` | 是 | 商户侧预授权请款流水号，全局唯一 | | `bizContent.amount` | 是 | 请款金额，应与原授权金额一致 | | `bizContent.currency` | 是 | 交易币种 | | `bizContent.notificationUrl` | 否 | 用于接收请款结果的异步通知地址，建议配置 | 有关完整参数的更多信息，请参阅[预授权请款接口](/notes/zh/checkout/api/modifications/capture/)。 预授权请款请求示例： ```json { "accId": "2023042011040310224447", "clientId": "2023042011040310224", "signType": "SHA256", "sign": "{{Sign}}", "version": "1.0", "bizContent": { "merchantCaptureId": "CAPTURE_202606260001", "merchantTransactionId": "AUTH_202606260001", "amount": 100, "currency": "USD", "notificationUrl": "https://www.example.com/capture/notify" } } ``` ::: warning 注意 - 仅对已授权且尚未扣款的交易发起预授权请款。 - 下单阶段需已启用手动 Capture，即 `captureDelayHours=-1`；当前暂不支持部分 Capture，请款金额必须等于原授权金额。 - 并非所有支付方式都支持单独 Authorization / Capture；如果无法确认原交易当前是否已达到 `AUTH_SUCCESS`，可先调用 [交易查询](/notes/zh/checkout/api/getOne/) 判断当前是否可以执行预授权请款。 - [预授权请款](/notes/zh/checkout/api/modifications/capture/) API 基于 `merchantCaptureId` 做幂等控制：同一笔请款请求重复提交时请保持 `merchantCaptureId` 不变；如果上一笔请款请求失败且需要重新发起，请使用新的 `merchantCaptureId`。 ::: 预授权请款响应关键字段： | 字段 | 说明 | |:---|:---| | `bizContent.merchantCaptureId` | 商户侧预授权请款流水号 | | `bizContent.merchantTransactionId` | 商户网站的原交易流水号 | | `bizContent.transactionId` | PingPong 原交易流水号 | | `bizContent.status` | 请款状态，可能为 `SUCCESS`、`FAILED` 或 `PROCESSING` | | `bizContent.captureEndingTime` | 请款到达终态时间；如果同步已返回终态，可用于记录完成时间 | 预授权请款响应示例： ```json { "accId": "2023042011040310224447", "bizContent": "{\"amount\":\"100.000000\",\"merchantCaptureId\":\"CAPTURE_202606260001\",\"captureTime\":\"1715047466000\",\"transactionId\":\"2024050750046460\",\"captureEndingTime\":\"1715047468242\",\"merchantTransactionId\":\"AUTH_202606260001\",\"currency\":\"USD\",\"status\":\"SUCCESS\"}", "clientId": "2023042011040310224", "code": "000000", "description": "Transaction succeeded", "sign": "5033C47D3A1CF3E19A4B0EE0E566CE723D67E8BA236B828829BDE586CA999D2A", "signType": "SHA256" } ``` 调用预授权请款接口后，同步响应中的 `status` 可能为以下值： - `SUCCESS`：请款成功，资金正式完成扣款 - `FAILED`：请款失败，应结合错误原因判断是否允许重试 - `PROCESSING`：请款处理中，需继续等待请款通知或主动查询 ### 步骤 2：获取预授权请款结果 请款发起后，商户应通过以下方式确认最终结果： 1. 接收 [预授权请款通知](/notes/zh/notify/status/captureNotify/) 2. 如异步通知延迟、未达、网络异常或需要再次核验结果，可主动调用 [预授权请款查询](/notes/zh/checkout/api/getCapture/) 如果您通过异步通知接收结果，可参考以下通知示例与处理方式。 预授权请款通知示例： ```json { "clientId": "2023042011040310224", "code": "000000", "bizContent": "{\"amount\":\"100.000000\",\"merchantCaptureId\":\"CAPTURE_202606260001\",\"captureTime\":\"1715047466000\",\"transactionId\":\"2024050750046460\",\"captureEndingTime\":\"1715047468296\",\"notifyType\":\"CAPTURE\",\"merchantTransactionId\":\"AUTH_202606260001\",\"currency\":\"USD\",\"status\":\"SUCCESS\"}", "sign": "7B9F45E93C79D8C2341558FBB735A7AB7FA3AF2CBAA64D2C0411E4F698552747", "accId": "2023042011040310224447", "description": "Transaction succeeded", "signType": "SHA256" } ``` 在预授权请款异步通知场景下，`status` 会返回最终请款结果，即 `SUCCESS` 或 `FAILED`。收到 `SUCCESS` 时可将请款更新为成功；收到 `FAILED` 时可将请款更新为失败。 收到通知后，商户服务端建议按以下方式处理： - 先返回 HTTP `2xx` 确认已接收，避免触发重复通知 - 再根据通知中的 `status` 更新请款结果，并执行对应业务处理 通知响应示例： ```http HTTP/1.1 200 OK Content-Type: text/plain; charset=UTF-8 Content-Length: 2 OK ``` 如果异步通知延迟、未达，或商户侧因网络异常、回调处理失败、结果核验等原因暂时无法确认最终状态，可主动调用 [预授权请款查询](/notes/zh/checkout/api/getCapture/) 获取请款结果。 预授权请款查询请求关键字段： | 字段 | 必填 | 说明 | |:---|:---:|:---| | `bizContent.merchantCaptureId` | 是 | 商户侧预授权请款流水号，全局唯一 | | `bizContent.merchantTransactionId` | 是 | 商户网站的原交易流水号 | 有关完整参数的更多信息，请参阅[预授权请款查询接口](/notes/zh/checkout/api/getCapture/)。 预授权请款查询请求示例： ```json { "accId": "2018092714313010016291", "clientId": "2018092714313010016", "signType": "SHA256", "sign": "{{Sign}}", "version": "1.0", "bizContent": { "merchantCaptureId": "CAPTURE_202606260001", "merchantTransactionId": "AUTH_202606260001" } } ``` 预授权请款查询响应示例： ```json { "accId": "2023060217493010231446", "bizContent": "{\"amount\":\"100.000000\",\"captureTime\":\"1715047466000\",\"resultCode\":\"000000\",\"transactionId\":\"2024050750046460\",\"captureEndingTime\":\"1715047468242\",\"merchantTransactionId\":\"AUTH_202606260001\",\"currency\":\"USD\",\"resultMessage\":\"Transaction succeeded\",\"status\":\"SUCCESS\"}", "clientId": "2023060217493010231", "code": "001000", "description": "Successful request", "sign": "C550628F93D95A84AE89D18264CD9184520896908CEEEE77829F72196036A0AC", "signType": "SHA256" } ``` 预授权请款查询响应关键字段： | 字段 | 说明 | |:---|:---| | `bizContent.merchantTransactionId` | 商户订单号，用于关联原授权交易 | | `bizContent.transactionId` | PingPong 交易流水号 | | `bizContent.status` | 请款状态，可能为 `SUCCESS`、`FAILED` 或 `PROCESSING` | | `bizContent.captureEndingTime` | 请款到达终态时间，可用于记录最终完成时间 | 预授权请款查询响应中的 `status` 可能返回 `SUCCESS`、`FAILED` 或 `PROCESSING`。如果查询结果为 `PROCESSING`，说明请款结果尚未最终确认，建议稍后重试查询，或继续等待请款通知。 ::: note 提示 预授权请款查询请在同步响应返回之后调用；若查询过早，可能会出现查询异常。 :::