- XF 兼容性
- 2.3.x
- 摘要
- This add-on provides advanced refund capabilities for XenForo, including admin-initiated refunds and smart partial refund handling. It integrates seamlessly with Stripe and PayPal, offering a robust framework for payment providers and add-ons to manage refunds efficiently. Users can initiate refunds directly from the admin panel or via purchase logs, ensuring smooth user upgrades and seamless transaction management.
管理员导航到日志 → 支付提供商 →[specific=payment entry]点击“退款”（仅对支持退款的服务提供者可见）
输入退款金额（预填充为可退还余额）
对于用户升级：选项取消购买（降级用户）
对于其他可购类型：退款由服务提供商处理，拥有者的附加组件通过payment_refund_complete代码事件来撤销退款
附加组件调用服务提供商的退款API，记录结果，并跟踪累计退款金额
从服务提供商日志中发起支付
如果购买是用于XenForo处理的用户升级，可以指定退款金额和所需的行动。
如果购买是在另一个附加选项中进行的，您将被提示仅发起退款：
如何为支付提供商添加退款支持？
第三方支付提供商可以通过直接在其提供程序类中实现supportsRefunds()和refund()方法来添加退款支持——无需依赖此插件。
第三方可购买的附加组件可以监听payment_refund_complete代码事件以处理触发退款的操作（例如，撤销课程访问权限）。
步骤 2：实现 refund() 方法，其签名必须与此 exactly 相同：
步骤3：没有步骤3。退款插件使用method_exists()在运行时检测这些方法。如果安装了退款插件，你的提供商会在支付日志条目中显示“退款”按钮。如果没有安装，这些方法则不会被使用。
如何为我的插件添加退款支持？
如果你有一个允许购买的插件（而不是支付服务提供商），并且希望在发生退款时做出反应——例如，取消课程访问权限——请注册一个代码事件监听器来处理payment_refund_complete：
你需要在你的扩展程序的 _data/code_event_listeners.xml 文件中注册这个监听器：
重要提示：无需使用或要求Jack\PaymentRefund命名空间中的任何类。您的提供商应完全不依赖退款扩展。
交易ID解析：$transactionId参数来自要退款的xf_payment_provider_log条目中的transaction_id列。根据您的提供商记录支付的方式，这可能不是您需要用于退款API的ID。如果不是，请从日志条目的log_details或购买请求的provider_metadata中查找正确的ID。参见Stripe扩展中的resolveChargeId()方法示例。
货币处理：$amount始终是一个小数值（例如，10.00）。如果您的提供商API期望金额以最小货币单位（如美分）表示，请在退款()方法中进行转换。
部分退款：退款扩展自动跟踪累积记录。您的退款()方法只需处理它所给的任何金额即可。该附加组件确保$amount不会超过可退还余额剩余的部分。
Webhook去重：当管理员发出退款时，提供商随后发送的后续webhook（例如Stripe的charge.refunded）被检测为重复，并作为信息日志记录——防止双重逆向操作。
输入退款金额（预填充为可退还余额）
对于用户升级：选项取消购买（降级用户）
对于其他可购类型：退款由服务提供商处理，拥有者的附加组件通过payment_refund_complete代码事件来撤销退款
附加组件调用服务提供商的退款API，记录结果，并跟踪累计退款金额
从服务提供商日志中发起支付
如果购买是用于XenForo处理的用户升级，可以指定退款金额和所需的行动。
如果购买是在另一个附加选项中进行的，您将被提示仅发起退款：
如何为支付提供商添加退款支持？
第三方支付提供商可以通过直接在其提供程序类中实现supportsRefunds()和refund()方法来添加退款支持——无需依赖此插件。
第三方可购买的附加组件可以监听payment_refund_complete代码事件以处理触发退款的操作（例如，撤销课程访问权限）。
PHP：
public function supportsRefunds(): bool
{
return true;
}
PHP：
public function refund(
\XF\Entity\PaymentProfile $paymentProfile,
\XF\Entity\PurchaseRequest $purchaseRequest,
string $transactionId,
?float $amount = null,
string $currency = 'USD'
): array
{
// $paymentProfile - contains your API credentials in $paymentProfile->options
// $purchaseRequest - the original purchase (has cost_amount, cost_currency, provider_metadata)
// $transactionId - the transaction ID from the payment log entry being refunded
// $amount - refund amount (null means full refund)
// $currency - currency code
// Call your provider's refund API here...
// On success, return:
return [
'success' => true,
'provider_refund_id' => 'your_provider_refund_id',
];
// On failure, return:
return [
'success' => false,
'error' => 'Human-readable error message',
];
}如何为我的插件添加退款支持？
如果你有一个允许购买的插件（而不是支付服务提供商），并且希望在发生退款时做出反应——例如，取消课程访问权限——请注册一个代码事件监听器来处理payment_refund_complete：
PHP：
public static function onPaymentRefundComplete(
\XF\Entity\PaymentProviderLog &$logEntry,
\XF\Entity\PurchaseRequest &$purchaseRequest,
float $amount,
string $currency,
bool $purchaseReversed,
array $providerResult
): void
{
// Check if this refund is for your purchasable type
if ($purchaseRequest->purchasable_type_id !== 'your_purchasable_type')
{
return;
}
// Handle the refund (e.g., revoke access, send notification)
}
XML：
<listeners>
<listener event_id="payment_refund_complete"
execute_order="10"
callback_class="Your\AddOn\Listener"
callback_method="onPaymentRefundComplete"
active="1" />
</listeners>交易ID解析：$transactionId参数来自要退款的xf_payment_provider_log条目中的transaction_id列。根据您的提供商记录支付的方式，这可能不是您需要用于退款API的ID。如果不是，请从日志条目的log_details或购买请求的provider_metadata中查找正确的ID。参见Stripe扩展中的resolveChargeId()方法示例。
货币处理：$amount始终是一个小数值（例如，10.00）。如果您的提供商API期望金额以最小货币单位（如美分）表示，请在退款()方法中进行转换。
部分退款：退款扩展自动跟踪累积记录。您的退款()方法只需处理它所给的任何金额即可。该附加组件确保$amount不会超过可退还余额剩余的部分。
Webhook去重：当管理员发出退款时，提供商随后发送的后续webhook（例如Stripe的charge.refunded）被检测为重复，并作为信息日志记录——防止双重逆向操作。
