Documentation Intégration Solution Bancaire

1.1 Objectif du Document

Ce document fournit les spécifications techniques complètes pour l'intégration de la solution bancaire OpenBanking dans l'écosystème REWAPP.

Il détaille :

• La configuration du partenaire bancaire (Budget Insight)
• Les endpoints API et leur utilisation
• La gestion des webhooks pour la détection des transactions
• L'initiation des virements SEPA pour le cashback bancaire
• Les procédures de test et de mise en production

1.2 Périmètre de l'Intégration

L'intégration bancaire couvre les fonctionnalités suivantes :

1.3 Architecture Globale

L'architecture d'intégration bancaire repose sur les composants suivants :

• Application Mobile : Interface utilisateur pour le card linking
• Banking Service : Gestion des tokens, virements, communication avec Budget Insight
• Webhook Handler : Réception et validation des notifications Budget Insight
• Transaction Service : Matching et traitement des transactions
• Points Service : Gestion du solde et des crédits de points

Communication avec Budget Insight

• API REST HTTPS (TLS 1.3)
• Authentification OAuth2 Client Credentials
• SDK natif compatible Capacitor pour le card linking mobile
• Webhooks HTTPS pour les notifications temps réel

1.4 Prérequis Techniques

Avant de démarrer l'intégration, les éléments suivants doivent être en place :

2.1 Fournisseur Recommandé : Budget Insight (Powens)

Budget Insight (groupe Powens) est le fournisseur OpenBanking recommandé pour REWAPP.

Raisons du choix

• Agrément ACPR : Établissement de paiement agréé par l'Autorité de Contrôle Prudentiel et de Résolution
• Couverture bancaire : Plus de 350 banques françaises et européennes
• Conformité PSD2 : Full compliance avec la directive européenne
• Certification PCI DSS : Niveau 1 (plus haut niveau de certification)
• SDK Capacitor : Intégration native pour l'application mobile Angular + Ionic
• Webhooks temps réel : Notification immédiate des nouvelles transactions
• Support technique : Documentation complète et support dédié

2.2 Alternatives Supportées

En cas d'indisponibilité ou de besoin spécifique, les fournisseurs suivants sont compatibles :

2.3 Critères de Sélection

2.4 Comparatif des Fournisseurs

3.1 Création du Compte Développeur

Étape 1 : Inscription sur le portail Budget Insight

URL : https://developers.budget-insight.com

Informations requises :

• Raison sociale : REWAPP Solutions SAS
• SIRET : [Numéro SIRET]
• Contact technique : tech@rewapp.fr
• Contact commercial : contact@rewapp.fr

Étape 2 : Validation du compte

Budget Insight procède à une vérification KYB (Know Your Business) :

• Vérification des documents légaux (Kbis, statuts)
• Validation du cas d'usage
• Signature du contrat de partenariat
• Délai : 5-10 jours ouvrés

3.2 Obtention des Clés API

Une fois le compte validé, les clés API sont disponibles dans le portail développeur :

3.3 Configuration des Environnements

Environnement Sandbox (Tests)

Environnement Production

3.4 Gestion des Secrets

Configuration des variables d'environnement CapRover :

{
  "budget_insight": {
    "sandbox": {
      "client_id": "bi_sandbox_xxx",
      "client_secret": "xxx",
      "webhook_secret": "xxx"
    },
    "production": {
      "client_id": "bi_prod_xxx",
      "client_secret": "xxx",
      "webhook_secret": "xxx"
    }
  }
}

Règles de rotation

• Rotation automatique tous les 90 jours
• Rotation immédiate en cas de suspicion de compromission
• Historique des versions conservé (30 jours)

4.1 Base URLs et Versioning

Versioning : L'API utilise le versioning dans l'URL. La version actuelle est v2.

Headers obligatoires

Content-Type: application/json
Authorization: Bearer {access_token}
X-Request-Id: {uuid} // Pour la traçabilité
User-Agent: REWAPP-BankingService/1.0

4.2 Authentification

L'API Budget Insight utilise OAuth2 avec le flow Client Credentials.

Obtention du token d'accès

grant_type=client_credentials
&client_id={client_id}
&client_secret={client_secret}

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "accounts transactions payments"
}

Gestion des tokens

• Durée de validité : 1 heure (3600 secondes)
• Renouvellement : Automatique avant expiration (5 min avant)
• Cache : Stockage en Redis avec TTL

4.3 Endpoints Principaux

4.4 Formats de Données

Format Connexion

