Payment Refunds v1.0

What it does​

1. Admin-initiated refunds — Issue full or partial refunds directly from the admin panel instead of logging into the provider dashboards (e.g. Stripe, PayPal, etc).
2. Smart partial refund handling — Fixes a core XenForo behavior where partial refunds (e.g., a $15 discount adjustment on a $30 purchase) downgrades the user vs only refunds. Partial refunds now log as informational events without triggering a reversal. Full refunds continue to auto-downgrade as before.

Refund flow​

1. Admin navigates to Logs → Payment Provider → [specific payment entry]
2. Clicks "Issue Refund" (only visible for providers that support refunds)
3. Enters refund amount (pre-filled with remaining refundable balance)
4. For user upgrades: option to reverse the purchase (downgrade user)
5. For other purchasable types: the refund is processed with the provider, and the owning add-on handles reversal via the payment_refund_complete code event
6. The add-on calls the provider's refund API, logs the result, and tracks the cumulative refunded amount

How it works​

• Stripe and PayPal REST Payment providers — Adds supportsRefunds() and refund() methods for API calls, plus overrides getPaymentResult() to detect partial vs full refunds on incoming webhooks.
• AbstractProvider — Adds a safe default supportsRefunds() returning false so legacy providers don't crash.
• LogController — Injects an "Issue Refund" button on payment log detail views and adds a refund form action.
• PaymentRepository — Adds helper methods for cumulative refund tracking and deduplication.

Extensibility​

• Third-party payment providers can add refund support by implementing supportsRefunds() and refund() methods directly on their provider class — no dependency on this add-on required.
• Third-party purchasable add-ons can listen for the payment_refund_complete code event to handle refund-triggered actions (e.g., revoking access to a course).

How do I add refund support to my payment provider?​

Step 1: Add supportsRefunds() to your provider​

public function supportsRefunds(): bool
{
    return true;
}

​

Step 2: Implement refund()​

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',
    ];
}

Step 3: There is no step 3​

How do I add refund support to my add-on?​

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)
}

<listeners>
    <listener event_id="payment_refund_complete"
              execute_order="10"
              callback_class="Your\AddOn\Listener"
              callback_method="onPaymentRefundComplete"
              active="1" />
</listeners>

Important notes​