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.
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.
La classe de base crée la session avant d’appeler l’adaptateur. Un adaptateur ne doit pas remplacer ce flux par une seconde création de session.
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.
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.