{
  "id": "conn_abc123xyz",
  "user_id": "user_789",
  "bank_id": "bnp_paribas",
  "bank_name": "BNP Paribas",
  "status": "active",
  "last_sync": "2025-11-24T14:30:00.000Z",
  "created_at": "2025-11-01T10:00:00.000Z",
  "expires_at": "2026-01-29T10:00:00.000Z",
  "accounts": [
    {
      "id": "acc_456",
      "type": "checking",
      "name": "Compte Courant",
      "iban": "FR76****1234",
      "currency": "EUR"
    }
  ]
}

Format Transaction

{
  "id": "txn_xyz789",
  "connection_id": "conn_abc123xyz",
  "account_id": "acc_456",
  "amount": -45.50,
  "currency": "EUR",
  "direction": "DEBIT",
  "date": "2025-11-24",
  "value_date": "2025-11-24",
  "description": "PAIEMENT CB 2411 RESTAURANT LE BISTROT",
  "merchant": {
    "name": "RESTAURANT LE BISTROT",
    "mcc_code": "5812",
    "mcc_category": "Restaurants",
    "city": "PARIS",
    "country": "FR"
  },
  "card": {
    "last_four": "1234"
  },
  "category": "food_and_dining",
  "status": "booked"
}

4.5 Codes de Réponse HTTP

5.1 Vue d'Ensemble du Flux OAuth2

Le card linking utilise le flux OAuth2 Authorization Code avec PKCE pour une sécurité maximale.

Étapes du flux

1. 1

   Application Mobile → Banking Service

   Demande d'initialisation

2. 2

   Banking Service → Budget Insight

   POST /auth/init

3. 3

   Budget Insight → Banking Service

   URL d'autorisation + state token

4. 4

   Application Mobile → SDK Budget Insight

   Lancement interface de connexion

5. 5

   Utilisateur → Banque

   Authentification SCA (2FA)

6. 6

   Banque → Budget Insight

   Code d'autorisation

7. 7

   Budget Insight → Application Mobile

   Callback avec connection_id

8. 8

   Application Mobile → Banking Service

   Finalisation de la liaison

9. 9

   Banking Service → Base de données

   Stockage token chiffré

5.2 Étape 1 : Initialisation de la Session

{
  "device_id": "device_abc123",
  "platform": "ios"
}

{
  "session_id": "sess_xyz789",
  "auth_url": "https://webview.budget-insight.com/auth/xxx",
  "expires_at": "2025-11-24T14:40:00.000Z"
}

Actions Backend

• Générer un session_id unique (UUID v4)
• Stocker en Redis avec TTL 10 minutes
• Appeler Budget Insight POST /auth/init
• Retourner l'URL d'autorisation

5.3 Étape 2 : Redirection vers Budget Insight

{
  "client_id": "bi_prod_rewapp",
  "redirect_uri": "rewapp://banking/callback",
  "state": "sess_xyz789",
  "scope": "accounts transactions",
  "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "code_challenge_method": "S256"
}

{
  "auth_url": "https://webview.budget-insight.com/auth/abc123",
  "state": "sess_xyz789",
  "expires_in": 600
}

5.4 Étape 3 : Authentification Bancaire (SCA)

L'utilisateur est redirigé vers l'interface Budget Insight (webview ou navigateur in-app) où il :

1. 1

   Sélectionne sa banque

   Dans la liste des banques supportées

2. 2

   Saisit ses identifiants bancaires

   Directement chez Budget Insight

3. 3

   Valide l'authentification forte (SCA)

   Via son application bancaire

4. 4

   Accorde le consentement

   D'accès aux données

5.5 Étape 4 : Callback et Récupération des Tokens

Callback Budget Insight → Application Mobile

rewapp://banking/callback?connection_id=conn_abc123&state=sess_xyz789

{
  "session_id": "sess_xyz789",
  "connection_id": "conn_abc123"
}

Actions Backend

• Valider le session_id (existe en Redis, non expiré)
• Appeler Budget Insight GET /connections/{id}
• Récupérer les détails de la connexion et du compte
• Enregistrer le webhook pour cette connexion

5.6 Étape 5 : Stockage Sécurisé

Données stockées dans PostgreSQL (table bank_connections) :

{
  "id": "bc_rewapp_001",
  "user_id": "user_789",
  "bi_connection_id": "AES256_ENCRYPTED(conn_abc123)",
  "bank_name": "BNP Paribas",
  "bank_logo_url": "https://assets.bi.com/bnp.png",
  "account_iban_masked": "FR76****1234",
  "card_last_four": "1234",
  "status": "active",
  "consent_expires_at": "2026-01-29T10:00:00.000Z",
  "created_at": "2025-11-24T14:35:00.000Z",
  "updated_at": "2025-11-24T14:35:00.000Z"
}

