Rembourser un paiement Razorpay (développeurs)
Rembourser un paiement Razorpay (développeurs)
Cette référence s'adresse aux développeurs. L'application payments fournit des méthodes Python pour rembourser un paiement Razorpay et un webhook qui reçoit les notifications de remboursement.
Prérequis
- Un compte Razorpay (mode test ou production).
- Les Paramètres Razorpay remplis : Clé API et Secret API. À l'enregistrement, Dokos teste ces identifiants auprès de l'API Razorpay.
- Pour le webhook : un Secret Webhook dans les Paramètres Razorpay.
Rembourser par code
Les Paramètres Razorpay sont un document unique. Ses méthodes appellent l'API Razorpay.
| Méthode | Rôle |
|---|---|
refund_payment(payment_id, amount=None) | Rembourse un paiement. amount est en unités principales (euros). Sans montant, rembourse tout ce qui reste remboursable. |
fetch_refund(refund_id) | Retourne un remboursement. |
fetch_refunds(payment_id) | Retourne la liste des remboursements d'un paiement. Les montants sont en unités mineures (centimes). |
fetch_payment(payment_id) | Retourne le paiement. |
refund_payment() refuse le remboursement dans ces cas :
- le paiement n'a pas le statut
captured(« Only captured payments can be refunded »), - le montant est inférieur ou égal à 0,
- le montant dépasse le reste remboursable (montant du paiement moins montant déjà remboursé).
Un refus de Razorpay (BadRequestError) s'affiche à l'utilisateur. Une erreur serveur de Razorpay va dans le Journal des Erreurs.
Le remboursement retourné reste pending jusqu'à son traitement par Razorpay. Vérifiez son état avec fetch_refund() ou attendez la notification refund.processed.
Exemple fictif : un paiement de 100 € (pay_DEF456UVW) reçoit un remboursement partiel de 40 €.
settings = frappe.get_doc("Razorpay Settings")
refund = settings.refund_payment("pay_DEF456UVW", 40)
# refund["status"] == "pending"
settings.fetch_refunds("pay_DEF456UVW")
# [{"id": "rfnd_GHI789JKL", "amount": 4000, "currency": "EUR", "status": "processed", ...}]
Un second appel sans montant rembourse les 60 € restants.
Recevoir les notifications de remboursement
Configurer le webhook dans Razorpay
- Dans le tableau de bord Razorpay, ouvrez Settings > Webhooks.
- Cliquez sur Add New Webhook.
- Dans Webhook URL, saisissez :
https://<votre-site>/api/method/payments.payment_gateways.doctype.razorpay_settings.webhook.razorpay_webhook - Dans Secret, saisissez un secret de votre choix.
- Sélectionnez les événements
refund.processedetrefund.failed. - Enregistrez le webhook.
Configurer le secret dans Dokos
- Ouvrez la recherche (Ctrl+K) et saisissez « Paramètres Razorpay ».
- Dans Secret Webhook, saisissez le même secret.
- Enregistrez.
Sans Secret Webhook, Dokos refuse toutes les notifications.
Traitement d'une notification
- Dokos vérifie l'en-tête
X-Razorpay-Signatureavec le Secret Webhook (HMAC SHA-256). - Dokos ignore les événements autres que
refund.processedetrefund.failed. - Dokos crée une Demande d'Intégration (service « Razorpay », description « Refund Notification »), avec le corps de la notification.
- Une tâche de fond appelle les méthodes du hook
handle_refund_notification, avecdoctypeetdocnamede la demande d'intégration. - La demande d'intégration passe au statut « Terminé ». Si une méthode échoue, l'erreur va dans le Journal des Erreurs et la demande passe au statut « Échec ».
Razorpay renvoie une notification tant qu'il ne reçoit pas de réponse 2xx. Dokos utilise l'en-tête X-Razorpay-Event-Id pour ne pas créer deux fois la même demande d'intégration. Vos méthodes doivent quand même accepter un second appel sans effet de bord.
payments n'abonne aucune méthode à handle_refund_notification. Sans méthode déclarée par votre application, la notification est seulement enregistrée.Exemple fictif de déclaration dans hooks.py (noms à adapter) :
handle_refund_notification = "mon_app.paiements.razorpay.on_refund"
import frappe
def on_refund(doctype, docname):
data = frappe.parse_json(frappe.db.get_value(doctype, docname, "data"))
refund = data["payload"]["refund"]["entity"]
# Mettre à jour vos documents à partir de refund["id"] et refund["status"]