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

Intégrer une passerelle avec PaymentController v2

Contrat du contrôleur de paiement, données de transaction et points d’extension pour les développeurs.

Intégrer une passerelle avec PaymentController v2

Cette référence s’adresse aux développeurs d’une application de paiement. Pour configurer une passerelle existante, consultez les passerelles de paiement.

Rôle du contrôleur

PaymentController, dans l’application payments, crée la session de paiement et coordonne ses changements d’état. Chaque passerelle fournit un adaptateur pour communiquer avec son prestataire.

La Demande de paiement utilise ce contrôleur lorsqu’une passerelle v2 est reconnue. Les passerelles sans adaptateur v2 suivent le traitement v1.

Une passerelle est v2 quand le type de document de ses paramètres figure dans le hook payment_v2_controllers. L’application payments déclare ces passerelles v2 : Stripe, Stancer, Braintree, GoCardless, PayPal, HelloAsso et Lyra. Les autres passerelles, comme Razorpay, restent en v1.

Appels depuis une demande de paiement

Le code appelant transmet les données de transaction et le nom du document Payment Gateway :

from payments.controllers import PaymentController

controller, psl_name = PaymentController.initiate(tx_data, payment_gateway)
payment_url = PaymentController.get_payment_url(psl_name)

initiate() retourne un tuple contenant le contrôleur et le nom du Payment Session Log. get_payment_url() retourne l’URL destinée au navigateur.

initiate() refuse de créer une session si le document de référence est déjà payé. La classe de base crée ensuite la session avant d’appeler l’adaptateur. Un adaptateur ne doit pas remplacer ce flux par une seconde création de session.

Si initiate() lève une erreur, la demande de paiement enregistre l’erreur dans le Journal des Erreurs. L’utilisateur voit le message « Payment Initialization Failed ».

Données de transaction

PaymentRequest.get_tx_data() fournit les champs suivants. Le contrôleur les convertit en objet TxData avant l’appel à _initiate().

ChampContenu
amountMontant retourné par get_request_amount(), qui tient compte du montant demandé
currencyDevise de la demande
reference_doctypePayment Request
reference_docnameNom de la demande de paiement
payer_contactDictionnaire des coordonnées du contact principal, ou dictionnaire vide
payer_addressDictionnaire de l’adresse principale, ou dictionnaire vide
loyalty_pointsNone dans ce flux
discount_amountNone dans ce flux

La référence désigne la demande de paiement, qui gère le lien avec la facture ou la commande. Elle ne désigne pas directement ce document commercial.

Dans l’adaptateur, utilisez les attributs de l’objet, par exemple tx_data.amount et tx_data.payer_contact.get("email_id").

Enregistrer un adaptateur

Déclarez le contrôleur dans le hook payment_v2_controllers de votre application. La clé est le nom du type de document des paramètres de la passerelle :

# hooks.py — noms à adapter à votre application
payment_v2_controllers = {
    "Ma Passerelle Settings": "mon_app.paiements.controleur.MaPasserelleController",
}

Le document Payment Gateway doit référencer ces paramètres. L’enregistrement du hook permet au framework de trouver la classe, mais ne constitue pas une intégration complète.

Implémenter le contrat de l’adaptateur

La classe hérite de payments.controllers.payment_controller.PaymentController. Elle implémente les méthodes adaptées au prestataire :

MéthodeResponsabilité
_initiate(self, psl, tx_data)Créer l’objet de paiement distant et retourner un RemoteServerInitiationPayload
_start(self, psl)Retourner l’URL du parcours de paiement
_verify_webhook_signature(self, request)Vérifier l’authenticité d’une notification du prestataire
_parse_webhook_event(self, request)Extraire les données de la notification
_map_remote_state(self, decoded)Traduire l’état distant en SessionStates
_fetch_remote_state(self, psl)Consulter l’état du paiement chez le prestataire

RemoteServerInitiationPayload, défini dans payments.types, contient gateway_reference, redirect_url, client_secret et raw. Les besoins de capture, remboursement et rapprochement dépendent du prestataire. Consultez les méthodes de la classe de base et un adaptateur existant avant d’implémenter ces opérations.

La classe de base conserve la gestion des transitions et du rapprochement. Une redirection du navigateur ne suffit pas à déclarer un paiement réussi.

Le bouton Remboursement d’une écriture de paiement apparaît seulement si l’adaptateur remplace _refund(). Il faut aussi que la session ait le statut Paid ou Partially Refunded et un identifiant de paiement chez le prestataire.

Importer les versements du prestataire

La tâche planifiée quotidienne payments.payouts.ingest_payouts parcourt les passerelles v2 actives. Pour chaque contrôleur qui définit sync_payouts(), elle appelle cette méthode. Elle appelle aussi sync_disputes() quand le contrôleur la définit. Une erreur sur une passerelle est enregistrée dans le Journal des Erreurs et n’interrompt pas les autres.

Un adaptateur qui importe les versements fournit :

