From 4b9fd88914d4b2e97390b51d1cafeb3438044115 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Vihoal=C3=A9=20ANIGLO?= <46029829+JIV-DLS@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:52:19 +0100 Subject: [PATCH] Annuler un paiement : cancelPayment, route d'annulation, changement d'offre sans double paiement (0.4.0) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit cancelPayment(id) → POST /v1/payments/{id}/cancel. Payment : canceledAt, cancelReason, reason (avis payment.expired : canceled ou timeout). Routes toutes faites : POST /payments/{id}/cancel (propriété vérifiée) ; sur reference_conflict, l'ancien essai est relu par sa référence et annulé s'il est ouvert avant l'essai suivant ; payment_in_progress ou payment_already_completed : aucun second paiement. Contrat v1 à 30 cas (query_includes). --- AGENTS.md | 17 +- CHANGELOG.md | 4 + README.md | 12 +- contract/app-contract.v1.json | 471 +++++++++++++++++- examples/kotlin-spring/pom.xml | 2 +- examples/spring-boot/pom.xml | 2 +- llms.txt | 4 +- pom.xml | 2 +- src/main/java/fr/technas/pay/TechnasPay.java | 13 +- .../java/fr/technas/pay/app/AppRoutes.java | 53 +- .../java/fr/technas/pay/model/Payment.java | 11 +- .../java/fr/technas/pay/AppContractTest.java | 12 +- .../fr/technas/pay/ChangementDOffreTest.java | 45 ++ 13 files changed, 618 insertions(+), 30 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 713499f..35bead9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,7 @@ Dépendance JitPack (voir le README) : com.github.Technas-Organization technas-pay-java - v0.3.0 + v0.4.0 ``` @@ -31,7 +31,7 @@ Dépendance JitPack (voir le README) : | Faire payer une commande | `pay.askForPayment(PaymentRequest.builder().amount(5000).reference(Status.retryReference(orderId, attempt)).customer(Customer.of(email, name)).returnUrl(…).build())`, puis rediriger (303) vers `payment.checkoutUrl()` | | Savoir qu'elle est payée | avis signé : `pay.handleWebhook(corpsBrut, signature, WebhookHandlers.builder().onCompleted(…).build())` | | Rattraper un avis manqué | `pay.getPaymentByReference(reference)` | -| Le client change d'offre ou revient plus tard | nouvel essai `Status.retryReference(factureId, n + 1)` ; au retour, `pay.getPayment(dernierPaymentId)` d'abord (voir la section dédiée) | +| Le client change d'offre ou revient plus tard | `pay.cancelPayment(ancienId)`, puis nouvel essai `Status.retryReference(factureId, n + 1)` ; au retour, `pay.getPayment(dernierPaymentId)` d'abord (voir la section dédiée) | | Savoir si on peut relancer | `onExpired`, ou `Status.canRetry(pay.getPayment(id).status())` | | Rembourser | `pay.refund(paymentId)` ou `pay.refund(paymentId, amount, fees, reference)` | | Noter un remboursement fait hors Technas | `pay.recordExternalRefund(paymentId, 2000, "Flooz", null, null, null)` | @@ -56,7 +56,7 @@ Dépendance JitPack (voir le README) : ## App mobile (Flutter) -Ne réécrivez pas de routes : `pay.appRoutes(authorize, resolveOrder).returnUrl(…).webhooks(…).card(?).authorizeAdmin(?).build()`, montées sous `/api/technas-pay` par `TechnasPayServlet.handle(routes, req, res, "/api/technas-pay")` (Spring MVC, Quarkus, Tomcat, Jetty). Hors Servlet : `routes.handle(new AppRequest(…))`. `resolveOrder(orderId, user)` relit la commande EN BASE et rend `null` si elle n'est pas à cet utilisateur. N'y mettez jamais un montant reçu de l'app. Côté app : `TechnasPayClient(baseUrl: '…/api/technas-pay')`. +Ne réécrivez pas de routes : `pay.appRoutes(authorize, resolveOrder).returnUrl(…).webhooks(…).card(?).authorizeAdmin(?).build()`, montées sous `/api/technas-pay` par `TechnasPayServlet.handle(routes, req, res, "/api/technas-pay")` (Spring MVC, Quarkus, Tomcat, Jetty). Hors Servlet : `routes.handle(new AppRequest(…))`. `resolveOrder(orderId, user)` relit la commande EN BASE et rend `null` si elle n'est pas à cet utilisateur. N'y mettez jamais un montant reçu de l'app. Le client change d'offre : l'app appelle `POST /payments/{id}/cancel` sur l'essai affiché, puis `POST /payments` ; si la commande a changé de montant, `POST /payments` annule lui-même l'ancien essai encore ouvert. Côté app : `TechnasPayClient(baseUrl: '…/api/technas-pay')`. ## Obligatoire @@ -136,7 +136,8 @@ Le client choisit une offre, ouvre la page de paiement, ne paie pas, puis revien - **Une référence = un essai.** Nouvelle offre, ou retour après expiration : un NOUVEL essai, `Status.retryReference(factureId, n + 1)`, `n` gardé en base. Réutiliser la référence d'un autre montant lève `reference_conflict` (409) ; celle d'un essai expiré, `payment_expired` (409). Les routes toutes faites (`appRoutes`) le font seules. - **Une facture n'est payée QUE sur `payment.completed`** (`onCompleted`). Jamais sur `returnUrl`, jamais à l'ouverture de la page. -- **Un essai non payé ne bloque jamais un nouvel essai.** Même offre et essai `pending` ou `failed` : renvoyez le client sur la même page (`checkoutUrl()`). Autre offre : créez le nouvel essai, ne refusez pas. `expired` : marquez la tentative expirée et laissez recommencer. +- **Un essai non payé ne bloque jamais un nouvel essai.** Même offre et essai `pending` ou `failed` : renvoyez le client sur la même page (`checkoutUrl()`). Autre offre : ANNULEZ l'ancien essai (`pay.cancelPayment(ancienId)`), puis créez le nouveau avec une NOUVELLE référence ; ne refusez pas. `expired` : marquez la tentative expirée et laissez recommencer. +- **`cancelPayment` refuse quand c'est trop tard** : `payment_already_completed` (le client a payé l'ancienne offre : relisez le paiement, ne créez rien) ; `payment_in_progress` (une demande est en cours chez l'opérateur : ne créez PAS de second paiement, attendez l'avis de l'issue). Un paiement annulé reste `expired` (`canceledAt()`, `cancelReason()`), et son avis `payment.expired` porte `reason()` = `canceled` (`timeout` pour une échéance passée). - **Au retour du client**, vérifiez `pay.getPayment(dernierPaymentId)` avant de dire quoi que ce soit : votre base peut avoir manqué un avis. - **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(paymentId)`. @@ -151,6 +152,11 @@ Payment payer(Facture f, long montant) { if (memeOffre && !"expired".equals(dernier.status()) && dernier.checkoutUrl() != null) { return dernier; // pending ou failed : même page, le client peut encore payer } + if (!"expired".equals(dernier.status())) { + // Autre offre : l'ancien lien est fermé d'abord. payment_in_progress ou + // payment_already_completed remontent : on ne crée alors AUCUN second paiement. + pay.cancelPayment(dernier.id()); + } } int essai = factures.essaiSuivant(f.id()); // n + 1, gardé en base Payment p = pay.askForPayment(PaymentRequest.builder() @@ -257,9 +263,10 @@ Ce n'est PAS le même parcours que le mobile money. Ne le proposez que si l'util | `fx_mode_unavailable`, `fx_channel_unavailable` | Mode `converted` pas ouvert : proposer `local` (avec l'accord de l'utilisateur sur le risque) ou rester en `none` | | `quote_expired` | Le client rechoisit son pays sur la page, rien à faire côté code | | `reference_conflict` | Même référence, autres valeurs : ne pas réutiliser la référence | +| `payment_already_completed` | `cancelPayment` : le paiement est déjà payé. Relire le paiement ; ne créer aucun nouvel essai | | `kyc_required` | Pièce d'identité à déposer : `e.details().get("consoleUrl")`, `reason` (`amount` ou `duration`). Proposer la carte ; ne pas réessayer | | `contract_required` | Le responsable doit accepter le contrat dans la console (`e.details().get("version")`) ; ne pas réessayer | -| `payment_in_progress` | Réessayer dans une minute, même appel | +| `payment_in_progress` | Réessayer dans une minute, même appel. Sur `cancelPayment` : ne créez PAS de second paiement, attendez l'avis de l'issue | | `payment_not_found`, `refund_not_found` | Mauvais identifiant ou autre compte | | `payment_expired` | Cette référence est un essai expiré : nouveau paiement avec une NOUVELLE référence, jamais le même appel | | `payment_not_refundable` | Seul un paiement `completed` se rembourse | diff --git a/CHANGELOG.md b/CHANGELOG.md index 77f70f9..0820d44 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Journal +## 0.4.0 (16/11/2026) + +`cancelPayment(id)` (`POST /v1/payments/{id}/cancel`) : annule un paiement que personne n'a commencé à payer. `Payment` : `canceledAt()`, `cancelReason()`, `reason()` (avis `payment.expired` : `canceled` ou `timeout`). Routes toutes faites : `POST /payments/{id}/cancel`, et sur `reference_conflict` l'ancien essai est relu puis annulé avant le suivant (aucun second paiement si l'annulation répond `payment_in_progress` ou `payment_already_completed`). Contrat v1 à 30 cas. + ## 0.3.0 (15/11/2026) Le client change d'offre ou revient plus tard : les routes toutes faites passent à l'essai suivant sur `reference_conflict` (comme sur `payment_expired`) ; contrat v1 à 24 cas ; section dédiée dans README et AGENTS.md ; test de scénario. diff --git a/README.md b/README.md index a8a9599..0fde135 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Maven : com.github.Technas-Organization technas-pay-java - v0.3.0 + v0.4.0 ``` @@ -32,7 +32,7 @@ Gradle (Kotlin) : ```kotlin repositories { maven("https://jitpack.io") } -dependencies { implementation("com.github.Technas-Organization:technas-pay-java:v0.3.0") } +dependencies { implementation("com.github.Technas-Organization:technas-pay-java:v0.4.0") } ``` Technas vous remet **un secret**. Mettez-le dans les variables d'environnement du serveur : @@ -122,7 +122,7 @@ class TechnasPayRoutes { Hors Servlet (Ktor, Vert.x, Micronaut Netty) : construisez une `AppRequest(method, path, query, headers, rawBody, original)` et renvoyez `routes.handle(req)` (`status()`, `json()`). -Routes : `GET /methods?orderId=`, `POST /payments` `{orderId, method?}`, `GET /payments/{id}`, `POST /webhook` (adresse à déclarer à Technas). Les essais expirés sont sautés tout seuls (`42-1`, `42-2`…) : rien à stocker. Carte : `.card(true)` et une `currency` dans `AppOrder`, puis `.authorizeAdmin(...)` pour l'écran du marchand (`GET /card/account`, `POST /card/onboarding`). Contrat : [`contract/app-contract.v1.json`](contract/app-contract.v1.json), rejoué par ce paquet, les autres SDK et le client Flutter. +Routes : `GET /methods?orderId=`, `POST /payments` `{orderId, method?}`, `GET /payments/{id}`, `POST /payments/{id}/cancel` (le client change d'offre), `POST /webhook` (adresse à déclarer à Technas). Les essais expirés sont sautés tout seuls (`42-1`, `42-2`…) : rien à stocker. Carte : `.card(true)` et une `currency` dans `AppOrder`, puis `.authorizeAdmin(...)` pour l'écran du marchand (`GET /card/account`, `POST /card/onboarding`). Contrat : [`contract/app-contract.v1.json`](contract/app-contract.v1.json), rejoué par ce paquet, les autres SDK et le client Flutter. Exemples complets, compilés en CI : [`examples/spring-boot`](examples/spring-boot) (Java) et [`examples/kotlin-spring`](examples/kotlin-spring) (Kotlin). @@ -131,6 +131,7 @@ Exemples complets, compilés en CI : [`examples/spring-boot`](examples/spring-bo | Méthode | Rôle | |---|---| | `getPayment(id)`, `getPaymentByReference(ref)` | Statut ; rattraper un avis manqué | +| `cancelPayment(id)` | Annuler un paiement que personne n'a commencé à payer (le client change d'offre) | | `listTransactions(limit, status, cursor)` | Historique paginé (`nextCursor()`) | | `refund(paymentId)`, `refund(paymentId, amount, fees, reference)` | Rembourser au numéro ou à la carte qui a payé | | `recordExternalRefund(paymentId, amount, method, note, recordedBy, reference)` | Noter un remboursement fait hors Technas | @@ -175,7 +176,7 @@ Le client choisit une offre, ouvre la page de paiement, ne paie pas, puis revien - **Une référence = un essai.** Nouvelle offre, ou retour après expiration : un NOUVEL essai, `Status.retryReference(factureId, n + 1)`, `n` gardé en base. Réutiliser la référence d'un autre montant lève `reference_conflict` (409) ; celle d'un essai expiré, `payment_expired` (409). Les routes toutes faites (`appRoutes`) le font seules. - **Une facture n'est payée QUE sur `payment.completed`** (`onCompleted`). Jamais sur `returnUrl`, jamais à l'ouverture de la page. -- **Un essai non payé ne bloque jamais un nouvel essai.** Même offre et essai `pending` ou `failed` : renvoyez le client sur la même page (`checkoutUrl()`). Autre offre : créez le nouvel essai, ne refusez pas. `expired` : marquez la tentative expirée et laissez recommencer. +- **Un essai non payé ne bloque jamais un nouvel essai.** Même offre et essai `pending` ou `failed` : renvoyez le client sur la même page (`checkoutUrl()`). Autre offre : ANNULEZ l'ancien essai (`pay.cancelPayment(ancienId)`), puis créez le nouveau avec une NOUVELLE référence ; ne refusez pas. Si l'annulation répond `payment_in_progress` ou `payment_already_completed`, ne créez aucun second paiement. `expired` : marquez la tentative expirée et laissez recommencer. - **Au retour du client**, vérifiez `pay.getPayment(dernierPaymentId)` avant de dire quoi que ce soit : votre base peut avoir manqué un avis. - **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(paymentId)`. @@ -190,6 +191,9 @@ Payment payer(Facture f, long montant) { if (memeOffre && !"expired".equals(dernier.status()) && dernier.checkoutUrl() != null) { return dernier; // pending ou failed : même page, le client peut encore payer } + if (!"expired".equals(dernier.status())) { + pay.cancelPayment(dernier.id()); // autre offre : l'ancien lien est fermé d'abord + } } int essai = factures.essaiSuivant(f.id()); // n + 1, gardé en base Payment p = pay.askForPayment(PaymentRequest.builder() diff --git a/contract/app-contract.v1.json b/contract/app-contract.v1.json index 191a3dc..4c9f883 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. 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'.", + "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) est sauté. Un essai dont le montant ne correspond plus (reference_conflict : le client a changé d'offre) est relu par sa référence (GET /v1/payments?reference=), annulé s'il est encore ouvert (POST /v1/payments/{id}/cancel), puis l'essai suivant est créé ; si l'annulation répond payment_in_progress ou payment_already_completed, aucun second paiement n'est créé et l'erreur est rendue à l'app. 'query_includes' : paramètres attendus dans l'adresse. Le paiement rendu à l'app porte 'method'.", "routes": [ { "method": "GET", @@ -22,6 +22,12 @@ "auth": true, "response": "{payment: toAppJson}" }, + { + "method": "POST", + "path": "/payments/{id}/cancel", + "auth": true, + "response": "{payment: toAppJson} (status expired, checkout_url null)" + }, { "method": "POST", "path": "/webhook", @@ -43,7 +49,7 @@ "response": "{url, kind, expires_at, account}" } ], - "errors": "{code, message, retryable} ; 400 invalid_request, 401 unauthorized, 404 order_not_found | payment_not_found | not_found, 409/4xx code de Technas transmis, 502 Technas injoignable ou en panne (retryable true) ; 400 method_not_available (carte non ouverte par le marchand), 403 forbidden (routes du marchand)", + "errors": "{code, message, retryable} ; 400 invalid_request, 401 unauthorized, 404 order_not_found | payment_not_found | not_found, 409/4xx code de Technas transmis, 502 Technas injoignable ou en panne (retryable true) ; 400 method_not_available (carte non ouverte par le marchand), 403 forbidden (routes du marchand) ; 409 payment_in_progress (retryable true) et payment_already_completed (changement d'offre ou annulation)", "cases": [ { "name": "démarrer : premier essai", @@ -201,7 +207,7 @@ } }, { - "name": "démarrer : le client a changé d'offre (autre montant) → essai suivant, jamais un refus", + "name": "démarrer : le client a changé d'offre (autre montant) → l'ancien essai est annulé, puis le suivant est créé", "request": { "method": "POST", "path": "/payments", @@ -227,6 +233,42 @@ "message": "m" } }, + { + "status": 200, + "body": { + "id": "pay_1", + "reference": "42-1", + "amount": 5000, + "currency": null, + "commission": 100, + "net_amount": 4900, + "status": "pending", + "checkout_url": "https://pay-api.technas.fr/checkout/pay_1", + "metadata": {}, + "test_mode": true, + "created_at": "2026-11-15T10:00:00Z", + "expires_at": "2026-11-15T11:00:00Z" + } + }, + { + "status": 200, + "body": { + "id": "pay_1", + "reference": "42-1", + "amount": 5000, + "currency": null, + "commission": 100, + "net_amount": 4900, + "status": "expired", + "checkout_url": null, + "metadata": {}, + "test_mode": true, + "created_at": "2026-11-15T10:00:00Z", + "expires_at": "2026-11-15T11:00:00Z", + "canceled_at": "2026-11-16T09:00:00Z", + "cancel_reason": "canceled_by_partner" + } + }, { "status": 201, "body": { @@ -254,6 +296,17 @@ "reference": "42-1" } }, + { + "method": "GET", + "path": "/v1/payments", + "query_includes": { + "reference": "42-1" + } + }, + { + "method": "POST", + "path": "/v1/payments/pay_1/cancel" + }, { "method": "POST", "path": "/v1/payments", @@ -279,6 +332,271 @@ } } }, + { + "name": "démarrer : changement d'offre, l'ancien essai avait déjà expiré → pas d'annulation, essai suivant", + "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": 200, + "body": { + "id": "pay_1", + "reference": "42-1", + "amount": 5000, + "currency": null, + "commission": 100, + "net_amount": 4900, + "status": "expired", + "checkout_url": null, + "metadata": {}, + "test_mode": true, + "created_at": "2026-11-15T10:00:00Z", + "expires_at": "2026-11-15T11:00:00Z" + } + }, + { + "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": "GET", + "path": "/v1/payments", + "query_includes": { + "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 : changement d'offre pendant une demande en cours chez l'opérateur → aucun second paiement", + "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": 200, + "body": { + "id": "pay_1", + "reference": "42-1", + "amount": 5000, + "currency": null, + "commission": 100, + "net_amount": 4900, + "status": "pending", + "checkout_url": "https://pay-api.technas.fr/checkout/pay_1", + "metadata": {}, + "test_mode": true, + "created_at": "2026-11-15T10:00:00Z", + "expires_at": "2026-11-15T11:00:00Z" + } + }, + { + "status": 409, + "body": { + "code": "payment_in_progress", + "message": "m" + } + } + ], + "expect_gateway": [ + { + "method": "POST", + "path": "/v1/payments", + "body_includes": { + "amount": 7500, + "reference": "42-1" + } + }, + { + "method": "GET", + "path": "/v1/payments", + "query_includes": { + "reference": "42-1" + } + }, + { + "method": "POST", + "path": "/v1/payments/pay_1/cancel" + } + ], + "expect": { + "status": 409, + "body": { + "code": "payment_in_progress", + "retryable": true + } + } + }, + { + "name": "démarrer : changement d'offre alors que l'ancien essai vient d'être payé → aucun second paiement", + "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": 200, + "body": { + "id": "pay_1", + "reference": "42-1", + "amount": 5000, + "currency": null, + "commission": 100, + "net_amount": 4900, + "status": "pending", + "checkout_url": "https://pay-api.technas.fr/checkout/pay_1", + "metadata": {}, + "test_mode": true, + "created_at": "2026-11-15T10:00:00Z", + "expires_at": "2026-11-15T11:00:00Z" + } + }, + { + "status": 409, + "body": { + "code": "payment_already_completed", + "message": "m" + } + } + ], + "expect_gateway": [ + { + "method": "POST", + "path": "/v1/payments", + "body_includes": { + "amount": 7500, + "reference": "42-1" + } + }, + { + "method": "GET", + "path": "/v1/payments", + "query_includes": { + "reference": "42-1" + } + }, + { + "method": "POST", + "path": "/v1/payments/pay_1/cancel" + } + ], + "expect": { + "status": 409, + "body": { + "code": "payment_already_completed", + "retryable": false + } + } + }, { "name": "démarrer : le montant ne vient jamais du téléphone", "request": { @@ -1023,6 +1341,153 @@ } } }, + { + "name": "annuler son paiement (le client change d'offre) → expiré, plus de lien", + "request": { + "method": "POST", + "path": "/payments/pay_1/cancel" + }, + "user": "u1", + "orders": { + "42": { + "amount": 5000, + "customer": { + "email": "awa@exemple.tg", + "name": "Awa Mensah" + } + } + }, + "gateway": [ + { + "status": 200, + "body": { + "id": "pay_1", + "reference": "42-1", + "amount": 5000, + "currency": null, + "commission": 100, + "net_amount": 4900, + "status": "pending", + "checkout_url": "https://pay-api.technas.fr/checkout/pay_1", + "metadata": {}, + "test_mode": true, + "created_at": "2026-11-15T10:00:00Z", + "expires_at": "2026-11-15T11:00:00Z" + } + }, + { + "status": 200, + "body": { + "id": "pay_1", + "reference": "42-1", + "amount": 5000, + "currency": null, + "commission": 100, + "net_amount": 4900, + "status": "expired", + "checkout_url": null, + "metadata": {}, + "test_mode": true, + "created_at": "2026-11-15T10:00:00Z", + "expires_at": "2026-11-15T11:00:00Z", + "canceled_at": "2026-11-16T09:00:00Z", + "cancel_reason": "canceled_by_partner" + } + } + ], + "expect_gateway": [ + { + "method": "GET", + "path": "/v1/payments/pay_1" + }, + { + "method": "POST", + "path": "/v1/payments/pay_1/cancel" + } + ], + "expect": { + "status": 200, + "body": { + "payment": { + "id": "pay_1", + "reference": "42-1", + "status": "expired", + "checkout_url": null, + "amount": 5000, + "currency": null, + "expires_at": "2026-11-15T11:00:00Z", + "method": "mobile_money" + } + } + } + }, + { + "name": "annuler le paiement d'une commande qui n'est pas la sienne → 404, rien n'est annulé", + "request": { + "method": "POST", + "path": "/payments/pay_9/cancel" + }, + "user": "u1", + "orders": { + "42": { + "amount": 5000, + "customer": { + "email": "awa@exemple.tg", + "name": "Awa Mensah" + } + } + }, + "gateway": [ + { + "status": 200, + "body": { + "id": "pay_9", + "reference": "99-1", + "amount": 5000, + "currency": null, + "commission": 100, + "net_amount": 4900, + "status": "pending", + "checkout_url": "https://pay-api.technas.fr/checkout/pay_1", + "metadata": {}, + "test_mode": true, + "created_at": "2026-11-15T10:00:00Z", + "expires_at": "2026-11-15T11:00:00Z" + } + } + ], + "expect_gateway": [ + { + "method": "GET", + "path": "/v1/payments/pay_9" + } + ], + "expect": { + "status": 404, + "body": { + "code": "payment_not_found", + "retryable": false + } + } + }, + { + "name": "annuler sans authentification → 401", + "request": { + "method": "POST", + "path": "/payments/pay_1/cancel" + }, + "user": null, + "orders": {}, + "gateway": [], + "expect_gateway": [], + "expect": { + "status": 401, + "body": { + "code": "unauthorized", + "retryable": false + } + } + }, { "name": "compte carte : réservé au marchand (sans authorizeAdmin, la route n'existe pas)", "request": { diff --git a/examples/kotlin-spring/pom.xml b/examples/kotlin-spring/pom.xml index 7e1d22d..b0ea31b 100644 --- a/examples/kotlin-spring/pom.xml +++ b/examples/kotlin-spring/pom.xml @@ -28,7 +28,7 @@ fr.technas technas-pay - 0.3.0 + 0.4.0 diff --git a/examples/spring-boot/pom.xml b/examples/spring-boot/pom.xml index 77ebe40..fc2b826 100644 --- a/examples/spring-boot/pom.xml +++ b/examples/spring-boot/pom.xml @@ -23,7 +23,7 @@ fr.technas technas-pay - 0.3.0 + 0.4.0 diff --git a/llms.txt b/llms.txt index a15ce0a..349f94f 100644 --- a/llms.txt +++ b/llms.txt @@ -1,10 +1,10 @@ # technas-pay-java (Java, Kotlin) -> SDK Java 17+ et Kotlin (côté serveur : Spring Boot, Quarkus, Micronaut, Ktor) pour encaisser du mobile money en Afrique et des paiements par carte via Technas Pay, rembourser et recharger son solde. Une dépendance (jackson-databind). Montant seul, en F CFA : la devise (XOF ou XAF) suit le pays du client. Installation depuis GitHub par JitPack : com.github.Technas-Organization:technas-pay-java:v0.3.0. +> SDK Java 17+ et Kotlin (côté serveur : Spring Boot, Quarkus, Micronaut, Ktor) pour encaisser du mobile money en Afrique et des paiements par carte via Technas Pay, rembourser et recharger son solde. Une dépendance (jackson-databind). Montant seul, en F CFA : la devise (XOF ou XAF) suit le pays du client. Installation depuis GitHub par JitPack : com.github.Technas-Organization:technas-pay-java:v0.4.0. Agents de code : lisez d'abord AGENTS.md. -Client qui change d'offre ou revient plus tard : nouvel essai (référence suivante), jamais « paiement déjà existant » ; payé seulement sur payment.completed ; au retour, getPayment(dernierPaymentId) d'abord ; un second paiement réussi se rembourse. +Client qui change d'offre ou revient plus tard : cancelPayment(ancienId) puis nouvel essai (référence suivante), jamais « paiement déjà existant » ; payé seulement sur payment.completed ; au retour, getPayment(dernierPaymentId) d'abord ; un second paiement réussi se rembourse. Une référence = un essai : `Status.retryReference(orderId, attempt)`. Relancez avec une NOUVELLE référence seulement après payment.expired (`Status.canRetry`), jamais sur failed. diff --git a/pom.xml b/pom.xml index 0449259..a4dcbd7 100644 --- a/pom.xml +++ b/pom.xml @@ -4,7 +4,7 @@ 4.0.0 fr.technas technas-pay - 0.3.0 + 0.4.0 Technas Pay Encaisser du mobile money et des paiements par carte via Technas Pay depuis Java ou Kotlin (Spring Boot, Jakarta Servlet). https://github.com/Technas-Organization/technas-pay-java diff --git a/src/main/java/fr/technas/pay/TechnasPay.java b/src/main/java/fr/technas/pay/TechnasPay.java index eb9ca74..e1ce91d 100644 --- a/src/main/java/fr/technas/pay/TechnasPay.java +++ b/src/main/java/fr/technas/pay/TechnasPay.java @@ -50,7 +50,7 @@ * } */ public final class TechnasPay { - public static final String VERSION = "0.3.0"; + public static final String VERSION = "0.4.0"; public static final String DEFAULT_BASE_URL = "https://pay-api.technas.fr"; public static final String SECRET_ENV = "TECHNAS_PAY_SECRET"; private static final Pattern SECRET = Pattern.compile("^tps_(live|test)_([\\x21-\\x2d\\x2f-\\x7e]+)\\.([\\x21-\\x2d\\x2f-\\x7e]+)$"); // ASCII imprimable sans « . » @@ -248,6 +248,17 @@ public Payment getPayment(String id) { return Payment.fromJson(call("GET", "/v1/payments/" + seg(id), null)); } + /** + * Annule DÉFINITIVEMENT un paiement que personne n'a commencé à payer (le client change d'offre) : + * rien ne peut plus aboutir dessus. Rend le paiement, {@code expired}, sans lien. Rejouer rend le + * même résultat. Refus : {@code payment_already_completed} (payé : relisez-le), + * {@code payment_in_progress} (une demande est en cours chez l'opérateur : ne créez PAS de second + * paiement, attendez l'avis). Puis créez le nouvel essai avec une NOUVELLE référence. + */ + public Payment cancelPayment(String id) { + return Payment.fromJson(call("POST", "/v1/payments/" + seg(id) + "/cancel", Json.object())); + } + /** Pour rattraper un avis manqué. */ public Payment getPaymentByReference(String reference) { return Payment.fromJson(call("GET", "/v1/payments?reference=" + q(reference), null)); diff --git a/src/main/java/fr/technas/pay/app/AppRoutes.java b/src/main/java/fr/technas/pay/app/AppRoutes.java index d2e8788..28e7fb8 100644 --- a/src/main/java/fr/technas/pay/app/AppRoutes.java +++ b/src/main/java/fr/technas/pay/app/AppRoutes.java @@ -34,6 +34,7 @@ */ public final class AppRoutes { private static final Pattern PAYMENT_PATH = Pattern.compile("^/payments/([^/]+)$"); + private static final Pattern CANCEL_PATH = Pattern.compile("^/payments/([^/]+)/cancel$"); private static final Pattern ATTEMPT = Pattern.compile("^(.+?)-(?:card-)?\\d+$"); /** Identifiant de commande ou de paiement accepté de l'app : court, sans « / », « . » ni espace. */ private static final Pattern ID = Pattern.compile("^[A-Za-z0-9_-]{1,128}$"); @@ -133,16 +134,42 @@ private Payment start(String orderId, AppOrder order, String method) { .currency(order.currency()) .description(order.description()) .metadata(meta); + PaymentRequest request = r.build(); try { - return pay.askForPayment(r.build()); + return pay.askForPayment(request); } catch (TechnasPayException e) { - // Essai expiré, ou référence d'un autre montant (le client a changé d'offre) : essai - // suivant. Un essai non payé ne bloque jamais un nouvel essai. - if (("payment_expired".equals(e.code()) || "reference_conflict".equals(e.code())) && attempt < maxAttempts) { - continue; + if (attempt >= maxAttempts) { + throw e; } - throw e; + if ("payment_expired".equals(e.code())) { + continue; // essai expiré : le suivant + } + if (!"reference_conflict".equals(e.code())) { + throw e; + } + // Le client a changé d'offre (autre montant) : l'ancien essai est annulé s'il est encore + // ouvert, puis le suivant est créé. Payé ou demande en cours chez l'opérateur : aucun + // second paiement, l'erreur remonte à l'app. + closePrevious(request.reference()); + } + } + } + + private void closePrevious(String reference) { + Payment previous; + try { + previous = pay.getPaymentByReference(reference); + } catch (TechnasPayException e) { + if ("payment_not_found".equals(e.code())) { + return; } + throw e; + } + if ("completed".equals(previous.status())) { + throw new TechnasPayException("payment_already_completed", "L'essai précédent de cette commande est déjà payé", 409, Map.of()); + } + if (!"expired".equals(previous.status())) { + pay.cancelPayment(previous.id()); } } @@ -227,7 +254,10 @@ public AppResponse handle(AppRequest req) { } Matcher pm = PAYMENT_PATH.matcher(path); boolean isPayment = pm.matches(); - boolean known = ("GET".equals(method) && ("/methods".equals(path) || isPayment)) || ("POST".equals(method) && "/payments".equals(path)); + Matcher cm = CANCEL_PATH.matcher(path); + boolean isCancel = cm.matches(); + boolean known = ("GET".equals(method) && ("/methods".equals(path) || isPayment)) + || ("POST".equals(method) && ("/payments".equals(path) || isCancel)); if (!known) { return err(404, "not_found", "Route inconnue"); } @@ -288,8 +318,9 @@ public AppResponse handle(AppRequest req) { } return new AppResponse(200, Map.of("payment", start(orderId, order, payMethod).toAppJson())); } - // GET /payments/{id} : seulement si la commande de ce paiement est à cet utilisateur. - String id = URLDecoder.decode(pm.group(1), StandardCharsets.UTF_8); + // GET /payments/{id} et POST /payments/{id}/cancel : seulement si la commande de ce paiement + // est à cet utilisateur. + String id = URLDecoder.decode((isCancel ? cm : pm).group(1), StandardCharsets.UTF_8); if (!ID.matcher(id).matches()) { return err(404, "payment_not_found", "Paiement introuvable"); } @@ -306,6 +337,10 @@ public AppResponse handle(AppRequest req) { if (orderId == null || resolveOrder.apply(orderId, user) == null) { return err(404, "payment_not_found", "Paiement introuvable"); } + if (isCancel) { + // Le client change d'offre : l'essai affiché est annulé avant d'en démarrer un autre. + payment = pay.cancelPayment(payment.id()); + } return new AppResponse(200, Map.of("payment", payment.toAppJson())); } catch (TechnasPayException e) { return fromPayError(e); diff --git a/src/main/java/fr/technas/pay/model/Payment.java b/src/main/java/fr/technas/pay/model/Payment.java index 8ae377d..d241b5e 100644 --- a/src/main/java/fr/technas/pay/model/Payment.java +++ b/src/main/java/fr/technas/pay/model/Payment.java @@ -12,12 +12,18 @@ * @param status {@code pending}, {@code completed}, {@code failed} (PAS définitif), {@code expired} (définitif), {@code amount_mismatch} * @param method {@code mobile_money} ou {@code card} * @param checkoutUrl {@code null} après expiration : n'envoyez jamais un ancien lien + * @param canceledAt quand vous l'avez annulé ({@code cancelPayment}) ; {@code null} sinon. Un paiement + * annulé est {@code expired} : {@code Status.canRetry} et vos états marchent tels quels + * @param cancelReason {@code canceled_by_partner}, ou {@code null} + * @param reason dans l'avis {@code payment.expired} : {@code canceled} (annulé par vous) ou + * {@code timeout} (échéance passée) ; {@code null} dans un avis plus ancien */ public record Payment( String id, String reference, BigDecimal amount, String currency, BigDecimal commission, BigDecimal netAmount, String status, String method, BigDecimal refundedAmount, BigDecimal originalAmount, String originalCurrency, String checkoutUrl, Map metadata, boolean testMode, - String createdAt, String completedAt, String expiresAt, String expiredAt) { + String createdAt, String completedAt, String expiresAt, String expiredAt, + String canceledAt, String cancelReason, String reason) { public static Payment fromJson(JsonNode r) { String method = Json.nstr(r, "method"); @@ -27,7 +33,8 @@ public static Payment fromJson(JsonNode r) { method == null ? "mobile_money" : method, Json.num(r, "refunded_amount"), Json.nnum(r, "original_amount"), Json.nstr(r, "original_currency"), Json.nstr(r, "checkout_url"), Json.map(r, "metadata"), Json.bool(r, "test_mode"), Json.nstr(r, "created_at"), - Json.nstr(r, "completed_at"), Json.nstr(r, "expires_at"), Json.nstr(r, "expired_at")); + Json.nstr(r, "completed_at"), Json.nstr(r, "expires_at"), Json.nstr(r, "expired_at"), + Json.nstr(r, "canceled_at"), Json.nstr(r, "cancel_reason"), Json.nstr(r, "reason")); } /** diff --git a/src/test/java/fr/technas/pay/AppContractTest.java b/src/test/java/fr/technas/pay/AppContractTest.java index 2999690..5aca13d 100644 --- a/src/test/java/fr/technas/pay/AppContractTest.java +++ b/src/test/java/fr/technas/pay/AppContractTest.java @@ -103,10 +103,20 @@ Stream contrat() throws IOException { assertEquals(e.get("path").asText(), URI.create(gw.calls.get(i).url()).getRawPath()); JsonNode sent = gw.calls.get(i).json(); e.path("body_includes").properties().forEach(kv -> assertJsonEquals(kv.getValue(), sent.path(kv.getKey()))); + String rawQuery = URI.create(gw.calls.get(i).url()).getRawQuery(); + Map q = new HashMap<>(); + if (rawQuery != null) { + for (String part : rawQuery.split("&")) { + String[] kv2 = part.split("=", 2); + q.put(java.net.URLDecoder.decode(kv2[0], StandardCharsets.UTF_8), + kv2.length > 1 ? java.net.URLDecoder.decode(kv2[1], StandardCharsets.UTF_8) : ""); + } + } + e.path("query_includes").properties().forEach(kv -> assertEquals(kv.getValue().asText(), q.get(kv.getKey()), kv.getKey())); } })); } - assertEquals(24, tests.size(), "le contrat v1 a 24 cas"); + assertEquals(30, tests.size(), "le contrat v1 a 30 cas"); return tests.stream(); } diff --git a/src/test/java/fr/technas/pay/ChangementDOffreTest.java b/src/test/java/fr/technas/pay/ChangementDOffreTest.java index 928fea3..6d628e8 100644 --- a/src/test/java/fr/technas/pay/ChangementDOffreTest.java +++ b/src/test/java/fr/technas/pay/ChangementDOffreTest.java @@ -40,4 +40,49 @@ void essaiExpirePuisNouvelleOffre() { assertEquals(409, e.status()); assertFalse(e.retryable()); } + + @Test + void annulerLAncienEssaiPuisCreerLeNouveau() { + Map annule = new java.util.LinkedHashMap<>(ClientTest.payment(Map.of("id", "pay_1", "reference", "F-1", "status", "expired", + "canceled_at", "2026-11-16T09:00:00Z", "cancel_reason", "canceled_by_partner"))); + annule.put("checkout_url", null); + FakeTransport t = new FakeTransport() + .reply(200, annule) + .reply(200, annule) + .reply(409, Map.of("code", "payment_in_progress", "message", "m")) + .reply(409, Map.of("code", "payment_already_completed", "message", "m")); + TechnasPay pay = ClientTest.pay(t); + Payment p = pay.cancelPayment("pay_1"); + assertEquals("POST", t.calls.get(0).method()); + assertEquals("https://gw.test/v1/payments/pay_1/cancel", t.calls.get(0).url()); + assertEquals("expired", p.status()); + assertEquals(null, p.checkoutUrl()); + assertEquals("2026-11-16T09:00:00Z", p.canceledAt()); + assertEquals("canceled_by_partner", p.cancelReason()); + assertEquals(true, Status.canRetry(p.status())); + assertEquals("2026-11-16T09:00:00Z", pay.cancelPayment("pay_1").canceledAt(), "rejouer rend le même résultat"); + TechnasPayException enCours = assertThrows(TechnasPayException.class, () -> pay.cancelPayment("pay_1")); + assertEquals("payment_in_progress", enCours.code()); + TechnasPayException paye = assertThrows(TechnasPayException.class, () -> pay.cancelPayment("pay_1")); + assertEquals("payment_already_completed", paye.code()); + assertFalse(paye.retryable()); + assertThrows(TechnasPayException.class, () -> pay.cancelPayment("../balance")); + assertEquals(4, t.calls.size()); + } + + @Test + void avisExpireDitPourquoi() { + TechnasPay pay = ClientTest.pay(new FakeTransport()); + java.util.List seen = new java.util.ArrayList<>(); + fr.technas.pay.webhook.WebhookHandlers h = fr.technas.pay.webhook.WebhookHandlers.builder() + .onExpired(e -> seen.add(e.payment().reason() + "/" + e.payment().canceledAt())).build(); + for (String data : new String[] { + "{\"id\":\"p\",\"reference\":\"F-1\",\"status\":\"expired\",\"amount\":1,\"currency\":\"XOF\",\"reason\":\"canceled\",\"canceled_at\":\"2026-11-16T09:00:00Z\"}", + "{\"id\":\"p\",\"reference\":\"F-1\",\"status\":\"expired\",\"amount\":1,\"currency\":\"XOF\",\"reason\":\"timeout\"}", + "{\"id\":\"p\",\"reference\":\"F-1\",\"status\":\"expired\",\"amount\":1,\"currency\":\"XOF\"}"}) { + String body = "{\"id\":\"e\",\"type\":\"payment.expired\",\"created_at\":\"x\",\"data\":" + data + "}"; + pay.handleWebhook(body, fr.technas.pay.webhook.Signature.sign(body, ClientTest.WEBHOOK_SECRET), h); + } + assertEquals(java.util.List.of("canceled/2026-11-16T09:00:00Z", "timeout/null", "null/null"), seen); + } }