Chiffrement

• Algorithme : AES-256-GCM
• Clé : Stockée dans variables d'environnement CapRover
• IV : Généré aléatoirement pour chaque enregistrement

5.7 Exemples de Code

Service NestJS - Initialisation Card Linking

// banking.service.ts
@Injectable()
export class BankingService {
  async initCardLinking(userId: string, deviceId: string): Promise<CardLinkingSession> {
    // 1. Générer session ID
    const sessionId = uuidv4();
    
    // 2. Appeler Budget Insight
    const biResponse = await this.budgetInsightClient.post('/auth/init', {
      client_id: this.config.clientId,
      redirect_uri: 'rewapp://banking/callback',
      state: sessionId,
      scope: 'accounts transactions'
    });
    
    // 3. Stocker session en Redis (TTL 10 min)
    await this.redis.setex(
      'card_linking:' + sessionId,
      600,
      JSON.stringify({ userId, deviceId, createdAt: new Date() })
    );
    
    // 4. Retourner les infos
    return {
      sessionId,
      authUrl: biResponse.data.auth_url,
      expiresAt: new Date(Date.now() + 600000)
    };
  }
}

6.1 Architecture des Webhooks

Les webhooks permettent à Budget Insight de notifier REWAPP en temps réel lorsqu'une nouvelle transaction est détectée sur le compte bancaire d'un utilisateur.

Flux de réception

1. 1

   Budget Insight détecte une nouvelle transaction

2. 2

   Budget Insight envoie un POST HTTPS vers l'endpoint REWAPP

3. 3

   Webhook Handler valide la signature HMAC-SHA256

4. 4

   Webhook Handler répond HTTP 200 immédiatement

5. 5

   Job ajouté à la queue Bull pour traitement asynchrone

6. 6

   Transaction Service traite le job

6.2 Événements Supportés

6.3 Format des Payloads

Payload transaction.created

POST /webhooks/banking
Content-Type: application/json
X-Webhook-Signature: sha256=7d38cdd689735b008b3c702edd92eea23791c5f6...
X-Webhook-Timestamp: 1732456800
X-Webhook-Id: wh_evt_abc123

{
  "event": "transaction.created",
  "timestamp": "2025-11-24T14:30:00.000Z",
  "webhook_id": "wh_evt_abc123",
  "data": {
    "transaction_id": "txn_xyz789",
    "connection_id": "conn_abc123",
    "account_id": "acc_456",
    "amount": -45.50,
    "currency": "EUR",
    "direction": "DEBIT",
    "date": "2025-11-24",
    "description": "PAIEMENT CB 2411 RESTAURANT LE BISTROT",
    "merchant": {
      "name": "RESTAURANT LE BISTROT",
      "mcc_code": "5812",
      "mcc_category": "Restaurants",
      "city": "PARIS",
      "country": "FR"
    },
    "status": "booked"
  }
}

Payload payment.completed

{
  "event": "payment.completed",
  "timestamp": "2025-11-24T15:45:00.000Z",
  "webhook_id": "wh_evt_def456",
  "data": {
    "payment_id": "pay_xyz789",
    "amount": 9.50,
    "currency": "EUR",
    "status": "COMPLETED",
    "reference": "REWAPP-WD-2025-11-24-001",
    "beneficiary_iban": "FR76****5678",
    "execution_date": "2025-11-24"
  }
}

6.4 Sécurité et Validation

Étape 1 : Vérification de l'IP source

Les webhooks ne sont acceptés que depuis les IPs Budget Insight (whitelist) :

• 52.47.XXX.XXX (Production EU-West-1)
• 35.180.XXX.XXX (Production EU-West-1)

Étape 2 : Vérification de la signature HMAC-SHA256

// Calcul de la signature attendue
const expectedSignature = crypto
  .createHmac('sha256', webhookSecret)
  .update(timestamp + '.' + rawBody)
  .digest('hex');

// Comparaison sécurisée (timing-safe)
if (!crypto.timingSafeEqual(
  Buffer.from(receivedSignature),
  Buffer.from('sha256=' + expectedSignature)
)) {
  throw new UnauthorizedException('WEBHOOK_SIGNATURE_INVALID');
}

Étape 3 : Protection anti-replay

const webhookTimestamp = parseInt(headers['x-webhook-timestamp']);
const currentTimestamp = Math.floor(Date.now() / 1000);

if (currentTimestamp - webhookTimestamp > 300) { // 5 minutes
  throw new UnauthorizedException('WEBHOOK_TIMESTAMP_EXPIRED');
}

