退款是指在一笔交易已经成功支付，且资金状态允许退款后，商户将部分或全部交易金额返还给买家的过程。您可以发起全额退款，也可以发起部分退款；若支付方式支持，多次部分退款的累计金额不得超过原交易的可退金额。

对于支持单独 Capture 的支付方式，只有在 Capture 成功后才能退款；如果原交易仍处于已授权未捕获状态，应使用 Void 而不是退款。

退款方式

在支付成功后，您可以通过以下两种方法发起退款：

1. 调用退款接口对成功支付的交易发起退款。
2. 在商户后台退款。

退款流程

流程说明：

1. 商户服务端调用 申请退款 发起退款。
2. 同步响应可能直接返回 SUCCESS、FAILED 或 PROCESSING。
3. 如果同步响应为 PROCESSING，商户可调用 退款查询 主动确认退款状态。
4. PingPongCheckout 也会通过 退款通知 返回最终退款结果。

退款状态机

退款属于支付成功后的独立后置操作。原支付单应已处于 SUCCESS，退款成功或失败不会将原支付单的 status 改为退款状态；商户应使用 merchantRefundId 或 refundId 跟踪退款对象的状态。

退款状态机

集成步骤

请按以下步骤完成集成：

1. 发起退款请求
2. 获取退款结果

步骤 1：发起退款请求

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

退款请求关键字段：

字段	必填	说明
bizContent.merchantRefundId	是	商户侧退款流水请求唯一标识
bizContent.merchantTransactionId	是	商户支付时定义的商户网站订单号
bizContent.amount	是	退款金额
bizContent.currency	是	退款币种
bizContent.notificationUrl	否	用于接收退款结果的异步通知地址

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

退款请求示例：

{
  "accId": "2023121216311410287522",
  "clientId": "2023121216311410287",
  "signType": "SHA256",
  "sign": "{{Sign}}",
  "version": "1.0",
  "bizContent": {
    "amount": 50,
    "currency": "USD",
    "merchantTransactionId": "PMT-KRTTYPSLBE1782370463605",
    "notificationUrl": "https://www.example.com/refund/notify",
    "merchantRefundId": "refund2026062514001"
  }
}

注意

• 仅对已成功支付且当前仍允许退款的交易发起退款；如果是手动 Capture 的交易，请先确认已完成 Capture；如无法确认原交易当前状态，可先调用 交易查询 确认原交易状态。
• 不同支付方式可能存在是否支持退款、退款有效期、是否支持部分退款或多次部分退款等差异，具体信息详见支付方式；部分支付方式在退款时需要额外参数，详见 特殊支付方式退款说明。
• 申请退款 API 基于 merchantRefundId 做幂等控制：同一笔退款请求重复提交时请保持 merchantRefundId 不变；如果上一笔退款请求失败且需要重新发起，请使用新的 merchantRefundId。
• 如需对同一原交易执行多次部分退款，每次退款都应使用新的 merchantRefundId；多次部分退款的累计金额不得超过原交易的可退金额。

退款响应关键字段：

字段	说明
bizContent.merchantRefundId	商户侧退款流水请求唯一标识
bizContent.refundId	PingPong 退款流水号，可用于后续查询或对账
bizContent.transactionId	PingPong 原交易流水号
bizContent.status	退款状态，可能为 SUCCESS、FAILED 或 PROCESSING

退款响应示例：

{
  "accId": "2023121216311410287522",
  "bizContent": "{\"exchangeAmount\":\"50.000000\",\"merchantTransactionId\":\"PMT-KRTTYPSLBE1782370463605\",\"currency\":\"USD\",\"amount\":\"50\",\"refundTime\":\"1782370583121\",\"transactionId\":\"26062500000650916958\",\"exchangeCurrency\":\"USD\",\"merchantRefundId\":\"refund2026062514001\",\"refundId\":\"26062500010650916976\",\"status\":\"SUCCESS\"}",
  "clientId": "2023121216311410287",
  "code": "000000",
  "description": "Transaction succeeded",
  "sign": "5063B78230FCCCFDF5C05171F129A8691FAE030FC196E11557003F6217E361D2",
  "signType": "SHA256"
}

调用退款接口后，同步响应中的 status 可能为以下值：

• SUCCESS：退款成功，可直接更新退款状态
• FAILED：退款失败，应结合错误原因决定是否重试
• PROCESSING：退款处理中，需继续等待退款通知或主动查询

步骤 2：获取退款结果

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

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

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

退款通知示例：

{
  "clientId": "2023121216311410287",
  "code": "000000",
  "bizContent": "{\"amount\":\"50.000000\",\"refundTime\":\"1782370582000\",\"transactionId\":\"26062500000650916958\",\"notifyType\":\"REFUND\",\"merchantTransactionId\":\"PMT-KRTTYPSLBE1782370463605\",\"currency\":\"USD\",\"merchantRefundId\":\"refund2026062514001\",\"refundEndingTime\":\"1782370583083\",\"refundId\":\"26062500010650916976\",\"status\":\"SUCCESS\"}",
  "sign": "5505326E5FEAB26C1DAD253DD06E0E13F4BBA74AA69D7E156B5E26C17CAE0B4F",
  "accId": "2023121216311410287522",
  "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.merchantTransactionId	是	商户支付时定义的商户网站订单号
bizContent.merchantRefundId	条件必填	商户侧退款流水号，与 bizContent.refundId 至少上送一项
bizContent.refundId	条件必填	PingPong 退款流水号，与 bizContent.merchantRefundId 至少上送一项

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

退款查询请求示例：

{
  "accId": "2023121216311410287522",
  "clientId": "2023121216311410287",
  "signType": "SHA256",
  "sign": "{{Sign}}",
  "version": "1.0",
  "bizContent": {
    "merchantRefundId": "PMT-KZW7XVPKVL1782370581548",
    "merchantTransactionId": "PMT-KRTTYPSLBE1782370463605"
  }
}

退款查询响应示例：

{
  "accId": "2023121216311410287522",
  "bizContent": "{\"amount\":\"50.000000\",\"refundTime\":\"1782370582000\",\"resultCode\":\"000000\",\"transactionId\":\"26062500000650916958\",\"merchantTransactionId\":\"PMT-KRTTYPSLBE1782370463605\",\"currency\":\"USD\",\"resultMessage\":\"Transaction succeeded\",\"refundEndingTime\":\"1782370583000\",\"refundId\":\"26062500010650916976\",\"status\":\"SUCCESS\"}",
  "clientId": "2023121216311410287",
  "code": "001000",
  "description": "Successful request",
  "sign": "CDEAD58D00E75DD79642290B6D85190622986A978F23A9FAC1653C876A93F97E",
  "signType": "SHA256"
}

退款查询响应关键字段：

字段	说明
bizContent.merchantTransactionId	商户订单号，用于关联原支付订单
bizContent.refundId	PingPong 退款流水号
bizContent.status	退款状态，可能为 SUCCESS、FAILED 或 PROCESSING
bizContent.refundEndingTime	退款到达终态时间，可用于记录最终完成时间

退款查询响应中的 status 可能返回 SUCCESS、FAILED 或 PROCESSING。如果查询结果为 PROCESSING，说明退款结果尚未最终确认，建议稍后重试查询，或继续等待退款通知。

提示

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

上一页预授权撤销

下一页概览