Aller au contenu

Lemonway — Retraits

Endpoints liés aux retraits (money-out) investisseur : initiation d'un retrait vers un IBAN enregistré et lecture du quota annuel sans frais. Source : withdraw.controller.ts.

Tous les endpoints sont sous le préfixe /customers/lemonway. Ils requièrent un JWT investisseur (JwtAuthGuard) et le rôle CUSTOMER (UserRoleGuard). L'initiation de retrait (POST /payment-intent/withdrawal) requiert en plus un code 2FA via le guard CheckCustomer2FACode (header tfa) et passe par TFAInterceptor qui invalide le code Redis après usage.

POST /payment-intent/withdrawal

Initie un retrait depuis le wallet investisseur vers un IBAN enregistré. Le retrait est créé en statut WAITING côté Bricks puis traité par le pipeline backend (anti-fraude, frais, lien chez Lemonway). Source : withdraw.controller.ts#L31.

Pré-conditions

  • JWT valide + rôle CUSTOMER
  • Code 2FA valide en header tfa (validé contre Redis clé 2FA_<code>_<customerId>)
  • Droits transactionnels : 'all' (Customer.assertTransactionRights)
  • IBAN_WITHDRAW payment method existant + actif chez Lemonway (Activated)
  • Anti-fraude : WithdrawFraudService.buildAndCheckWithdrawRequest ne doit pas bloquer la requête
  • Balance investisseur cohérente (interne vs Lemonway, intégrité giftBalance vs withdrawableBalance)

Headers

  • tfa — code 2FA précédemment généré et stocké en Redis. Le TFAInterceptor l'invalide après succès.

Request body

Validé via withdrawPayload (depuis investor-withdraw.service.ts) :

{
  "paymentMethodId": "uuid-iban-withdraw",
  "amount": 50000
}
  • paymentMethodId — UUID du PaymentMethod IBAN_WITHDRAW activé chez Lemonway
  • amount — entier positif en cents

Le customerId est ajouté côté serveur depuis @IAM() avant validation.

Effets

Délègue à InvestorWithdrawService.withdraw(payload, 'investor') qui :

  1. Vérifie le payment method (existence, kind IBAN_WITHDRAW, statut Lemonway Activated, lemonwayIbanId présent).
  2. Vérifie l'intégrité de balance vs Lemonway (en cas d'incohérence interne → freeze auto du customer).
  3. Lance WithdrawFraudService.buildAndCheckWithdrawRequest (peut bloquer).
  4. Crée la WalletTransaction WITHDRAWAL en WAITING.
  5. Envoie l'évènement Customer.io de retrait initié (juste après la WT WITHDRAWAL, avant les frais et la persistance du WithdrawRequest).
  6. Si quota annuel sans frais épuisé : crée également une WT WITHDRAWAL_FEE (frais TTC) + Invoice associée.
  7. Persiste le WithdrawRequest.

Response

Pas de body explicite côté controller (la fonction retourne void ou rien d'utile en cas de succès — le client se base sur 200/201).

Erreurs

Code Statut Cause
2fa-code.invalid 403 Code 2FA absent ou invalide (guard)
Validation errors (idtt) 400 Payload invalide (paymentMethodId, amount)
withdrawal.payment-method.not-found 404 IBAN withdraw introuvable / pas activé Lemonway
withdrawal.withdrawal-payment-method.missing-lemonwayIbanId 400 IBAN sans lemonwayIbanId (intégrité)
customer-balance.not-enough-balance 400 Balance insuffisante
customer.fetch-balance-at-lemonway-failed 500 Échec fetch balance Lemonway
withdrawal.blocked-by-fraud-rule 403 Bloqué par anti-fraude (règle déclenchée)
InternalServerError 500 Cas freeze customer (mismatch balance interne)
Erreurs Customer.assertTransactionRights 4xx Droits transactionnels insuffisants

GET /withdraw/remaining-without-fee

Retourne le quota annuel restant de retraits sans frais pour l'investisseur (basé sur le nombre de retraits gratuits effectués sur les 12 derniers mois). Source : withdraw.controller.ts#L49.

Pré-conditions

  • JWT valide + rôle CUSTOMER

Response

{
  "freeWithdrawalsInPastYear": 2,
  "withdrawRemainingWithoutFeeCount": 1,
  "shouldApplyFee": false
}
  • freeWithdrawalsInPastYear — retraits sans frais déjà consommés (statut confirmed ou waiting) sur l'année glissante
  • withdrawRemainingWithoutFeeCount — max(businessRules.withdraw.yearlyWithoutFeeMax - freeWithdrawalsInPastYear, 0)
  • shouldApplyFee — true si quota épuisé (le prochain retrait facturera des frais)

Erreurs

Aucune spécifique au-delà des erreurs d'auth standard.

Liens