Étape 4 : Idempotence

// Vérifier si le webhook a déjà été traité
const processed = await this.redis.get('webhook:' + webhookId);
if (processed) {
  return { status: 'already_processed' };
}

// Marquer comme traité (TTL 24h)
await this.redis.setex('webhook:' + webhookId, 86400, 'processed');

6.5 Gestion des Retries

Politique de retry Budget Insight

Réponses attendues par Budget Insight

6.6 Exemples de Traitement

Webhook Handler NestJS

// webhook.controller.ts
@Controller('webhooks')
export class WebhookController {
  @Post('banking')
  async handleBankingWebhook(
    @Headers() headers: Record<string, string>,
    @Body() body: any,
    @Req() req: Request
  ) {
    // 1. Valider la signature
    await this.webhookService.validateSignature(
      headers['x-webhook-signature'],
      headers['x-webhook-timestamp'],
      req.rawBody
    );
    
    // 2. Répondre immédiatement (important pour éviter le timeout)
    // Le traitement se fait de manière asynchrone
    
    // 3. Ajouter le job à la queue
    await this.transactionQueue.add('process-webhook', {
      event: body.event,
      data: body.data,
      webhookId: body.webhook_id
    });
    
    return { received: true };
  }
}

7.1 Flux de Détection

Lorsqu'une transaction est reçue via webhook, le flux suivant est exécuté :

1. 1

   Webhook Handler reçoit et valide le webhook

2. 2

   Job ajouté à la queue "transactions"

3. 3

   Transaction Service consomme le job

4. 4

   Vérification d'idempotence

   Transaction déjà traitée ?

5. 5

   Identification de l'utilisateur via connection_id

6. 6

   Matching du commerçant dans la base REWAPP

7. 7

   Si match → Calcul des points et crédit

8. 8

   Si pas de match → Transaction ignorée (log uniquement)

7.2 Algorithme de Matching Commerçant

Le matching s'effectue selon plusieurs critères, par ordre de priorité :

Algorithme de matching

async function matchMerchant(transaction: Transaction): Promise<Merchant | null> {
  // 1. Match par ID externe (le plus fiable)
  let merchant = await this.merchantRepo.findByExternalId(
    transaction.merchant.external_id
  );
  if (merchant) return merchant;
  
  // 2. Match par SIRET si disponible
  if (transaction.merchant.siret) {
    merchant = await this.merchantRepo.findBySiret(
      transaction.merchant.siret
    );
    if (merchant) return merchant;
  }
  
  // 3. Match par nom exact + ville
  merchant = await this.merchantRepo.findByNameAndCity(
    transaction.merchant.name,
    transaction.merchant.city
  );
  if (merchant) return merchant;
  
  // 4. Match fuzzy (Levenshtein distance < 3)
  merchant = await this.merchantRepo.findByFuzzyName(
    transaction.merchant.name,
    transaction.merchant.mcc_code
  );
  if (merchant && merchant.matchScore > 0.7) return merchant;
  
  // Pas de match
  return null;
}

7.3 Calcul des Points de Cashback

Exemple

• Montant transaction : 100€
• Taux cashback commerçant : 4%
• Palier utilisateur : Silver (+5%)
• Calcul : (100 × 0.04 × 1.05) / 0.10 = 42 points

7.4 Gestion des Transactions Non Matchées

Les transactions qui ne correspondent à aucun partenaire REWAPP sont :

• Loggées pour analyse (amélioration du matching)
• Ignorées pour le crédit de points
• Non notifiées à l'utilisateur

Métriques suivies

• Taux de matching global (objectif > 80%)
• Top 10 commerçants non matchés
• Transactions par MCC code non couvert

8.1 Prérequis PIS (Payment Initiation Service)

Pour initier des virements, REWAPP utilise le service PIS de Budget Insight qui requiert :

• Agrément PIS actif (inclus dans le contrat Budget Insight)
• IBAN source : Compte REWAPP dédié aux virements
• IBAN destination : Compte bancaire de l'utilisateur (récupéré lors du card linking)
• Montant : Calculé selon le ratio cashback bancaire (points × 0.095)

8.2 Flux d'Initiation de Virement

1. 1

   Utilisateur demande un virement dans l'app

   Minimum 100 points

2. 2

   Banking Service vérifie le solde disponible

3. 3

   Points Service bloque les points concernés

4. 4

   Banking Service calcule le montant

   points × 0.095 = -5% vs valeur nominale

5. 5

   Création d'un enregistrement withdrawal

   status: pending

