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

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

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

请款方式

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

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

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

预授权请款流程

流程说明：

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

集成步骤

请按以下步骤完成集成：

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

步骤 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"
 }
}

注意

• 仅对已授权且尚未扣款的交易发起预授权请款。
• 下单阶段需已启用手动 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：获取预授权请款结果

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

1. 接收 预授权请款通知
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\",\"resultDescription\":\"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，说明请款结果尚未最终确认，建议稍后重试查询，或继续等待请款通知。

提示

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

上一页Klarna测试资源

下一页Void