From 84b1fe87abf1c22175f81ec9d285e9cfff2e2359 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 20:16:34 +0100 Subject: [PATCH] =?UTF-8?q?feat(kyc)=20:=20seuil=20d'identit=C3=A9=20du=20?= =?UTF-8?q?compte=20(get=5Faccount=5Fkyc,=20on=5Fkyc=5Frequired,=20kyc=5Fr?= =?UTF-8?q?equired)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - get_account_kyc() : GET /v1/account/kyc, rend un AccountKyc typé (valeurs inconnues gardées). - Avis account.kyc_required : fonction on_kyc_required, contenu typé event.kyc_required. - Erreurs 409 kyc_required et contract_required : details.console_url et details.version. - README, AGENTS.md, llms.txt : règle du seuil d'identité ; version 0.5.0. --- AGENTS.md | 15 ++++++-- CHANGELOG.md | 4 +++ README.md | 19 ++++++++-- llms.txt | 2 ++ src/technas_pay/__init__.py | 7 ++-- src/technas_pay/_version.py | 2 +- src/technas_pay/client.py | 13 +++++++ src/technas_pay/errors.py | 16 ++++++++- src/technas_pay/models.py | 44 +++++++++++++++++++++++ src/technas_pay/webhooks.py | 30 ++++++++++++++++ tests/test_client.py | 70 +++++++++++++++++++++++++++++++++++++ tests/test_webhooks.py | 20 ++++++++++- 12 files changed, 232 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fabee58..98424c6 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.4.2" +pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.5.0" ``` @@ -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)` | @@ -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. @@ -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 | |---|---| @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 6398d38..3c9fea2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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). diff --git a/README.md b/README.md index 09c5d7f..180f4dc 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.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. @@ -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 @@ -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 | @@ -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)`). diff --git a/llms.txt b/llms.txt index 416d852..20d327a 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). +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 diff --git a/src/technas_pay/__init__.py b/src/technas_pay/__init__.py index a5375cc..7578be0 100644 --- a/src/technas_pay/__init__.py +++ b/src/technas_pay/__init__.py @@ -9,6 +9,7 @@ from .errors import ErrorDetails, TechnasPayError, WebhookVerificationError from .models import ( CURRENCY_BY_COUNTRY, + AccountKyc, Balance, CardAccount, CardOnboardingLink, @@ -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", ] diff --git a/src/technas_pay/_version.py b/src/technas_pay/_version.py index df12433..3d18726 100644 --- a/src/technas_pay/_version.py +++ b/src/technas_pay/_version.py @@ -1 +1 @@ -__version__ = "0.4.2" +__version__ = "0.5.0" diff --git a/src/technas_pay/client.py b/src/technas_pay/client.py index 1a8657a..09a8c86 100644 --- a/src/technas_pay/client.py +++ b/src/technas_pay/client.py @@ -24,6 +24,7 @@ from ._version import __version__ from .errors import TechnasPayError, error_from_response from .models import ( + AccountKyc, Balance, CardAccount, CardOnboardingLink, @@ -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"]) @@ -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()) @@ -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()) diff --git a/src/technas_pay/errors.py b/src/technas_pay/errors.py index ca6f208..f4e5ba9 100644 --- a/src/technas_pay/errors.py +++ b/src/technas_pay/errors.py @@ -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 @@ -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): @@ -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``). """ @@ -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"), ), ) diff --git a/src/technas_pay/models.py b/src/technas_pay/models.py index 6e252c8..681bd6b 100644 --- a/src/technas_pay/models.py +++ b/src/technas_pay/models.py @@ -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. diff --git a/src/technas_pay/webhooks.py b/src/technas_pay/webhooks.py index 95f138d..3d514df 100644 --- a/src/technas_pay/webhooks.py +++ b/src/technas_pay/webhooks.py @@ -72,6 +72,23 @@ class FxModeChange: home_currency: Optional[str] +@dataclass(frozen=True) +class KycRequired: + """``account.kyc_required`` : le seuil d'identité approche ou est atteint. + + ``reason`` : ``amount_80`` (80 % du seuil encaissés), ``deadline_7d`` (échéance dans 7 jours), + ``blocked`` (premier refus). Une valeur que cette version ne connaît pas est gardée telle quelle. + Prévenez le RESPONSABLE : il dépose sa pièce d'identité sur ``console_url``. + """ + + reason: Optional[str] + collected_xof: Any + threshold_xof: Any + deadline: Optional[str] + blocked: bool + console_url: Optional[str] + + @dataclass(frozen=True) class Event: """Un événement vérifié. Un seul des champs de contenu est rempli selon ``type``. @@ -90,6 +107,8 @@ class Event: fx: Optional[FxModeChange] = None #: ``card_account.updated`` : le nouvel état de votre compte carte. card_account: Optional[CardAccount] = None + #: ``account.kyc_required`` : où en est le seuil d'identité. + kyc_required: Optional[KycRequired] = None #: Données brutes (toujours présentes), utiles pour un type que cette version ne connaît pas. data: Optional[Dict[str, Any]] = None @@ -117,6 +136,11 @@ def parse_event(raw: Any) -> Event: )) if t == "card_account.updated": return Event(**base, card_account=CardAccount.from_api(d)) + if t == "account.kyc_required": + return Event(**base, kyc_required=KycRequired( + reason=d.get("reason"), collected_xof=d.get("collected_xof"), threshold_xof=d.get("threshold_xof"), + deadline=d.get("deadline"), blocked=bool(d.get("blocked")), console_url=d.get("console_url"), + )) if t == "balance.topped_up": return Event(**base, top_up=TopUpInfo( id=d.get("id"), amount=d.get("amount"), currency=d.get("currency"), completed_at=d.get("completed_at"), @@ -180,6 +204,8 @@ class WebhookHandlers: - ``on_expired`` : définitif ; seul moment où relancer, avec une NOUVELLE référence. - ``on_refund`` : ``refund.completed`` / ``refund.failed`` / ``refund.recorded`` ; prévenez le client. - ``on_fx_mode_updated`` : si ce n'est pas vous, prévenez Technas (clé compromise ?). + - ``on_kyc_required`` : prévenez le RESPONSABLE (pas le client) de déposer sa pièce + (``event.kyc_required.console_url``). Une exception doit REMONTER : la réponse n'est pas 2xx et Technas relivre l'événement. """ @@ -194,6 +220,8 @@ class WebhookHandlers: on_fx_mode_updated: Optional[Handler] = None #: Votre compte carte a changé d'état (ouvert, à compléter, suspendu…). on_card_account_updated: Optional[Handler] = None + #: ``account.kyc_required`` : seuil d'identité à 80 %, échéance dans 7 jours, ou premier refus. + on_kyc_required: Optional[Handler] = None def handler_for(event: Event, handlers: WebhookHandlers) -> Optional[Handler]: @@ -216,6 +244,8 @@ def handler_for(event: Event, handlers: WebhookHandlers) -> Optional[Handler]: return handlers.on_fx_mode_updated if t == "card_account.updated": return handlers.on_card_account_updated + if t == "account.kyc_required": + return handlers.on_kyc_required # Type inconnu : acquitté sans rien appeler (sinon relivré pendant trois jours). return None diff --git a/tests/test_client.py b/tests/test_client.py index bb6b85e..6adbc35 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -5,6 +5,7 @@ import pytest from technas_pay import ( + AccountKyc, AsyncTechnasPay, PayoutDestination, TechnasPay, @@ -264,3 +265,72 @@ def handler(request): def test_refund_kind_stripe_received_is_read_as_card(received, expected): from technas_pay.models import Refund assert Refund.from_api({"id": "r1", "kind": received}).kind == expected + + +KYC_FULL = { + "applies": True, "stage": "soon", "level": "none", "days_elapsed": 23, "warn_from_xof": 800000, + "warn_from_date": "2026-11-20T00:00:00Z", "collected_xof": 812500, "threshold_xof": 1000000, "grace_days": 30, + "first_collected_at": "2026-10-23T09:00:00Z", "deadline": "2026-11-22T09:00:00Z", "waiver_until": "2026-12-01T00:00:00Z", + "blocked": False, "reason": None, "console_url": "https://console.technas.test/identite", +} +KYC_NULLS = { + "applies": False, "stage": "not_applicable", "level": "none", "days_elapsed": None, "warn_from_xof": 800000, + "warn_from_date": None, "collected_xof": 0, "threshold_xof": 1000000, "grace_days": 30, "first_collected_at": None, + "deadline": None, "waiver_until": None, "blocked": False, "reason": None, "console_url": "https://console.technas.test/identite", +} + + +def _kyc_client(body, seen): + def handler(request): + seen.append(request) + return httpx.Response(200, json=body) + + return TechnasPay(SECRET, base_url=BASE, http_client=httpx.Client(transport=httpx.MockTransport(handler))) + + +def test_get_account_kyc_route_en_tete_et_tous_les_champs(): + seen = [] + kyc = _kyc_client(KYC_FULL, seen).get_account_kyc() + assert isinstance(kyc, AccountKyc) + assert seen[0].method == "GET" and seen[0].url.path == "/v1/account/kyc" + assert seen[0].headers["authorization"] == f"Bearer {API_KEY}" and not seen[0].content + assert kyc == AccountKyc(**KYC_FULL) + + +def test_get_account_kyc_champs_nuls(): + kyc = _kyc_client(KYC_NULLS, []).get_account_kyc() + assert kyc == AccountKyc(**KYC_NULLS) + assert kyc.days_elapsed is None and kyc.deadline is None and kyc.first_collected_at is None + + +def test_get_account_kyc_valeurs_inconnues_gardees(): + body = dict(KYC_FULL, stage="paused", level="enhanced", reason="volume", blocked=True) + kyc = _kyc_client(body, []).get_account_kyc() + assert (kyc.stage, kyc.level, kyc.reason, kyc.blocked) == ("paused", "enhanced", "volume", True) + + +async def test_get_account_kyc_async(): + async def handler(request): + assert request.url.path == "/v1/account/kyc" and request.headers["authorization"] == f"Bearer {API_KEY}" + return httpx.Response(200, json=KYC_FULL) + + async with AsyncTechnasPay(SECRET, base_url=BASE, http_client=httpx.AsyncClient(transport=httpx.MockTransport(handler))) as pay: + assert (await pay.get_account_kyc()).threshold_xof == 1000000 + + +def test_erreur_kyc_required_et_contract_required(): + replies = [ + httpx.Response(409, json={"code": "kyc_required", "message": "m", "reason": "amount", + "console_url": "https://console.technas.test/identite"}), + httpx.Response(409, json={"code": "contract_required", "message": "m", "version": "2026-11", + "console_url": "https://console.technas.test/contrat"}), + ] + pay = TechnasPay(SECRET, base_url=BASE, http_client=httpx.Client(transport=httpx.MockTransport(lambda r: replies.pop(0)))) + with pytest.raises(TechnasPayError) as e: + ask(pay) + assert e.value.code == "kyc_required" and e.value.status == 409 and not e.value.retryable + assert e.value.details.console_url == "https://console.technas.test/identite" and e.value.details.reason == "amount" + with pytest.raises(TechnasPayError) as e: + ask(pay) + assert e.value.code == "contract_required" and not e.value.retryable + assert e.value.details.version == "2026-11" and e.value.details.console_url == "https://console.technas.test/contrat" diff --git a/tests/test_webhooks.py b/tests/test_webhooks.py index 957b706..967a64a 100644 --- a/tests/test_webhooks.py +++ b/tests/test_webhooks.py @@ -3,7 +3,7 @@ import pytest -from technas_pay import AsyncTechnasPay, TechnasPay, TechnasPayError, WebhookHandlers, WebhookVerificationError, sign +from technas_pay import AsyncTechnasPay, KycRequired, TechnasPay, TechnasPayError, WebhookHandlers, WebhookVerificationError, sign from .fake_gateway import SECRET, WEBHOOK_SECRET @@ -71,6 +71,9 @@ def test_type_inconnu_acquitte(): lambda e: e.fx.previous_mode == "none"), ("card_account.updated", {"status": "enabled", "can_accept_payments": True}, "on_card_account_updated", lambda e: e.card_account.can_accept_payments), + ("account.kyc_required", {"reason": "deadline_7d", "collected_xof": 400000, "threshold_xof": 1000000, + "deadline": "2026-11-22T09:00:00Z", "blocked": False, "console_url": "https://c"}, "on_kyc_required", + lambda e: e.kyc_required.reason == "deadline_7d" and e.kyc_required.console_url == "https://c"), ("payment.expired", {"id": "p", "reference": "r-1", "status": "expired", "amount": 1, "currency": "XOF"}, "on_expired", lambda e: e.payment.status == "expired"), ("payment.failed", {"id": "p", "reference": "r-1", "status": "failed", "amount": 1, "currency": "XOF"}, "on_failed", @@ -120,3 +123,18 @@ async def on_completed(event): await pay.handle_webhook(EVENT, sign(EVENT, WEBHOOK_SECRET), WebhookHandlers(on_completed=lambda e: seen.append("sync"))) assert seen == ["evt_1", "sync"] await pay.aclose() + + +def test_avis_kyc_required_signe_contenu_type(): + data = {"reason": "amount_80", "collected_xof": 800000, "threshold_xof": 1000000, + "deadline": "2026-11-22T09:00:00Z", "blocked": False, "console_url": "https://console.technas.test/identite"} + body = json.dumps({"id": "evt_kyc", "type": "account.kyc_required", "created_at": "2026-11-15T10:00:00Z", "data": data}) + seen, other = [], [] + TechnasPay(SECRET).handle_webhook(body, sign(body, WEBHOOK_SECRET), WebhookHandlers(on_kyc_required=seen.append, + on_completed=other.append)) + assert not other and len(seen) == 1 + assert seen[0].kyc_required == KycRequired(**data) and seen[0].payment is None + blocked = json.dumps({"id": "e2", "type": "account.kyc_required", "created_at": "x", + "data": dict(data, reason="blocked", blocked=True, deadline=None)}) + ev = TechnasPay(SECRET).verify_webhook(blocked, sign(blocked, WEBHOOK_SECRET)) + assert ev.kyc_required.blocked and ev.kyc_required.reason == "blocked" and ev.kyc_required.deadline is None