Paiements & Cartes
Integrez les paiements multi-methodes (CB, SEPA, QR Code) avec loyalty cashback automatique, cartes virtuelles/physiques, et suivi en temps reel via l'API YaniPay. YaniPay opere trois rails de paiement : Humain-to-Humain (B2C, B2B), Humain-to-Agent (delegation IA) et Agent-to-Agent (transactions automatiques entre agents IA, regles en YANICoin).
Vue d'ensemble
Le module de paiements YaniPay offre une integration dual-provider : Swan BaaS (IBAN, SEPA, cartes) et Stripe (CB/Visa/MC). Chaque paiement EUR declenche automatiquement un cashback loyaltyvia le programme du marchand. L'architecture repose sur 3 methodes de paiement (Wallet, CB, SEPA) et 16+ routes API avec webhooks temps reel.
Stripe Connect
Paiements, abonnements et marketplace via l'API Stripe avec gestion complete du cycle de vie.
Securite PCI DSS
Tokenisation des cartes, 3D Secure, HMAC-SHA256 pour les webhooks. Aucune donnee sensible stockee cote serveur.
Suivi temps reel
Historique des transactions, notifications webhook, dashboard analytique pour les marchands.
Integration Stripe
STRIPE_SECRET_KEY et STRIPE_WEBHOOK_SECRET).Flux de paiement
Le flux de paiement YaniPay suit un pattern asynchrone avec confirmation via webhooks. Voici le parcours complet d'une transaction :
Flux SEPA (Swan BaaS) avec Loyalty
Pour les paiements EUR via Swan BaaS, le flux integre l'attribution automatique de loyalty et le masquage IBAN dans les reponses (commit f220a81b T-21) :
Masquage IBAN dans les réponses
f220a81b (T-21), les IBAN sont masques dans toutes les reponses API de paiement et les logs. Seuls les 4 derniers chiffres sont visibles (ex. : FR76 **** **** **** 1234). Les IBAN complets ne sont jamais exposes cote client.Initiation
L'utilisateur declenche un paiement via le formulaire ou l'API.
Processing
L'API YaniPay cree une session Stripe Checkout ou un PaymentIntent.
Confirmation
Stripe traite le paiement et envoie un evenement webhook.
Persistence
Le webhook handler valide la signature HMAC et met a jour la base de donnees.
Notification
L'utilisateur recoit une confirmation par email et dans l'application.
Methodes de paiement NEW
Lors du paiement via QR code ou lien (/pay/[ref]), l'utilisateur peut choisir sa methode de paiement via le composant PaymentMethodSelector :
Solde YaniPay (WALLET)
Transfert P2P instantane depuis le portefeuille EUR. Defaut pour les paiements QR.
Carte bancaire (CARD)
CB/Visa/Mastercard via Stripe Elements. 3D Secure integre.
Virement SEPA
Virement bancaire via Swan BaaS. Instantane ou classique.
1 import { PaymentMethodSelector } from '@/components/payments/PaymentMethodSelector'; 2 import type { PaymentMethodType } from '@platform/api/contracts/payments'; 3 4 const [method, setMethod] = useState<PaymentMethodType>('WALLET'); 5 6 <PaymentMethodSelector 7 selected={method} 8 onChange={setMethod} 9 disabledMethods={['SEPA']} // SEPA bientot disponible 10 />
Loyalty & Cashback NEW
Chaque paiement en EUR declenche automatiquement l'attribution de points et de cashback si le marchand a un programme de fidelite actif. La logique est non-bloquante: un echec de l'attribution loyalty n'echoue jamais le paiement.
| Methode | Montant | Cashback (1%) | Points (10/EUR) |
|---|---|---|---|
| CB (Carte) | 10,00 EUR | +0,10 EUR | +100 pts |
| SEPA | 100,00 EUR | +1,00 EUR | +1 000 pts |
| QR Code | 150,00 EUR | +1,50 EUR | +1 500 pts |
| Total | 260,00 EUR | +2,60 EUR | +2 600 pts |
Auto-detect du programme loyalty
programIdn'est fourni dans le paiement, le systeme detecte automatiquement le programme PUBLISHED du marchand via son Store. Le client doit etre inscrit au programme (LoyaltyCard ACTIVE) pour recevoir les recompenses.1 // Appele automatiquement apres chaque paiement EUR 2 const loyaltyResult = await awardLoyaltyForPayment( 3 payerId, // Qui paye 4 payeeId, // Le marchand 5 amount, // Montant en EUR 6 'EUR', // Devise (seul EUR earn loyalty) 7 'QR_CODE', // Canal: QR_CODE | ONLINE | IN_APP | TAP_TO_PAY | SEPA_TRANSFER 8 transactionId, // Reference transaction 9 ); 10 11 // Resultat (ou null si pas de programme) 12 // { pointsEarned: 150, cashbackEarned: 1.50, 13 // pointsBalance: 2600, cashbackBalance: 2.60 }
Fonctionnalites
Stripe Payments
- Checkout Sessions
- PaymentIntents
- Subscriptions recurrentes
- Remboursements automatises
Gestion des cartes
- Cartes virtuelles instantanees
- Cartes physiques personnalisees
- Gel / Degel / Suppression
- Plafonds et limites
Historique transactions
- Liste paginee avec filtres
- Export CSV / PDF
- Recherche avancee
- Webhooks temps reel
QR Code & Payment Links NEW
YaniPay permet aux marchands de generer des demandes de paiement sous forme de QR codes ou de liens partageables. Les clients scannent le QR ou cliquent sur le lien pour acceder a une page de paiement pre-remplie.
QR Code Decode
Decodez les URIs yanipay://depuis un QR code scanne. L'API extrait le montant, la devise, le destinataire et la reference de paiement.
Payment Links
Creez des liens de paiement partageables par SMS, email ou reseaux sociaux. Chaque lien est associe a une reference unique accessible publiquement via /pay/[ref].
1 // POST /api/payments/request 2 const response = await fetch('/api/payments/request', { 3 method: 'POST', 4 headers: { 'Content-Type': 'application/json' }, 5 body: JSON.stringify({ 6 amount: 25.50, 7 currency: 'EUR', 8 description: 'Commande #1234', 9 }), 10 }); 11 12 const { ref, qrCodeUrl, paymentUrl } = await response.json(); 13 // ref: "pay_abc123xyz" 14 // qrCodeUrl: "data:image/png;base64,..." 15 // paymentUrl: "https://yanipay.com/pay/pay_abc123xyz"
URI yanipay://
yanipay://pay?amount=25.50¤cy=EUR&ref=pay_abc123xyz. L'endpoint POST /api/payments/qr parse automatiquement ce format et retourne les donnees structurees.PayWithYaniPayButton NEW
Le composant PayWithYaniPayButtonest un bouton embarquable avec effet shimmer qui permet d'integrer un paiement YaniPay en une seule ligne de code. Il cree automatiquement une demande de paiement et redirige vers la page de paiement.
Caracteristiques
- Effet shimmer anime sur le bouton
- Creation automatique de la demande de paiement
- Callback
onSuccessavec la reference de paiement - Variants :
default,outline,ghost - Tailles :
sm,md,lg
1 import { PayWithYaniPayButton } from '@/components/payments/PayWithYaniPayButton'; 2 3 // Bouton embarquable sur le site du marchand 4 <PayWithYaniPayButton 5 amount={25.50} 6 currency="EUR" 7 merchantId="merchant-uuid-123" // ID du marchand (optionnel) 8 description="Commande #1234" 9 onSuccess={({ ref }) => router.push(`/pay/${ref}`)} 10 variant="default" 11 size="lg" 12 redirect // Redirige vers /pay/[ref] apres creation 13 />
Spending Analytics
GET /api/payments/spending retourne les depenses par categorie (alimentation, transport, loisirs, etc.) avec des tendances mensuelles. Ideal pour construire des dashboards analytiques personnalises.API Routes
Voici un apercu de toutes les routes API disponibles pour le module de paiements :
| Methode | Endpoint | Description |
|---|---|---|
| POST | /api/payments | Creer un paiement |
| GET | /api/payments | Liste des paiements (dashboard) |
| GET | /api/v1/mobile/payments/history | Historique paiements (mobile)NEW |
| POST | /api/v1/mobile/payments/process | Traiter un paiement (mobile)NEW |
| GET | /api/v1/mobile/payments/requests | Demandes de paiement (mobile)NEW |
| POST | /api/v1/mobile/payments/send | Envoyer un paiement (mobile)NEW |
| GET | /api/v1/mobile/payments/scheduled | Paiements planifiés (mobile)NEW |
| GET | /api/payments/cards | Lister les cartes |
| POST | /api/payments/cards | Ajouter une carte |
| GET | /api/payments/transactions | Historique transactions |
| POST | /api/payments/stripe | Session Stripe Checkout |
| POST | /api/payments/validate | Valider un paiement |
| GET | /api/payments/merchant | Info marchand |
| POST | /api/payments/merchant | Config marchand |
| POST | /api/webhooks/stripe | Webhook Stripe |
| GET | /api/payments/merchant/stats | Statistiques marchand |
| POST | /api/payments/merchant/transactions | Transactions marchand |
| POST | /api/payments/qr | Decoder un QR code yanipay://NEW |
| POST | /api/payments/request | Creer une demande de paiementNEW |
| GET | /api/payments/request/[ref] | Consulter une demande (public)NEW |
| POST | /api/payments/request/[ref] | Executer une demande de paiementNEW |
| GET | /api/payments/spending | Analytique depenses par categorie (mois en cours)NEW |
| GET | /api/payments/spending/history | Historique depenses sur plusieurs moisNEW |
| GET | /api/payments/transactions/[id] | Detail d'une transaction par ID |
Documentation API complete
Quick Start
Pour commencer rapidement avec les paiements YaniPay, configurez vos variables d'environnement Stripe :
# Stripe Configuration (pour /api/payments/stripe et /api/billing/*)
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxx
STRIPE_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxx
# Paiement P2P interne (POST /api/payments) — pas de cle externe requise1 import { apiPost } from '@/lib/api/client'; 2 import type { PaymentRequest, PaymentResponse } from '@platform/api/contracts/payments'; 3 4 // Paiement P2P : wallet EUR ou YANI, routing CeFi/DeFi automatique 5 const result = await apiPost<PaymentResponse>('/api/payments', { 6 payeeId: 'user@example.com', // UUID, email, telephone ou accountId (10 chiffres) 7 amount: 25.50, 8 currency: 'EUR', // 'EUR' | 'YANI' 9 channel: 'QR_CODE', // 'TAP_TO_PAY' | 'ONLINE' | 'IN_APP' | 'QR_CODE' | 'SEPA_TRANSFER' 10 metadata: { 11 description: 'Commande #1234', 12 programId: 'prog_abc123', // optionnel — auto-detect si absent 13 }, 14 } satisfies PaymentRequest); 15 16 // Reponse 17 // result.payment.transactionId — ID de la transaction 18 // result.routing.channel — 'CEFI' | 'DEFI' 19 // result.routing.conversionApplied — true si conversion EUR↔YANI 20 // result.loyalty.pointsEarned — points attribues (null si pas de programme)
Roles requis et rate limiting
POST /api/payments requiert le role PARTICULIER, PROFESSIONNEL ou ADMIN. Rate limiting : apiRateLimit(100 requetes / 15 minutes par IP). Les paiements en EUR sont soumis aux limites du plan d'abonnement (checkSubscriptionLimit) — une erreur 402 LIMIT_EXCEEDED est retournee si le quota mensuel est atteint.Securite & Rate Limiting
Toutes les routes de paiement sont protegees par rate limiting HTTP et authentification via getCurrentUser() (routes sans withAuth) ou withAuth middleware.
| Route | Rate Limit | Auth |
|---|---|---|
| POST /api/payments | apiRateLimit — 100 req / 15 min | withAuth (PARTICULIER, PROFESSIONNEL, ADMIN) |
| POST /api/payments/transactions | strictRateLimit — 10 req / min | getServerSession |
| GET /api/payments/transactions | aucun (lecture) | getServerSession |
| POST /api/payments/stripe | apiRateLimit — 100 req / 15 min | getServerSession |
| POST /api/payments/request | apiRateLimit — 100 req / 15 min | getServerSession |
| POST /api/webhooks/stripe | apiRateLimit | HMAC-SHA256 (STRIPE_WEBHOOK_SECRET) |
Integration fidelite automatique
E-invoicing reform 2026
La réforme française de la facturation électronique impose la réception obligatoire des factures électroniques pour toutes les entreprises assujetties à la TVA à compter du 1ᵉʳ septembre 2026 (loi 2022-1157 art. 26 modifiée par 2023-1322 art. 91). YaniPay opère en OD compatible (Opérateur de Dématérialisation) via Pennylane PDP — pas de candidature PDP directe en Phase 1.
1ᵉʳ septembre 2026
Réception obligatoire pour toutes les entreprises · Émission obligatoire pour grandes entreprises (GE) et entreprises de taille intermédiaire (ETI) · E-reporting B2C
1ᵉʳ septembre 2027
Émission obligatoire étendue aux PME et TPE. Sanctions : 50 € par facture non conforme, plafond 15 000 €/an.
YaniPay : OD via Pennylane
Pennylane est Plateforme Agréée (PA) avec immatriculation définitive (DGFiP, déc. 2025). YaniPay génère la facture conforme et la transmet via la PDP partenaire.
Architecture conforme
| Composant | Standard | Implémentation YaniPay |
|---|---|---|
| Format facture | Factur-X v1.08 (CII / EN 16931) en PDF/A-3 + XML | Profil MINIMUM suffisant pour la réforme, EN16931 pour interop UE |
| TVA multi-taux | 5 taux français (0 / 2,1 / 5,5 / 10 / 20 %), 6 régimes | Validateurs Zod sur lib/invoices/vat-validator.ts (TASK-0709) |
| Signature | XAdES-EPES + horodatage RFC 3161 (eIDAS 910/2014) | Certificat qualifié DigiCert / ChamberSign (TASK-0710) |
| Archivage | NF Z42-013:2020 (= ISO 14641-1) — 10 ans valeur probante | S3 SecNumCloud object-lock + SHA-256 hash chain (TASK-0711) |
| E-reporting B2C | Fréquence selon régime TVA (quotidien à mensuel) | Cron agrégateur via Pennylane PDP (TASK-0712) |
| RGPD | AIPD CNIL si traitement de données nominatives | Pennylane co-traitant inscrit au registre art. 30 (TASK-0704, 0705) |
PDP vs OD vs PPF — qui fait quoi
- PDP (Plateforme de Dématérialisation Partenaire) : agréée DGFiP, transmet factures et données fiscales (e-reporting). Pennylane est PA avec immatriculation définitive.
- OD (Opérateur de Dématérialisation): non-agréée, génère des factures conformes. Doit s'appuyer sur une PDP pour la transmission. C'est la posture YaniPay Phase 1.
- PPF (Portail Public de Facturation): opéré par l'AIFE, rôle réduit à l'annuaire des entreprises et la réception du e-reporting. Pas de transmission de factures.
Phase 2 conditionnée
InvoiceProvider (factory pattern) permet la bascule sans casse fonctionnelle. Backlog : EPIC-2026-0006 — 5 sprints W20→W35 et 17 tasks.Prochaines etapes
Ressources associees
Last updated: 2026-05-07 — ajout section E-invoicing reform 2026 (Factur-X, Pennylane PDP, XAdES-EPES, NF Z42-013, EPIC-2026-0006). Précédent : 16+ routes web + 5 routes mobile (/api/v1/mobile/payments/*), masquage IBAN (T-21), diagramme SEPA Swan BaaS, loyalty cashback EUR, routing CeFi/DeFi, types @platform/api/contracts/payments