Intégrer une passerelle avec PaymentController v2
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().
| Champ | Contenu |
|---|---|
amount | Montant retourné par get_request_amount(), qui tient compte du montant demandé |
currency | Devise de la demande |
reference_doctype | Payment Request |
reference_docname | Nom de la demande de paiement |
payer_contact | Dictionnaire des coordonnées du contact principal, ou dictionnaire vide |
payer_address | Dictionnaire de l’adresse principale, ou dictionnaire vide |
loyalty_points | None dans ce flux |
discount_amount | None 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éthode | Responsabilité |
|---|---|
_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éthode | Responsabilité |
|---|---|
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) -> dict | Normaliser 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èrePayment Session Logde la passerelle, ouNones’il n’y en a pas. Les versements à importer commencent à cette date._raise_payout_issues(payout, data)ouvre unPayment Reconciliation Issuepour chaque élément dedata["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
paidcréés depuis la première session de paiement, avec les méthodeslist_alldes classesGoCardlessPayoutsetGoCardlessPayoutItems; - convertit chaque ligne GoCardless (
payout item) en élément :payment_paid_outenPayment,gocardless_fee,app_feeetsurcharge_feeenFees(TVA comprise danstax_amount),payment_refundedetrefundenRefund,payment_failedetpayment_charged_backenDisputeavec un problèmeChargeback, les autres types enAdjustment; - rattache chaque élément à son
Payment Session Logpar l’identifiant du paiement GoCardless ; - si la somme des lignes diffère du montant du versement, ajoute un élément
Adjustmentpour l’écart, marque le versementdiscrepancyet ouvre un problèmePayout Discrepancy. UnPayoutau statutDiscrepancyn’est pas validé ; - ignore un versement déjà enregistré avec le même
gateway_payout_idet 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 niPayment Entryni écriture rattachée à sa session. Avec une session, il appellereconcile(psl, source="payout"). Sans session, il lit les métadonnées du paiement GoCardless et appelleon_payment_authorized(status="Paid", reference_no=...)sur le document désigné. UnePayment Entryexistante (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, appelleon_payment_paid()du document de référence, qui crée l’écriture de paiement une seule fois, - à l’état
FailedouError, appelleon_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éthode | Rô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.