From 947ca1079a75ce021103175ce53b65f1c39ea96a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Vihoal=C3=A9=20ANIGLO?= <46029829+JIV-DLS@users.noreply.github.com> Date: Sun, 15 Nov 2026 22:16:37 +0100 Subject: [PATCH] feat : le client change d'offre ou revient plus tard (0.6.0) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Routes toutes faites : reference_conflict (le client a changé d'offre, autre montant) fait passer à l'essai suivant comme payment_expired, dans la même borne max_attempts. Contrat v1 à 24 cas (copie partagée, identique à l'octet). Documentation (AGENTS.md, README, llms.txt) : une référence = un essai, payée seulement sur payment.completed, un essai non payé ne bloque jamais un nouvel essai, get_payment au retour du client, refund de l'essai payé en trop. Exemple Python et test de scénario (essai expiré puis nouvel essai d'un autre montant, conflit sur la référence réutilisée). --- AGENTS.md | 44 ++++++++++++++++++- CHANGELOG.md | 4 ++ README.md | 34 +++++++++++++- contract/app-contract.v1.json | 83 ++++++++++++++++++++++++++++++++++- llms.txt | 2 + src/technas_pay/_version.py | 2 +- src/technas_pay/app_routes.py | 7 +-- tests/fake_gateway.py | 4 +- tests/test_client.py | 15 +++++++ 9 files changed, 185 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9b74746..9e1a197 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,7 +13,7 @@ Même API, mêmes règles que le SDK TypeScript `@technas/pay-next` : seuls les ## Installer ```bash -pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.5.1" +pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.6.0" ``` @@ -34,6 +34,7 @@ Créez UNE instance au niveau du module (`pay = TechnasPay()`) : elle lit `TECHN | Savoir qu'elle est payée | webhook, `WebhookHandlers(on_completed=...)` | | Rattraper un webhook manqué | `pay.get_payment_by_reference(reference)` | | Savoir si on peut relancer | `on_expired`, ou `can_retry(pay.get_payment(id))` | +| Le client change d'offre ou revient plus tard | nouvel essai `retry_reference(facture_id, n + 1)` ; au retour, `pay.get_payment(dernier_paiement_id)` d'abord | | Rembourser | `pay.refund(payment_id, amount=?, fees=?, reference=?)` | | Noter un remboursement fait hors Technas | `pay.record_external_refund(payment_id, amount=..., method="Flooz")` | | Savoir que le remboursement est arrivé | `on_refund` (`refund.completed`, `refund.failed`, `refund.recorded`) | @@ -122,6 +123,47 @@ Ne réécrivez pas de routes : `pay.app_routes(authorize=..., resolve_order=..., - `failed` n'est **pas** définitif : le client peut encore payer sur la même page pendant une heure. Dans `on_failed`, n'annulez rien, n'envoyez pas de nouveau lien. - `expired` est définitif. `can_retry(payment)` n'est vrai que là. - Expliquez cette règle à l'utilisateur : un client relancé sur `failed` pourrait payer deux fois. +- Le client choisit lui-même une AUTRE offre (autre montant) : c'est un nouvel essai tout de suite, voir la section suivante. + +## Le client change d'offre ou revient plus tard + +Le client choisit une offre, arrive sur la page de paiement, ne paie pas, puis revient choisir une AUTRE offre (ou revient plus tard). Ce n'est jamais « un paiement existe déjà ». + +- **Une référence = un essai.** Nouvelle offre, ou retour après expiration : un NOUVEL essai, avec une nouvelle référence `retry_reference(facture_id, n + 1)` (`n` gardé en base). Réutiliser la référence avec un autre montant lève `reference_conflict` (409) ; celle d'un essai expiré, `payment_expired` (409). Les routes toutes faites (`app_routes`) le font seules. +- **Une facture n'est payée QUE sur `payment.completed`** (avis signé, `on_completed`). Jamais sur `return_url`, jamais à l'ouverture de la page. +- **Un essai non payé ne bloque jamais un nouvel essai.** `pending` ou `failed` et le client change d'offre : créez le nouvel essai, ne refusez pas. `expired` : marquez la tentative expirée et laissez recommencer. +- **Au retour du client**, vérifiez avec `pay.get_payment(dernier_paiement_id)` avant de dire quoi que ce soit ; ne vous fiez jamais seulement à votre base. +- **Un ancien essai payé APRÈS le nouveau** (le client a payé les deux pages) : n'activez rien deux fois ; remboursez l'essai en trop avec `pay.refund(payment_id)`. + +```python +from technas_pay import retry_reference + +def payer(facture, montant): + """Au clic « payer » : `montant` est celui de l'offre choisie MAINTENANT.""" + if facture.dernier_paiement_id: + dernier = pay.get_payment(facture.dernier_paiement_id) # la vérité est chez Technas + if dernier.status == "completed": + return "deja_payee" + # pending, failed, expired ou autre montant : nouvel essai, jamais un refus + facture.essai += 1 + paiement = pay.ask_for_payment( + amount=montant, + reference=retry_reference(facture.id, facture.essai), + customer={"email": facture.email, "name": facture.nom}, + return_url="https://votre-site.example/merci", + ) + facture.dernier_paiement_id = paiement.id + facture.save() + return paiement.checkout_url + +def on_completed(event): + facture = Facture.get(event.payment.reference.rsplit("-", 1)[0]) + if facture.payee_par and facture.payee_par != event.payment.id: + pay.refund(event.payment.id) # le client a payé deux pages : on rend l'essai en trop + return + facture.payee_par = event.payment.id # payée ici, et seulement ici + facture.save() +``` ## Webhooks diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ada2b5..cdb2a2a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## 0.6.0 — 2026-11-15 + +Le client change d'offre ou revient plus tard. Routes toutes faites (`app_routes`) : un `reference_conflict` (la référence d'un essai existe avec un autre montant : le client a changé d'offre) fait passer à l'essai suivant, comme `payment_expired`, dans la même borne `max_attempts` : jamais un refus. Contrat v1 : 24 cas. Documentation : nouvelle section « Le client change d'offre ou revient plus tard » (AGENTS.md, README, llms.txt) avec un exemple ; test de scénario (essai expiré, puis nouvel essai d'un autre montant). + ## 0.5.1 — 2026-11-15 Avis `account.kyc_required` : `KycRequired` porte aussi l'état du compte, comme `get_account_kyc()` : `stage`, `block_reason` (`amount` | `duration`), `days_elapsed`, `grace_days`, `first_collected_at`. Tous facultatifs (`None` sur un avis plus ancien). `reason` ne change pas de sens. diff --git a/README.md b/README.md index 227a673..462c951 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ C'est la même API que le SDK TypeScript [`@technas/pay-next`](https://github.co ## 1. Installer ```bash -pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.5.1" +pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.6.0" ``` Seule dépendance : `httpx`. Python 3.9 ou plus récent. @@ -154,6 +154,38 @@ Les chiffres (seuil, délai) viennent de l'API (`threshold_xof`, `grace_days`) : **Une référence = un essai.** `failed` n'est pas définitif : le client peut encore payer sur la même page pendant une heure. Ne relancez qu'après `payment.expired`, avec une nouvelle référence (`retry_reference(order_id, attempt + 1)`). +Le client change d'offre ou revient plus tard : c'est un NOUVEL essai (`retry_reference(facture_id, n + 1)`), jamais un refus, même si l'essai précédent est encore `pending` ou `failed`. Réutiliser une référence avec un autre montant lève `reference_conflict` ; les routes toutes faites passent seules à l'essai suivant. Au retour du client, relisez le dernier essai (`get_payment`) avant de dire quoi que ce soit. La facture n'est payée que sur `payment.completed` ; si le client a payé deux pages, remboursez l'essai en trop (`refund`). + +```python +from technas_pay import retry_reference + +def payer(facture, montant): + """Au clic « payer » : `montant` est celui de l'offre choisie MAINTENANT.""" + if facture.dernier_paiement_id: + dernier = pay.get_payment(facture.dernier_paiement_id) # la vérité est chez Technas + if dernier.status == "completed": + return "deja_payee" + # pending, failed, expired ou autre montant : nouvel essai, jamais un refus + facture.essai += 1 + paiement = pay.ask_for_payment( + amount=montant, + reference=retry_reference(facture.id, facture.essai), + customer={"email": facture.email, "name": facture.nom}, + return_url="https://votre-site.example/merci", + ) + facture.dernier_paiement_id = paiement.id + facture.save() + return paiement.checkout_url + +def on_completed(event): + facture = Facture.get(event.payment.reference.rsplit("-", 1)[0]) + if facture.payee_par and facture.payee_par != event.payment.id: + pay.refund(event.payment.id) # le client a payé deux pages : on rend l'essai en trop + return + facture.payee_par = event.payment.id # payée ici, et seulement ici + facture.save() +``` + ## Paiement par carte 1. **Compte carte, une fois** : au clic du RESPONSABLE sur « Activer la carte », `link = pay.start_card_onboarding(country="TG", return_url=..., refresh_url=...)`, puis redirigez-le vers `link.url` : il y donne son identité et sa banque sur la page sécurisée de notre partenaire carte (Stripe), qui vous fera accepter son contrat (le lien expire en minutes). `refresh_url` : rappelez la méthode et redirigez de nouveau. diff --git a/contract/app-contract.v1.json b/contract/app-contract.v1.json index 101639d..191a3dc 100644 --- a/contract/app-contract.v1.json +++ b/contract/app-contract.v1.json @@ -1,7 +1,7 @@ { "name": "technas-pay-app", "version": 1, - "doc": "Contrat entre une app (technas_pay_flutter, TechnasPayClient) et les routes toutes faites des SDK serveur Technas Pay. Les chemins sont relatifs au préfixe de montage (ex. /api/technas-pay). Fichier copié À L'IDENTIQUE dans technas-pay-node, technas-pay-python et technas-pay-dart : chaque dépôt rejoue tous les cas. 'message' est un texte libre, jamais comparé. 'user' : l'utilisateur rendu par authorize (null = non authentifié). 'orders' : ce que resolveOrder rend pour (orderId, user) ; absent = commande inconnue ou d'un autre. 'gateway' : réponses successives de pay-api.technas.fr. Le webhook (POST /webhook, signé) est testé à part : sa signature dépend de l'heure. 'options' : options des routes pour ce cas ({card: true} ouvre la carte). 'admin' : présent = authorizeAdmin est branché et rend cette valeur (null = pas le marchand, 403). Une référence de paiement par carte est orderId-card-N, mobile money orderId-N. Le paiement rendu à l'app porte 'method'.", + "doc": "Contrat entre une app (technas_pay_flutter, TechnasPayClient) et les routes toutes faites des SDK serveur Technas Pay. Les chemins sont relatifs au préfixe de montage (ex. /api/technas-pay). Fichier copié À L'IDENTIQUE dans technas-pay-node, technas-pay-python et technas-pay-dart : chaque dépôt rejoue tous les cas. 'message' est un texte libre, jamais comparé. 'user' : l'utilisateur rendu par authorize (null = non authentifié). 'orders' : ce que resolveOrder rend pour (orderId, user) ; absent = commande inconnue ou d'un autre. 'gateway' : réponses successives de pay-api.technas.fr. Le webhook (POST /webhook, signé) est testé à part : sa signature dépend de l'heure. 'options' : options des routes pour ce cas ({card: true} ouvre la carte). 'admin' : présent = authorizeAdmin est branché et rend cette valeur (null = pas le marchand, 403). Une référence de paiement par carte est orderId-card-N, mobile money orderId-N. Un essai expiré (payment_expired) ou dont le montant ne correspond plus (reference_conflict : le client a changé d'offre) est sauté : essai suivant. Le paiement rendu à l'app porte 'method'.", "routes": [ { "method": "GET", @@ -200,6 +200,85 @@ } } }, + { + "name": "démarrer : le client a changé d'offre (autre montant) → essai suivant, jamais un refus", + "request": { + "method": "POST", + "path": "/payments", + "body": { + "orderId": "42" + } + }, + "user": "u1", + "orders": { + "42": { + "amount": 7500, + "customer": { + "email": "awa@exemple.tg", + "name": "Awa Mensah" + } + } + }, + "gateway": [ + { + "status": 409, + "body": { + "code": "reference_conflict", + "message": "m" + } + }, + { + "status": 201, + "body": { + "id": "pay_2", + "reference": "42-2", + "amount": 7500, + "currency": null, + "commission": 150, + "net_amount": 7350, + "status": "pending", + "checkout_url": "https://pay-api.technas.fr/checkout/pay_2", + "metadata": {}, + "test_mode": true, + "created_at": "2026-11-15T10:00:00Z", + "expires_at": "2026-11-15T11:00:00Z" + } + } + ], + "expect_gateway": [ + { + "method": "POST", + "path": "/v1/payments", + "body_includes": { + "amount": 7500, + "reference": "42-1" + } + }, + { + "method": "POST", + "path": "/v1/payments", + "body_includes": { + "amount": 7500, + "reference": "42-2" + } + } + ], + "expect": { + "status": 200, + "body": { + "payment": { + "id": "pay_2", + "reference": "42-2", + "status": "pending", + "checkout_url": "https://pay-api.technas.fr/checkout/pay_2", + "amount": 7500, + "currency": null, + "expires_at": "2026-11-15T11:00:00Z", + "method": "mobile_money" + } + } + } + }, { "name": "démarrer : le montant ne vient jamais du téléphone", "request": { @@ -1088,4 +1167,4 @@ } } ] -} \ No newline at end of file +} diff --git a/llms.txt b/llms.txt index 20d327a..79948da 100644 --- a/llms.txt +++ b/llms.txt @@ -6,6 +6,8 @@ Agents de code : lisez d'abord AGENTS.md (méthodes, champs obligatoires, sécur Une référence = un essai : `retry_reference(order_id, attempt)`. Relancez avec une NOUVELLE référence seulement après payment.expired (`can_retry`), jamais sur failed. Rejouer la référence d'un paiement expiré lève `TechnasPayError` code `payment_expired` (409). +Le client change d'offre ou revient plus tard : nouvel essai `retry_reference(facture_id, n + 1)`, jamais un refus (`reference_conflict` = référence réutilisée avec un autre montant) ; au retour, `get_payment(dernier_paiement_id)` d'abord ; payée seulement sur `payment.completed`, essai payé en trop → `refund`. + Seuil d'identité : `get_account_kyc()` (à montrer au marchand), avis `on_kyc_required`. Sur l'erreur `kyc_required` (409), proposer la carte ou dire au client que le mobile money n'est pas disponible pour le moment, jamais réessayer ; le responsable dépose sa pièce sur `details.console_url`. Hors zone franc CFA : option `local` seulement, activée par l'utilisateur lui-même après avoir lu le risque (`get_fx_mode().risks["local"]`, puis `set_fx_mode(mode="local", accept_risk=True)`). `converted` n'est pas ouvert (`fx_mode_unavailable`). diff --git a/src/technas_pay/_version.py b/src/technas_pay/_version.py index dd9b22c..906d362 100644 --- a/src/technas_pay/_version.py +++ b/src/technas_pay/_version.py @@ -1 +1 @@ -__version__ = "0.5.1" +__version__ = "0.6.0" diff --git a/src/technas_pay/app_routes.py b/src/technas_pay/app_routes.py index 762f3c2..e322d28 100644 --- a/src/technas_pay/app_routes.py +++ b/src/technas_pay/app_routes.py @@ -146,8 +146,9 @@ async def _card_method(self, order: AppOrder) -> Dict[str, Any]: return {"method": "card", "available": False, "reason": "card_account_not_ready"} async def _start(self, order_id: str, order: AppOrder, method: str = "mobile_money") -> Any: - # Une référence = un essai : `order_id-1`, `-2`… Un essai expiré lève payment_expired, on - # passe au suivant. Un essai en cours (ou payé) est rendu tel quel : jamais deux paiements. + # Une référence = un essai : `order_id-1`, `-2`… Un essai expiré (payment_expired) ou d'un + # autre montant (reference_conflict : le client a changé d'offre) est sauté : essai suivant, + # jamais un refus. Un essai en cours (ou payé) au même montant est rendu tel quel. attempt = 1 while True: options: Dict[str, Any] = {"metadata": {**order.metadata, "order_id": order_id}} @@ -167,7 +168,7 @@ async def _start(self, order_id: str, order: AppOrder, method: str = "mobile_mon **options, )) except TechnasPayError as e: - if e.code == "payment_expired" and attempt < self._max_attempts: + if e.code in ("payment_expired", "reference_conflict") and attempt < self._max_attempts: attempt += 1 continue raise diff --git a/tests/fake_gateway.py b/tests/fake_gateway.py index f20ef71..0d4cebf 100644 --- a/tests/fake_gateway.py +++ b/tests/fake_gateway.py @@ -119,10 +119,10 @@ def _create(self, body: Dict[str, Any]) -> httpx.Response: return _err(422, "invalid_amount") existing = next((p for p in self.payments.values() if p["reference"] == body["reference"]), None) if existing: - if existing["status"] == "expired": - return _err(409, "payment_expired") if existing["amount"] != body["amount"]: return _err(409, "reference_conflict") + if existing["status"] == "expired": + return _err(409, "payment_expired") return httpx.Response(200, json=existing) pid = f"pay_{uuid.uuid4().hex[:8]}" commission = body["amount"] * 2 // 100 diff --git a/tests/test_client.py b/tests/test_client.py index 6adbc35..d7ca99f 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -86,6 +86,21 @@ def test_une_reference_un_essai(pay): assert ask(pay, ref=retry_reference("cmd_1", 2)).id != first.id +def test_le_client_change_d_offre_ou_revient_plus_tard(pay, gw): + """Le client choisit une offre, ne paie pas, revient plus tard choisir une AUTRE offre : un + nouvel essai, jamais un refus. Réutiliser la référence avec un autre montant est un conflit.""" + first = ask(pay, ref=retry_reference("F", 1), amount=5000) + pay.simulate_test_payment(first.id, "expired") + assert pay.get_payment(first.id).status == "expired" + second = ask(pay, ref=retry_reference("F", 2), amount=7500) + assert second.id != first.id and second.status == "pending" + sent = [json.loads(r.content) for r in gw.requests if r.method == "POST" and r.url.path == "/v1/payments"] + assert [(b["reference"], b["amount"]) for b in sent] == [("F-1", 5000), ("F-2", 7500)] + with pytest.raises(TechnasPayError) as e: + ask(pay, ref="F-1", amount=7500) + assert e.value.code == "reference_conflict" and e.value.status == 409 and not e.value.retryable + + def test_retry_reference(): assert retry_reference("CMD-42", 2) == "CMD-42-2" with pytest.raises(ValueError):