Aller au contenu

Lemonway — Carte

Endpoints liés aux paiements par carte bancaire via Lemonway : création d'une intention de paiement, redirection après paiement et webhook de confirmation. Source : card.controller.ts.

Tous les endpoints sont sous le préfixe /customers/lemonway. L'endpoint de paiement (POST /payment-intent/card) requiert un JWT investisseur valide (JwtAuthGuard) et le rôle CUSTOMER (UserRoleGuard). Les endpoints de webhook (GET|POST /webhook-card/:walletTransactionId) sont publics (pas de guard) — le walletTransactionId (UUID v4) sert d'identifiant non devinable et la vérité finale est récupérée auprès de Lemonway côté serveur.

Surfaces client (oct. 2026)

App Carte one-shot (POST /payment-intent/card) Carte enregistrée (GET /card/saved, POST /payment-intent/saved-card)
front-app (web investisseur) Oui — funnel wallet / achat / carte cadeau (hosted Lemonway ou Checkout selon flags) Non — flux UI supprimé ; l'API reste disponible si ENABLE_MONEY_IN_SAVED_CARDS
front-mobile-app Oui — top-up / achats via Checkout ou Lemonway selon parcours Non — aucun appel client vers saved-card
Réservation primary-purchase Webhook + bricks-reservation inchangés côté API Variante API toujours documentée ci-dessous ; plus exposée sur le web legacy wallet

Ne pas supprimer les endpoints saved-card tant que Lemonway ou un client externe pourrait encore les appeler ; toute évolution produit passe par carte saisie à la volée ou Checkout.

POST /payment-intent/card

Initie un paiement par carte (carte non enregistrée) et retourne l'URL Lemonway sur laquelle rediriger l'investisseur pour saisir sa carte. Source : card.controller.ts#L64.

Pré-conditions

  • Onboarding investisseur complété (Customer.assertCompletedInvestorOnboarding)
  • Droits transactionnels : 'all' ou 'cashin_fundraise' (Customer.assertTransactionRights)
  • Si type: 'gift-card' : MFA pré-validé (MFAPreAuthFlowService.requireMfaToken avec action gift-card-purchase)
  • Si type: 'gift-card' : amountToMoneyIn + lemonwayBalance >= giftCard.amount

Request body

Validé via payWithCardRequestBody (depuis @bricks-common/api-communication). Discriminé sur type :

  • type: 'classic' — top-up de wallet simple
  • type: 'gift-card' — top-up + achat d'une carte cadeau (requiert mfaVerificationToken + giftCard)
  • type: 'bricks-reservation' — paiement d'une réservation d'achat primaire (requiert bricksReservationId)

Response

{
  "url": "https://webkit.lemonway.fr/..."
}

URL Lemonway vers laquelle rediriger l'investisseur (page de saisie carte hébergée par Lemonway).

Effets de bord

  • Si type === 'bricks-reservation' : appelle primaryPurchaseService.setCardInForBricksReservation pour rattacher la walletTransaction carte créée à la réservation.

Erreurs

Code Statut Cause
payment-intent.gif-card-amount-too-high 400 Carte cadeau : montant > amountToMoneyIn + lemonwayBalance
amount-too-low 400 Montant inférieur au minimum Lemonway
amount-too-high 400 Montant supérieur au plafond carte (businessRules.moneyIn.card.maxAmountInCents)
customer.rights.account-is-being-verified 400 Compte Lemonway restreint (en vérification)
primary-purchase-wrong-status 400 Réservation pas dans le bon statut pour rattacher une carte
primary-purchase-no-reservation 400 Purchase sans réservation
primary-purchase-not-found 400 Réservation introuvable
MFA errors (variants) 400 Cas carte cadeau, jeton MFA invalide / manquant

GET /webhook-card/:walletTransactionId

Page de retour Lemonway après saisie carte. Public (pas de guard) — Lemonway redirige le navigateur de l'investisseur ici en GET avec des query params. Lit le statut réel de la transaction côté Lemonway puis renvoie un 302 vers le front. Source : card.controller.ts#L311.

Path param

  • walletTransactionId — UUID v4 (validé par ParseUUIDPipe)

Query params

LemonwayCardPaymentIntentDto :

  • response_wkToken — token Lemonway (optionnel)
  • response_transactionId — id transaction Lemonway (optionnel)
  • redirectPath — chemin front cible (défaut /wallet)

Response

302 vers <frontUrl><redirectPath>?card_payment_state=<ok|fail|cancel>&amount=<totalValue> selon le statut Lemonway (success → ok, cancelled → cancel, sinon fail).

Erreurs

Code Statut Cause
InvalidRequest 400 Aucun token Lemonway ni walletTransactionId exploitable
TransactionNotFound 404 WalletTransaction introuvable en base
BadRequestException (vide) 400 walletTransaction.lemonwayTransactionId manquant
Transaction not found at Lemonway 404 Transaction absente côté Lemonway
InternalServerError 500 Erreur Lemonway autre que not-found

POST /webhook-card/:walletTransactionId

Webhook serveur-à-serveur appelé par Lemonway pour notifier le résultat du paiement carte. Public (pas de guard) — la sécurité repose sur le walletTransactionId UUID non devinable et sur la consultation directe de l'API Lemonway pour le statut réel. Source : card.controller.ts#L376.

Path param

  • walletTransactionId — UUID v4 (validé par ParseUUIDPipe)

Effets

Dans une transaction Postgres avec lock pessimiste : 1. Verrouille la WalletTransaction cible (statut requis : WAITING). 2. Lock le customer (CustomerBalanceService.lockCustomer). 3. Récupère le statut réel de la transaction Lemonway (lemonwayApi.getMoneyIn). 4. Met à jour walletTransaction.status : - Lemonway success → CONFIRMED - Lemonway cancelled ou autre → DECLINED 5. Si contexte topup_card : enrichit le contexte avec les infos de la carte (mapCardFromLwMoneyIn). 6. Sauvegarde via CustomerBalanceService.saveWalletTransactions.

Hors transaction : déclenche cardTopupService.cardStatusConfirmedOrDeclined (logique métier post-paiement, ex. validation réservation primary-purchase).

Erreurs

Code Statut Cause
money-in.card.hook.WALLET_TRANSACTION_NOT_FOUND 404 WT inconnue (cas log + ignore)
BadRequestException (vide) 400 lemonwayTransactionId manquant
money-in.card.hook.WALLET_TRANSACTION_NOT_WAITING 400 WT déjà finalisée — webhook ignoré
Transaction not found at Lemonway 404 Lemonway ne retrouve pas la transaction
InternalServerError 500 Autre erreur Lemonway

Liens