预授权请款

约 2002 字大约 7 分钟

View as Markdown

2025-03-07

对于支持单独 Authorization / Capture 的支付方式（如国际信用卡支付），支付通常分为两个阶段：

Authorization：验证买家支付信息并预留资金。
Capture：将已预留的资金正式请款并结算。

如果您希望在发货、库存确认、风控复核等业务节点之后再扣款，则可使用手动 Capture，在原交易达到 AUTH_SUCCESS 后由商户服务端主动调用预授权请款接口。

请款方式

PingPongCheckout 支持以下两种请款方式：

自动 Capture：默认方式。
手动 Capture：商户在支付请求中设置 captureDelayHours=-1，待交易达到 AUTH_SUCCESS 后，再主动调用预授权请款接口完成扣款。

预授权自交易达到 AUTH_SUCCESS 起 7 天内有效，到期未完成请款的，授权将自动撤销。使用手动 Capture 时，请在有效期内发起请款。

如果您使用自动 Capture，本页的预授权请款接口通常无需额外接入；支付最终结果请以交易异步通知或交易查询为准。下面的集成步骤主要针对手动 Capture。

预授权请款流程

流程说明：

商户通过支付同步响应或交易异步通知确认原交易状态达到 AUTH_SUCCESS。
商户服务端调用预授权请款发起请款。
同步响应可能直接返回 SUCCESS、FAILED 或 PROCESSING。
如果同步响应为 PROCESSING，商户可调用预授权请款查询主动查询请款状态。
PingPongCheckout 也会通过预授权请款通知返回最终请款结果。

请款状态机

预授权请款只能在原支付单处于 AUTH_SUCCESS 时发起。请款成功后，原支付单完成最终扣款并进入 SUCCESS；请款失败时，请以请款对象的 status 记录失败原因，并结合业务场景决定是否重新发起请款或改为撤销预授权。

集成步骤

请按以下步骤完成集成：

发起预授权请款请求
获取预授权请款结果

步骤 1：发起预授权请款请求

授权成功后，调用预授权请款 API 发起请款。请根据原交易流水号和本次请款流水号组装请求；如果希望在 PROCESSING 场景下异步接收最终结果，建议正确配置 notificationUrl。

预授权请款请求关键字段：

字段	必填	说明
`bizContent.merchantTransactionId`	是	商户网站的原交易流水号
`bizContent.merchantCaptureId`	是	商户侧预授权请款流水号，全局唯一
`bizContent.amount`	是	请款金额，应与原授权金额一致
`bizContent.currency`	是	交易币种
`bizContent.notificationUrl`	否	用于接收请款结果的异步通知地址，建议配置

有关完整参数的更多信息，请参阅预授权请款接口。

预授权请款请求示例：

{
  "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"
 }
}

注意

预授权有效期为 7 天，到期未请款将自动撤销授权。
仅对已授权且尚未扣款的交易发起预授权请款。
下单阶段需已启用手动 Capture，即 captureDelayHours=-1；当前暂不支持部分 Capture，请款金额必须等于原授权金额。
并非所有支付方式都支持单独 Authorization / Capture；如果无法确认原交易当前是否已达到 AUTH_SUCCESS，可先调用交易查询判断当前是否可以执行预授权请款。
预授权请款 API 基于 merchantCaptureId 做幂等控制：同一笔请款请求重复提交时请保持 merchantCaptureId 不变；如果上一笔请款请求失败且需要重新发起，请使用新的 merchantCaptureId。

预授权请款响应关键字段：

字段	说明
`bizContent.merchantCaptureId`	商户侧预授权请款流水号
`bizContent.merchantTransactionId`	商户网站的原交易流水号
`bizContent.transactionId`	PingPong 原交易流水号
`bizContent.status`	请款状态，可能为 `SUCCESS`、`FAILED` 或 `PROCESSING`
`bizContent.captureEndingTime`	请款到达终态时间；如果同步已返回终态，可用于记录完成时间

预授权请款响应示例：

{
  "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：获取预授权请款结果

请款发起后，商户应通过以下方式确认最终结果：

接收预授权请款通知
如异步通知延迟、未达、网络异常或需要再次核验结果，可主动调用预授权请款查询

如果您通过异步通知接收结果，可参考以下通知示例与处理方式。

预授权请款通知示例：

{
  "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/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Content-Length: 2

OK

如果异步通知延迟、未达，或商户侧因网络异常、回调处理失败、结果核验等原因暂时无法确认最终状态，可主动调用预授权请款查询获取请款结果。

预授权请款查询请求关键字段：

字段	必填	说明
`bizContent.merchantCaptureId`	是	商户侧预授权请款流水号，全局唯一
`bizContent.merchantTransactionId`	是	商户网站的原交易流水号

有关完整参数的更多信息，请参阅预授权请款查询接口。

预授权请款查询请求示例：

{
  "accId": "2018092714313010016291",
  "clientId": "2018092714313010016",
  "signType": "SHA256",
  "sign": "{{Sign}}",
  "version": "1.0",
  "bizContent": {
    "merchantCaptureId": "CAPTURE_202606260001",
    "merchantTransactionId": "AUTH_202606260001"
  }
}

预授权请款查询响应示例：

{
  "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，说明请款结果尚未最终确认，建议稍后重试查询，或继续等待请款通知。

提示

预授权请款查询请在同步响应返回之后调用；若查询过早，可能会出现查询异常。

无代码接入

PingPong 收银台

内嵌收银台

内嵌 SDK

API Only

Tokenization

保存卡 / CardOnFile

Recurring