Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 43 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
```


Expand All @@ -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`) |
Expand Down Expand Up @@ -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

Expand Down
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
34 changes: 33 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
83 changes: 81 additions & 2 deletions contract/app-contract.v1.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -1088,4 +1167,4 @@
}
}
]
}
}
2 changes: 2 additions & 0 deletions llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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`).
Expand Down
2 changes: 1 addition & 1 deletion src/technas_pay/_version.py
Original file line number Diff line number Diff line change
@@ -1 +1 @@
__version__ = "0.5.1"
__version__ = "0.6.0"
7 changes: 4 additions & 3 deletions src/technas_pay/app_routes.py
Original file line number Diff line number Diff line change
Expand Up @@ -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}}
Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions tests/fake_gateway.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 15 additions & 0 deletions tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
Loading