Version de développement
Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.
Paiements

Rembourser un paiement Razorpay (développeurs)

Méthodes de remboursement des Paramètres Razorpay et webhook de notification des remboursements, pour les 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.

Razorpay n'a pas de bouton de remboursement dans le bureau. Le bouton Remboursement d'une écriture de paiement apparaît seulement pour les passerelles v2 qui savent rembourser, et pour Stancer. Razorpay n'est pas une passerelle v2. Un remboursement Razorpay se fait par code ou depuis le tableau de bord Razorpay.

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éthodeRô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

  1. Dans le tableau de bord Razorpay, ouvrez Settings > Webhooks.
  2. Cliquez sur Add New Webhook.
  3. Dans Webhook URL, saisissez :
    https://<votre-site>/api/method/payments.payment_gateways.doctype.razorpay_settings.webhook.razorpay_webhook
    
  4. Dans Secret, saisissez un secret de votre choix.
  5. Sélectionnez les événements refund.processed et refund.failed.
  6. Enregistrez le webhook.

Configurer le secret dans Dokos

  1. Ouvrez la recherche (Ctrl+K) et saisissez « Paramètres Razorpay ».
  2. Dans Secret Webhook, saisissez le même secret.
  3. Enregistrez.

Sans Secret Webhook, Dokos refuse toutes les notifications.

Traitement d'une notification

  1. Dokos vérifie l'en-tête X-Razorpay-Signature avec le Secret Webhook (HMAC SHA-256).
  2. Dokos ignore les événements autres que refund.processed et refund.failed.
  3. Dokos crée une Demande d'Intégration (service « Razorpay », description « Refund Notification »), avec le corps de la notification.
  4. Une tâche de fond appelle les méthodes du hook handle_refund_notification, avec doctype et docname de la demande d'intégration.
  5. 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.

L'application 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"]

Pages liées