6. 6

   Banking Service appelle POST /payments/initiate

7. 7

   Budget Insight initie le virement SEPA

8. 8

   Mise à jour du statut

   status: processing

9. 9

   Webhook payment.completed reçu

   2-3 semaines

10. 10

    Points définitivement débités

    status: completed

8.3 Validation de l'IBAN

Avant chaque virement, l'IBAN est validé :

function validateIBAN(iban: string): boolean {
  // 1. Nettoyage (suppression espaces)
  const cleanIban = iban.replace(/s/g, '').toUpperCase();
  
  // 2. Vérification format FR
  if (!cleanIban.match(/^FR[0-9]{2}[0-9A-Z]{23}$/)) {
    return false;
  }
  
  // 3. Vérification checksum (modulo 97)
  const rearranged = cleanIban.slice(4) + cleanIban.slice(0, 4);
  const numericIban = rearranged.replace(/[A-Z]/g, 
    (char) => (char.charCodeAt(0) - 55).toString()
  );
  
  return BigInt(numericIban) % 97n === 1n;
}

8.4 Suivi du Statut

8.5 Exemples de Requêtes

{
  "points_amount": 100,
  "destination_iban": "FR7612345678901234567890123"
}

{
  "withdrawal_id": "wd_abc123",
  "points_amount": 100,
  "euro_amount": 9.50,
  "status": "pending",
  "estimated_arrival": "2025-12-08",
  "created_at": "2025-11-24T16:00:00.000Z"
}

Requête Banking Service → Budget Insight

{
  "amount": 9.50,
  "currency": "EUR",
  "source_iban": "FR7699999999999999999999999",
  "beneficiary": {
    "name": "Jean Dupont",
    "iban": "FR7612345678901234567890123"
  },
  "reference": "REWAPP-WD-2025-11-24-001",
  "execution_date": "2025-11-24"
}

9.1 Codes d'Erreur Budget Insight

9.2 Codes d'Erreur REWAPP

9.3 Stratégies de Retry

Implémentation retry avec backoff

async function callWithRetry<T>(
  fn: () => Promise<T>,
  maxRetries: number = 3
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries || !isRetryable(error)) {
        throw error;
      }
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await sleep(delay);
    }
  }
}

9.4 Circuit Breaker

Protection contre les cascades de pannes :

9.5 Dead Letter Queue

Les jobs échoués après toutes les tentatives sont placés en DLQ :

10.1 Environnement Sandbox

Comptes de test disponibles

10.2 Environnement de Staging

10.3 Environnement de Production

10.4 Données de Test

10.5 Checklist de Validation

Avant mise en production :

☐ Card Linking

• Flux OAuth2 complet testé
• Gestion des erreurs (annulation, timeout)
• Stockage chiffré des tokens vérifié
• Révocation de connexion testée

☐ Webhooks

• Réception et validation signature OK
• Protection anti-replay fonctionnelle
• Idempotence vérifiée (même webhook 2x)
• Traitement asynchrone (queue Bull)

☐ Matching Transactions

• Match par ID externe OK
• Match par nom + ville OK
• Calcul points correct
• Transactions non matchées ignorées

☐ Virements

• Validation IBAN fonctionnelle
• Blocage points avant initiation
• Webhook payment.completed traité
• Gestion des échecs (déblocage points)

☐ Sécurité

• Chiffrement AES-256 vérifié
• Secrets dans variables d'environnement CapRover
• IP whitelisting webhooks
• Rate limiting actif

☐ Monitoring

• Alertes CloudWatch configurées
• Dashboard de supervision opérationnel
• Logs centralisés

11.1 Métriques Clés

11.2 Alertes Configurées

11.3 Dashboard de Supervision

Tableaux de bord CloudWatch :

12.1 Conformité PSD2

12.2 Conformité PCI DSS

12.3 Conformité RGPD

12.4 Mesures de Sécurité

13.1 Points Clés de l'Intégration

• Fournisseur recommandé : Budget Insight (Powens) - Agrément ACPR, PCI DSS niveau 1
• Card Linking : OAuth2 + PKCE via SDK natif, tokens chiffrés AES-256
• Webhooks : Signature HMAC-SHA256, protection anti-replay, traitement asynchrone
• Matching : Algorithme multi-critères (ID, SIRET, nom, MCC), taux objectif >80%
• Virements : PIS via Budget Insight, validation IBAN, délai 2-3 semaines
• Sécurité : Aucune donnée de carte stockée, conformité PSD2/PCI DSS/RGPD

13.2 Contacts et Support

13.3 Documents Connexes