- Compatibilité XF
- 2.3.x
- Description courte
- 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.
Admin navigate à Logs → Paiement du fournisseur →[specific=payment entry]Cliquez "Retourner le Frais" (visible uniquement pour les fournisseurs supportant les remboursements)
Entrez le montant du remboursement (pré-rempli avec le solde restant rembourrasable)
Pour les améliorations de l'utilisateur : option de rétablir la transaction (désengager l'utilisateur)
Pour d'autres types de produits achetables : le remboursement est traité par le fournisseur et le gestionnaire d'ajout-on gère la réversibilité via l'événement payment_refund_complete
L'add-on appelle l'API de remboursement du fournisseur, enregistre les résultats et suit le montant total remboursé
Initiate a payment from the provider logs:
Si la commande a été effectuée pour une Augmentation de Utilisateur gérée par XenForo, vous pouvez spécifier le montant du remboursement et l'action désirée pour l'augmentation.
Si la commande a été effectuée dans un autre complément, vous serez invité à déclencher uniquement un remboursement :
Comment ça fonctionne (ce point-là-vien est principalement pour la documentation des développeurs qui veulent étendre les capacités de remboursement à leurs fournisseurs de paiement ou aux compléments)
Le complément s'insère :
Sur les fournisseurs de paiement Stripe et PayPal REST — Ajoute les méthodes supportsRefunds() et refund() pour les appels API, et surcharge getPaymentResult() pour détecter les remboursements partiels par rapport à ceux complets dans les webhooks entrants.
AbstractProvider — Ajoute une méthode safe default supportsRefunds() retournant false pour que les fournisseurs anciens ne crashent pas.
LogController — Injecte un bouton "Émettre un Remboursement" sur les vues détails des enregistrements de paiement et ajoute une action de formulaire de remboursement.
PaymentRepository — Ajoute des méthodes helper pour le suivi cumulatif des remboursesments et la déduplication.
Extensibilité
Les fournisseurs de paiement tierces peuvent ajouter le support de remboursement en implémentant les méthodes supportsRefunds() et refund() directement dans leur classe de fournisseur — aucune dépendance avec ce complément n'est requise.
Les compléments tiers achetable peuvent écouter l'événement payment_refund_complete pour gérer des actions liées au remboursement (par exemple, annuler l'accès à un cours).
Comment ajoutez-vous le support de remboursement à votre fournisseur de paiement?
Étape 1 : Ajoutez supportsRefunds() à votre fournisseur
Dans la classe de votre fournisseur (qui étend XF\Payment\AbstractProvider), ajoutez :
Étape 2 : Implémenter la méthode remboursement ()
Ajoutez la méthode remboursement () avec cette signature exacte :
Retirer le Réféssé
Vous devrez également enregistrer ce récepteur dans votre fichier _data/code_event_listeners.xml de votre add-on :
Instructions critiques
Notes importantes:
- Ne pas utiliser ou nécessiter les classes du espace de noms Jack\PaymentRefund.
- Votre fournisseur devrait avoir zéro références à l'add-on remboursement.
Résolution de l'ID de transaction: Le paramètre $transactionId provient du champ transaction_id dans l'enregistrement xf_payment_provider_log que l'admin est en train de rembourser. Selon la façon dont votre fournisseur enregistre les paiements, ce peut ou non être l'ID que vous avez besoin pour votre API de remboursement. Si ce n'est pas le cas, recherchez l'ID correct dans log_details ou provider_metadata de la demande d'achat. Voir le méthode resolveChargeId() de l'extension Stripe pour un exemple.
Gestion des devises: Le paramètre $amount est toujours une valeur décimale (par exemple, 10.00). Si votre API fournisseur attend les montants dans la unité de devise la plus petite (comme les centimes), convertissez-le dans votre méthode refund().
Remboursements partiel : L'addon remboursement gère automatiquement le suivi cumulatif. Votre méthode refund() doit simplement traiter ce qui lui est donné. L'addon garantit que $amount ne dépasse jamais la balance restante réellement rembourrasseable.
Déduplication des webhook : Quand un admin émet un remboursement, le webhook suivant du fournisseur (par exemple, le charge.refunded de Stripe) est détecté comme une duplication et enregistré comme informatif — empêchant les doubles annulations.
Entrez le montant du remboursement (pré-rempli avec le solde restant rembourrasable)
Pour les améliorations de l'utilisateur : option de rétablir la transaction (désengager l'utilisateur)
Pour d'autres types de produits achetables : le remboursement est traité par le fournisseur et le gestionnaire d'ajout-on gère la réversibilité via l'événement payment_refund_complete
L'add-on appelle l'API de remboursement du fournisseur, enregistre les résultats et suit le montant total remboursé
Initiate a payment from the provider logs:
Si la commande a été effectuée pour une Augmentation de Utilisateur gérée par XenForo, vous pouvez spécifier le montant du remboursement et l'action désirée pour l'augmentation.
Si la commande a été effectuée dans un autre complément, vous serez invité à déclencher uniquement un remboursement :
Comment ça fonctionne (ce point-là-vien est principalement pour la documentation des développeurs qui veulent étendre les capacités de remboursement à leurs fournisseurs de paiement ou aux compléments)
Le complément s'insère :
Sur les fournisseurs de paiement Stripe et PayPal REST — Ajoute les méthodes supportsRefunds() et refund() pour les appels API, et surcharge getPaymentResult() pour détecter les remboursements partiels par rapport à ceux complets dans les webhooks entrants.
AbstractProvider — Ajoute une méthode safe default supportsRefunds() retournant false pour que les fournisseurs anciens ne crashent pas.
LogController — Injecte un bouton "Émettre un Remboursement" sur les vues détails des enregistrements de paiement et ajoute une action de formulaire de remboursement.
PaymentRepository — Ajoute des méthodes helper pour le suivi cumulatif des remboursesments et la déduplication.
Extensibilité
Les fournisseurs de paiement tierces peuvent ajouter le support de remboursement en implémentant les méthodes supportsRefunds() et refund() directement dans leur classe de fournisseur — aucune dépendance avec ce complément n'est requise.
Les compléments tiers achetable peuvent écouter l'événement payment_refund_complete pour gérer des actions liées au remboursement (par exemple, annuler l'accès à un cours).
Comment ajoutez-vous le support de remboursement à votre fournisseur de paiement?
Étape 1 : Ajoutez supportsRefunds() à votre fournisseur
Dans la classe de votre fournisseur (qui étend XF\Payment\AbstractProvider), ajoutez :
PHP:
public function supportsRefunds(): bool
{
return true;
}Ajoutez la méthode remboursement () avec cette signature exacte :
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',
];
}
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>Notes importantes:
- Ne pas utiliser ou nécessiter les classes du espace de noms Jack\PaymentRefund.
- Votre fournisseur devrait avoir zéro références à l'add-on remboursement.
Résolution de l'ID de transaction: Le paramètre $transactionId provient du champ transaction_id dans l'enregistrement xf_payment_provider_log que l'admin est en train de rembourser. Selon la façon dont votre fournisseur enregistre les paiements, ce peut ou non être l'ID que vous avez besoin pour votre API de remboursement. Si ce n'est pas le cas, recherchez l'ID correct dans log_details ou provider_metadata de la demande d'achat. Voir le méthode resolveChargeId() de l'extension Stripe pour un exemple.
Gestion des devises: Le paramètre $amount est toujours une valeur décimale (par exemple, 10.00). Si votre API fournisseur attend les montants dans la unité de devise la plus petite (comme les centimes), convertissez-le dans votre méthode refund().
Remboursements partiel : L'addon remboursement gère automatiquement le suivi cumulatif. Votre méthode refund() doit simplement traiter ce qui lui est donné. L'addon garantit que $amount ne dépasse jamais la balance restante réellement rembourrasseable.
Déduplication des webhook : Quand un admin émet un remboursement, le webhook suivant du fournisseur (par exemple, le charge.refunded de Stripe) est détecté comme une duplication et enregistré comme informatif — empêchant les doubles annulations.
![[MC] Infinite Scroll](/data/resource_icons/26/26106.jpg?1758641112){kind=icon}