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.
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.