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
15 changes: 13 additions & 2 deletions 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.4.2"
pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.5.0"
```


Expand All @@ -39,6 +39,7 @@ Créez UNE instance au niveau du module (`pay = TechnasPay()`) : elle lit `TECHN
| Savoir que le remboursement est arrivé | `on_refund` (`refund.completed`, `refund.failed`, `refund.recorded`) |
| Recharger le solde | `pay.top_up_balance(amount=..., currency="XOF")`, ouvrir `checkout_url` ; `on_top_up` |
| Solde, reversements | `pay.get_balance()`, `pay.get_settlements()` |
| Seuil d'identité du compte (à montrer au marchand) | `pay.get_account_kyc()` ; avis `on_kyc_required` |
| Historique | `pay.list_transactions(limit=, status=, cursor=)` |
| Pays hors zone CFA ouverts, risques | `pay.get_fx_mode()` |
| Activer une option hors zone (après accord explicite) | `pay.set_fx_mode(mode="local", accept_risk=True)` |
Expand Down Expand Up @@ -94,6 +95,14 @@ Ne réécrivez pas de routes : `pay.app_routes(authorize=..., resolve_order=...,
5. **Tableau de bord** (virements, litiges) : `pay.get_card_dashboard_link()` → le tableau de bord de votre compte carte, où le responsable se connecte avec SES identifiants.
6. **App mobile** : `pay.app_routes(..., card=True, authorize_admin=...)` ; `/methods` n'ouvre la carte que si le compte est prêt et que `resolve_order` rend une `currency`.

## Seuil d'identité

- **La règle** : en réel, un compte sans pièce d'identité vérifiée voit ses NOUVEAUX paiements mobile money refusés (`kyc_required`) au-delà de 1 000 000 F CFA encaissés en cumul ou de 30 jours après son premier paiement réel encaissé. Rien de ce qui existe n'est bloqué (paiement en cours, remboursement, reversement, lecture). La carte n'est pas concernée. Le responsable dépose sa pièce dans la console (`console_url`).
- **Afficher l'état** : `pay.get_account_kyc()` dans l'espace d'administration du MARCHAND (jamais au client final) : `stage` (`ok`, `soon`, `blocked`, `verified`, `not_applicable`), `collected_xof` / `threshold_xof`, `deadline`, `console_url`. Une valeur inconnue de `stage`, `level` ou `reason` est une chaîne : traitez-la comme « à vérifier », sans planter.
- **Prévenir le responsable** : branchez `WebhookHandlers(on_kyc_required=...)` (avis `account.kyc_required`, à 80 % du seuil, 7 jours avant l'échéance, puis au premier refus) ; `event.kyc_required.reason` vaut `amount_80`, `deadline_7d` ou `blocked`.
- **Sur `kyc_required`** : proposez la carte, ou expliquez au client que le paiement mobile money n'est pas disponible pour le moment. **Ne réessayez jamais.**
- **Les chiffres viennent de l'API** (`threshold_xof`, `grace_days`, `warn_from_xof`) : n'écrivez jamais 1 000 000 ni 30 dans le code.

## Sécurité

- **Le secret reste côté serveur** : ni template, ni réponse JSON, ni log, ni commit, ni URL.
Expand Down Expand Up @@ -132,7 +141,7 @@ Ne réécrivez pas de routes : `pay.app_routes(authorize=..., resolve_order=...,

## Erreurs

Attrapez `TechnasPayError` et testez `error.code` (jamais le message). `error.retryable` vrai : refaites **le même appel**, mêmes valeurs. `error.details` : `missing_amount`, `refundable_amount`, `reason`, `risk`.
Attrapez `TechnasPayError` et testez `error.code` (jamais le message). `error.retryable` vrai : refaites **le même appel**, mêmes valeurs. `error.details` : `missing_amount`, `refundable_amount`, `reason`, `risk`, `account_status`, `console_url`, `version`.

| `error.code` | Que faire |
|---|---|
Expand Down Expand Up @@ -160,6 +169,8 @@ Attrapez `TechnasPayError` et testez `error.code` (jamais le message). `error.re
| `rate_limited` | Ralentir, réessayer |
| `card_account_not_ready` | Compte carte pas prêt : `error.details.account_status` ; finir `start_card_onboarding` |
| `currency_required` | Paiement par carte : passer `currency` |
| `kyc_required` | Seuil d'identité dépassé (`error.details.reason` : `amount` ou `duration`) : 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 `error.details.console_url` |
| `contract_required` | Le responsable accepte le contrat `error.details.version` dans la console (`error.details.console_url`) ; ne pas réessayer avant |
| `test_only` | Fonction de test appelée avec un secret réel |

## Vérifier l'intégration
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.5.0 — 2026-11-15

Seuil d'identité : `get_account_kyc()` (`GET /v1/account/kyc`) rend un `AccountKyc` (`stage`, `level`, `collected_xof`, `threshold_xof`, `grace_days`, `deadline`, `console_url`…). Avis `account.kyc_required` : fonction `on_kyc_required`, contenu typé `event.kyc_required` (`KycRequired`). Erreurs `kyc_required` et `contract_required` (409, non rejouables) : `details.console_url` et `details.version`. Les valeurs inconnues de `stage`, `level` et `reason` sont gardées telles quelles.

## 0.4.2 — 2026-11-15

Remboursement par carte : `Refund.kind` vaut désormais `"card"` (valeurs : `"payout"` | `"external"` | `"card"`). Pendant la transition, un `"stripe"` encore renvoyé par l'API est lu comme `"card"`. Documentation : carte à 1 % (plus les frais de votre compte carte), mobile money à 2 % (les frais de l'opérateur sont payés par le client).
Expand Down
19 changes: 17 additions & 2 deletions 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.4.2"
pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.5.0"
```

Seule dépendance : `httpx`. Python 3.9 ou plus récent.
Expand Down Expand Up @@ -72,7 +72,7 @@ return 200, result.body

Exemples complets, testés : [FastAPI](examples/fastapi_app.py), [Flask](examples/flask_app.py), [Django](examples/django_app/views.py).

Fonctions disponibles : `on_completed`, `on_failed` (pas définitif), `on_expired` (définitif), `on_refund`, `on_top_up`, `on_payout_destination`, `on_balance_converted`, `on_fx_mode_updated`. Un type inconnu est acquitté sans rien appeler. Une exception dans votre fonction doit remonter : Technas relivrera.
Fonctions disponibles : `on_completed`, `on_failed` (pas définitif), `on_expired` (définitif), `on_refund`, `on_top_up`, `on_payout_destination`, `on_balance_converted`, `on_fx_mode_updated`, `on_card_account_updated`, `on_kyc_required` (seuil d'identité, voir plus bas). Un type inconnu est acquitté sans rien appeler. Une exception dans votre fonction doit remonter : Technas relivrera.

## Pour une app mobile : les routes toutes faites

Expand Down Expand Up @@ -106,6 +106,7 @@ Routes : `GET /methods?orderId=`, `POST /payments` `{orderId}`, `GET /payments/{
| `get_refund(id)` | Statut d'un remboursement |
| `top_up_balance(amount=, currency=, return_url=?)` | Recharger le solde (ouvrir `checkout_url`) |
| `get_balance()`, `get_settlements()` | Solde par devise, reversements |
| `get_account_kyc()` | Seuil d'identité du compte (à montrer au marchand) |
| `get_fx_mode()`, `set_fx_mode(mode=, accept_risk=, markup_pct=?)` | Clients hors zone franc CFA (option à risque) |
| `set_country_rules(allowed=?, excluded=?)` | Où vous vendez |
| `get_payout_networks(country)`, `get_payout_destination()`, `set_payout_destination(...)` | Numéro de reversement |
Expand Down Expand Up @@ -133,8 +134,22 @@ except TechnasPayError as e:
raise
```

`kyc_required` (409) : seuil d'identité dépassé, les nouveaux paiements mobile money sont refusés. Ne réessayez jamais : proposez la carte, ou dites au client que le mobile money n'est pas disponible pour le moment. `e.details.console_url` : où le responsable dépose sa pièce ; `e.details.reason` : `amount` ou `duration`. `contract_required` (409) : le responsable accepte le contrat `e.details.version` dans la console (`e.details.console_url`). Aucun des deux n'est `retryable`.

La liste complète des codes et quoi faire est dans [AGENTS.md](AGENTS.md#erreurs).

## Seuil d'identité

En réel, un compte sans pièce d'identité vérifiée voit ses **nouveaux** paiements mobile money refusés (`kyc_required`) au-delà de 1 000 000 F CFA encaissés en cumul, ou 30 jours après son premier paiement réel encaissé. Rien de ce qui existe n'est bloqué : paiement en cours, remboursement, reversement, lecture. La carte n'est pas concernée. Le responsable dépose sa pièce dans la console (`console_url`).

```python
kyc = pay.get_account_kyc() # à montrer au marchand, jamais au client final
if kyc.stage in ("soon", "blocked"):
show_banner(f"{kyc.collected_xof} / {kyc.threshold_xof} F CFA, échéance {kyc.deadline}", kyc.console_url)
```

Les chiffres (seuil, délai) viennent de l'API (`threshold_xof`, `grace_days`) : ne les écrivez jamais en dur. Branchez `on_kyc_required` pour prévenir le responsable : l'avis `account.kyc_required` part à 80 % du seuil (`reason="amount_80"`), 7 jours avant l'échéance (`"deadline_7d"`), puis au premier refus (`"blocked"`), avec `event.kyc_required.collected_xof`, `threshold_xof`, `deadline`, `blocked`, `console_url`.

## La règle de relance

**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)`).
Expand Down
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).

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

- [AGENTS.md](AGENTS.md) : règles pour un agent de code
Expand Down
7 changes: 4 additions & 3 deletions src/technas_pay/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
from .errors import ErrorDetails, TechnasPayError, WebhookVerificationError
from .models import (
CURRENCY_BY_COUNTRY,
AccountKyc,
Balance,
CardAccount,
CardOnboardingLink,
Expand All @@ -31,16 +32,16 @@
retry_reference,
to_app_json,
)
from .webhooks import SIGNATURE_HEADER, Event, WebhookHandlers, sign, verify_signature
from .webhooks import SIGNATURE_HEADER, Event, KycRequired, WebhookHandlers, sign, verify_signature

__all__ = [
"__version__",
"AppOrder", "AppRequest", "AppResponse", "AppRoutes",
"AsyncTechnasPay", "TechnasPay", "TestWebhook", "WebhookResult",
"ErrorDetails", "TechnasPayError", "WebhookVerificationError",
"CURRENCY_BY_COUNTRY", "Balance", "CardAccount", "CardOnboardingLink", "CountryRules", "FxCountry", "FxMode", "Payment", "PaymentFx",
"CURRENCY_BY_COUNTRY", "AccountKyc", "Balance", "CardAccount", "CardOnboardingLink", "CountryRules", "FxCountry", "FxMode", "Payment", "PaymentFx",
"PayoutDestination", "PayoutDestinationState", "PayoutDestinationView", "PayoutNetwork", "Refund",
"Settlement", "TopUp", "TransactionPage",
"can_retry", "currency_for_country", "is_final", "retry_reference", "to_app_json",
"SIGNATURE_HEADER", "Event", "WebhookHandlers", "sign", "verify_signature",
"SIGNATURE_HEADER", "Event", "KycRequired", "WebhookHandlers", "sign", "verify_signature",
]
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.4.2"
__version__ = "0.5.0"
13 changes: 13 additions & 0 deletions src/technas_pay/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
from ._version import __version__
from .errors import TechnasPayError, error_from_response
from .models import (
AccountKyc,
Balance,
CardAccount,
CardOnboardingLink,
Expand Down Expand Up @@ -349,6 +350,10 @@ def _start_card_onboarding(
def _get_card_account() -> _Call[CardAccount]:
return _Call("GET", "/v1/card/account", None, CardAccount.from_api)

@staticmethod
def _get_account_kyc() -> _Call[AccountKyc]:
return _Call("GET", "/v1/account/kyc", None, AccountKyc.from_api)

@staticmethod
def _get_card_dashboard_link() -> _Call[str]:
return _Call("POST", "/v1/card/dashboard-link", {}, lambda raw: raw["url"])
Expand Down Expand Up @@ -523,6 +528,11 @@ def get_card_dashboard_link(self) -> str:
def get_balance(self) -> List[Balance]:
return self._run(self._get_balance())

def get_account_kyc(self) -> AccountKyc:
"""Le seuil d'identité de votre compte, à montrer au marchand (``stage``, ``collected_xof``,
``threshold_xof``, ``deadline``, ``console_url``). Les chiffres viennent d'ici : jamais en dur."""
return self._run(self._get_account_kyc())

def get_settlements(self) -> List[Settlement]:
return self._run(self._get_settlements())

Expand Down Expand Up @@ -646,6 +656,9 @@ async def get_card_dashboard_link(self) -> str:
async def get_balance(self) -> List[Balance]:
return await self._run(self._get_balance())

async def get_account_kyc(self) -> AccountKyc:
return await self._run(self._get_account_kyc())

async def get_settlements(self) -> List[Settlement]:
return await self._run(self._get_settlements())

Expand Down
16 changes: 15 additions & 1 deletion src/technas_pay/errors.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,10 @@ class ErrorDetails:
avec ``top_up_balance``, puis rappelez ``refund``) ;
- ``refund_exceeds_payment`` : ``refundable_amount`` ;
- ``country_not_available`` : ``reason`` (``no_payout_number``…) ;
- ``risk_not_accepted`` : ``risk``, le texte à montrer à l'utilisateur.
- ``risk_not_accepted`` : ``risk``, le texte à montrer à l'utilisateur ;
- ``kyc_required`` : ``console_url`` (où le responsable dépose sa pièce d'identité) et
``reason`` (``amount`` ou ``duration``) ;
- ``contract_required`` : ``version`` (le contrat à accepter dans la console) et ``console_url``.
"""

missing_amount: Optional[float] = None
Expand All @@ -24,6 +27,10 @@ class ErrorDetails:
risk: Optional[str] = None
#: ``card_account_not_ready`` : où en est votre compte carte (``not_started``, ``onboarding``…).
account_status: Optional[str] = None
#: ``kyc_required``, ``contract_required`` : la page de la console où agir.
console_url: Optional[str] = None
#: ``contract_required`` : la version du contrat à accepter dans la console.
version: Optional[str] = None


class TechnasPayError(Exception):
Expand All @@ -33,6 +40,11 @@ class TechnasPayError(Exception):
``risk_not_accepted``, ``fx_mode_unavailable``…). ``retryable`` dit si refaire LE MÊME appel,
avec la même référence, a du sens.

``kyc_required`` (409) : seuil d'identité dépassé, les NOUVEAUX paiements mobile money sont
refusés. Ne réessayez pas : proposez la carte, ou dites au client que le mobile money n'est pas
disponible pour le moment ; le responsable dépose sa pièce sur ``details.console_url``.
``contract_required`` (409) : le responsable accepte le contrat ``details.version`` dans la console.

``payment_expired`` : la référence est celle d'un essai expiré. Ne réessayez pas le même appel :
créez un nouveau paiement avec une NOUVELLE référence (``retry_reference``).
"""
Expand Down Expand Up @@ -82,6 +94,8 @@ def error_from_response(status: int, data: Any) -> TechnasPayError:
reason=data.get("reason"),
risk=data.get("risk"),
account_status=data.get("account_status"),
console_url=data.get("console_url"),
version=data.get("version"),
),
)

Expand Down
44 changes: 44 additions & 0 deletions src/technas_pay/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -413,6 +413,50 @@ def from_api(cls, raw: Any) -> "CardAccount":
)


@dataclass(frozen=True)
class AccountKyc:
"""Le seuil d'identité de votre compte (``get_account_kyc``), à montrer au marchand, pas au client.

En réel, un compte sans pièce d'identité vérifiée voit ses NOUVEAUX paiements mobile money
refusés (``kyc_required``) au-delà de ``threshold_xof`` F CFA encaissés en cumul, ou
``grace_days`` jours après son premier paiement réel encaissé. Lisez ces chiffres ici, ne les
écrivez jamais en dur. Le responsable dépose sa pièce sur ``console_url``.

``stage`` : ``ok``, ``soon`` (seuil proche), ``blocked``, ``verified``, ``not_applicable``.
``level`` : ``none``, ``identity``, ``business``. ``reason`` (si bloqué) : ``amount`` ou
``duration``. Une valeur que cette version ne connaît pas est gardée telle quelle.
"""

applies: bool
stage: str
level: str
days_elapsed: Optional[int]
warn_from_xof: int
warn_from_date: Optional[str]
collected_xof: int
threshold_xof: int
grace_days: int
first_collected_at: Optional[str]
deadline: Optional[str]
waiver_until: Optional[str]
blocked: bool
reason: Optional[str]
console_url: Optional[str]

@classmethod
def from_api(cls, raw: Any) -> "AccountKyc":
raw = raw or {}
return cls(
applies=bool(raw.get("applies")), stage=raw.get("stage"), level=raw.get("level"),
days_elapsed=raw.get("days_elapsed"), warn_from_xof=raw.get("warn_from_xof"),
warn_from_date=raw.get("warn_from_date"), collected_xof=raw.get("collected_xof"),
threshold_xof=raw.get("threshold_xof"), grace_days=raw.get("grace_days"),
first_collected_at=raw.get("first_collected_at"), deadline=raw.get("deadline"),
waiver_until=raw.get("waiver_until"), blocked=bool(raw.get("blocked")),
reason=raw.get("reason"), console_url=raw.get("console_url"),
)


@dataclass(frozen=True)
class CardOnboardingLink:
#: À ouvrir par le RESPONSABLE du compte (pas le développeur). Expire vite : à générer au clic.
Expand Down
Loading
Loading