MéthodeResponsabilité
sync_payouts(self)Lister les versements payés du prestataire, créer chaque Payout une seule fois et le valider
_fetch_payout(self, gateway_payout_id) -> dictNormaliser un versement dans le dictionnaire attendu par create_payout_from_data

La classe de base fournit deux aides :

  • _payout_floor() retourne l’heure Unix de la première Payment Session Log de la passerelle, ou None s’il n’y en a pas. Les versements à importer commencent à cette date.
  • _raise_payout_issues(payout, data) ouvre un Payment Reconciliation Issue pour chaque élément de data["items"] qui porte une clé issue, un tuple (type, détails). L’appel est idempotent (open_unique).

Chaque élément de data["items"] porte item_type, gateway_reference, gross_amount, fee_amount, net_amount et payment_session_log. Il peut aussi porter tax_amount, remarks, issue et payment_entry.

Exemple : GoCardless

GoCardlessController hérite du mixin GoCardlessPayoutSync (gocardless_payout_sync.py) avant PaymentController. Le mixin :

  • liste les versements paid créés depuis la première session de paiement, avec les méthodes list_all des classes GoCardlessPayouts et GoCardlessPayoutItems ;
  • convertit chaque ligne GoCardless (payout item) en élément : payment_paid_out en Payment, gocardless_fee, app_fee et surcharge_fee en Fees (TVA comprise dans tax_amount), payment_refunded et refund en Refund, payment_failed et payment_charged_back en Dispute avec un problème Chargeback, les autres types en Adjustment ;
  • rattache chaque élément à son Payment Session Log par l’identifiant du paiement GoCardless ;
  • si la somme des lignes diffère du montant du versement, ajoute un élément Adjustment pour l’écart, marque le versement discrepancy et ouvre un problème Payout Discrepancy. Un Payout au statut Discrepancy n’est pas validé ;
  • ignore un versement déjà enregistré avec le même gateway_payout_id et validé ou annulé ; un brouillon est repris à l’exécution suivante ;
  • avant de créer le Payout, règle chaque paiement versé qui n’a ni Payment Entry ni écriture rattachée à sa session. Avec une session, il appelle reconcile(psl, source="payout"). Sans session, il lit les métadonnées du paiement GoCardless et appelle on_payment_authorized(status="Paid", reference_no=...) sur le document désigné. Une Payment Entry existante (rapprochée ou annulée comprise) n’est jamais recréée.

Le règlement d’un paiement a lieu avant le point de sauvegarde (savepoint) qui protège la création du Payout, car il peut valider la transaction. La validation du Payout comptabilise déjà l’écriture de compensation : ne la comptabilisez pas une seconde fois.

Suivre la session après l’initialisation

Le Payment Session Log (« Journal des sessions de paiement ») porte l’état de la tentative. Les états sont définis par SessionStates : Created, Initiated, Started, Queued, Processing, Paid, Failed, Error, Abandoned, Refunded et Partially Refunded. Une transition ne peut aller que vers un état de rang supérieur ou égal.

La redirection du payeur, le webhook et l’interrogation périodique passent tous par process_response(). Cette méthode traduit l’état distant avec _map_remote_state(), applique la transition, puis :

  • à l’état Paid, appelle on_payment_paid() du document de référence, qui crée l’écriture de paiement une seule fois,
  • à l’état Failed ou Error, appelle on_payment_failed().

L’état de la session est validé en base avant ces appels. Si la création de l’écriture de paiement échoue, la session reste Paid sans écriture de paiement. Dokos ouvre alors un Problème de rapprochement de paiement de type « Booking Failure ». Corrigez la cause, puis créez l’écriture à la main. Une nouvelle notification qui réussit résout ce problème.

Déclarer un document de référence

Le contrôleur ne connaît pas les documents commerciaux. Il appelle les méthodes d’un document de référence déclaré dans le hook payment_reference_doctypes. Dokos y déclare la Demande de paiement :

payment_reference_doctypes = {
    "Payment Request": "erpnext.accounts.doctype.payment_request.payment_request.PaymentRequest",
}

Le document de référence implémente le protocole PaymentReferenceDocument de payments/reference_document.py :

MéthodeRôle
get_tx_data()Fournir les données de transaction
on_payment_paid(psl)Solder le paiement et retourner le nom de l’écriture de paiement
on_payment_failed(psl)Marquer l’échec
on_payment_refunded(psl, amount)Traiter un remboursement
get_redirection(psl=None)Donner la page de retour du payeur

Vérifier la compatibilité

L’application payments installée doit fournir PaymentController, TxData et le hook d’enregistrement. L’application Dokos doit contenir le flux v2 de PaymentRequest.

Si la détection v2 échoue, la demande de paiement peut revenir au traitement v1. Ce repli ne remplace pas les tests d’intégration d’une nouvelle passerelle.

Vérifiez au minimum l’initialisation, le retour du payeur, les notifications signées, les notifications répétées et les échecs de paiement. Testez également les opérations de remboursement et de rapprochement prises en charge par votre adaptateur.