🌐 Intégration API Wise - Africa Bridge Pay

Dernière révision: 2026-09-08

Documentation complète de l'intégration de l'API Wise pour la tarification dynamique.

📋 Table des matières

1. Vue d'ensemble
2. Configuration
3. Architecture
4. Règle de tarification
5. Utilisation
6. Tests
7. Déploiement en production

---

🎯 Vue d'ensemble

L'intégration Wise permet à Africa Bridge Pay d'obtenir des taux de change en temps réel et des frais de transfert précis directement depuis l'API Wise (TransferWise).

Avantages

• ✅ Taux interbancaires réels sans spread
• ✅ Tarification transparente avec la règle des 3x Wise
• ✅ Calculs automatiques des marges et frais
• ✅ Fallback automatique sur taux statiques si l'API échoue
• ✅ Cache intelligent pour réduire les appels API
• ✅ Debouncing pour optimiser les performances

---

⚙️ Configuration

1. Créer un compte Wise Sandbox

1. Allez sur https://sandbox.transferwise.tech/register
2. Créez un compte de test (gratuit)
3. Vérifiez votre email

2. Générer un API Token

1. Connectez-vous au sandbox
2. Allez dans Settings > API Tokens
3. Cliquez sur Create a token
4. Donnez un nom (ex: "Africa Bridge Pay Dev")
5. Copiez le token (vous ne le reverrez plus !)

3. Récupérer votre Profile ID

Option A: Via l'interface web

1. Allez dans votre profil
2. L'ID est dans l'URL : https://sandbox.transferwise.tech/user/{ID}

Option B: Via l'API

curl -X GET "https://api.sandbox.transferwise.tech/v2/profiles" \
  -H "Authorization: Bearer YOUR_TOKEN"

4. Configurer les variables d'environnement

Copiez .env.example vers .env.local :

cp .env.example .env.local

Modifiez .env.local :

WISE_API_BASE_URL=https://api.sandbox.transferwise.tech
WISE_API_TOKEN=votre_token_ici
WISE_PROFILE_ID=votre_profile_id_ici

---

🏗️ Architecture

Composants créés

africa-bridge-pay/
├── app/
│   └── api/
│       └── wise-quote/
│           └── route.ts           # Route handler Next.js (API sécurisée)
├── hooks/
│   └── useWiseQuote.ts           # Hook React avec debouncing et cache
├── components/
│   └── WiseCalculator.tsx        # Composant UI du calculateur
└── types/
    └── wise.ts                   # Types TypeScript pour Wise

Flux de données

[Utilisateur saisit un montant]
          ↓
[WiseCalculator] → [useWiseQuote hook]
          ↓
[Debounce 500ms] → [Cache check]
          ↓
[POST /api/wise-quote] (Next.js Route Handler)
          ↓
[Appel API Wise] → [Calcul marges ABP]
          ↓
[Réponse avec devis complet]
          ↓
[Affichage dans l'UI]

---

💰 Règle de Tarification

Principe

Pour chaque transaction, Africa Bridge Pay applique cette logique simplifiée :

1. Taux de change : Taux Wise + 1.0% de marge FIXE
2. Frais de transfert ABP : 14.00 EUR + (Montant × 0.005)
3. Commission : 0.5% du montant source

Exemple concret

Facture fournisseur : 1 000 USD

1. API Wise retourne :
   - Taux interbancaire : 1 USD = 0.92 EUR

2. Africa Bridge Pay calcule :
   - Taux ABP : 0.92 × 1.01 = 0.929 EUR (+ 1.0%)
   - Montant source : 1000 × 0.929 = 929 EUR
   - Frais transfert : 14.00 + (929 × 0.005) = 18.65 EUR
   - Commission service : 929 × 0.005 = 4.65 EUR

3. Total client : 929 + 18.65 + 4.65 = 952.30 EUR
   (soit ~624 740 XOF)

Avantages de cette règle

• ✅ Simplicité totale : Une seule règle pour tous les montants
• ✅ Transparence : Calculs prévisibles et linéaires
• ✅ Compétitivité : Spread réduit à 1.0% (au lieu de paliers variables)
• ✅ Sans plafond : Frais de transfert proportionnels au montant

---

🚀 Utilisation

Dans un composant React

import { useWiseQuote } from '@/hooks/useWiseQuote';

function MyComponent() {
  const { quote, loading, error, fetchQuote } = useWiseQuote();

  const handleCalculate = async () => {
    await fetchQuote(
      1000,        // Montant
      'target',    // Type: 'source' ou 'target'
      'EUR',       // Devise source
      'USD'        // Devise cible
    );
  };

  if (loading) return <div>Chargement...</div>;
  if (error) return <div>Erreur: {error}</div>;
  if (quote) return <div>Total: {quote.totalAmountXOF} XOF</div>;
}

Appel direct à l'API

const response = await fetch('/api/wise-quote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    amount: 1000,
    amountType: 'target',
    sourceCurrency: 'EUR',
    targetCurrency: 'USD',
  }),
});

const data = await response.json();
console.log(data.quote);

---

🧪 Tests

1. Tester le Route Handler

# Vérifier que l'API est configurée
curl http://localhost:3000/api/wise-quote

# Faire un calcul de devis
curl -X POST http://localhost:3000/api/wise-quote \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "amountType": "target",
    "sourceCurrency": "EUR",
    "targetCurrency": "USD"
  }'

2. Tester dans l'interface

1. Démarrez le serveur : npm run dev
2. Allez sur /calculator
3. Saisissez un montant (ex: 1000)
4. Sélectionnez une devise (ex: USD)
5. Le calcul se fait automatiquement après 500ms

3. Vérifier le fallback

1. Arrêtez votre serveur
2. Videz les variables d'environnement Wise
3. Redémarrez
4. Le calculateur devrait fonctionner avec des taux statiques
5. Un message "Taux indicatif" s'affiche

---

🌍 Déploiement en production

1. Créer un compte Wise Business

1. Allez sur https://wise.com/business/register
2. Complétez le KYB (Know Your Business)
3. Activez votre compte

2. Générer un token de production

⚠️ ATTENTION : Le token de production donne accès à votre compte réel !

1. Connectez-vous à https://wise.com
2. Settings > API Tokens
3. Créez un token avec les permissions minimales nécessaires :
   • ✅ Read quotes
   • ❌ Pas besoin de "Create transfers" pour le calculateur

3. Mettre à jour les variables d'environnement

Sur votre plateforme de déploiement (Vercel, Railway, etc.) :

WISE_API_BASE_URL=https://api.transferwise.com
WISE_API_TOKEN=votre_token_production
WISE_PROFILE_ID=votre_profile_id_business

4. Sécurité

• ✅ Jamais commit les tokens dans Git
• ✅ Utiliser des variables d'environnement chiffrées
• ✅ Rotation des tokens tous les 3-6 mois
• ✅ Monitoring des appels API (alertes si usage anormal)
• ✅ Rate limiting côté serveur

---

📊 Monitoring et logs

Logs disponibles

Tous les appels API sont loggés côté serveur :

📞 Appel API Wise: { url, body }
✅ Réponse Wise reçue: quote-id-xxx
⚠️ Utilisation du devis de fallback statique
❌ Erreur API Wise: 429 - Rate limit exceeded

Métriques à surveiller

• Taux de succès des appels Wise
• Temps de réponse moyen
• Taux d'utilisation du fallback
• Nombre d'appels API par jour

---

🆘 Troubleshooting

Erreur: "Configuration Wise manquante"

Cause : Variables d'environnement non définies

Solution :

# Vérifier que .env.local existe et contient les bonnes valeurs
cat .env.local

# Redémarrer le serveur
npm run dev

Erreur: "Wise API error: 401"

Cause : Token d'API invalide ou expiré

Solution :

1. Vérifiez que le token est correct
2. Générez un nouveau token
3. Mettez à jour .env.local
4. Redémarrez le serveur

Erreur: "Wise API error: 429"

Cause : Rate limit dépassé (trop de requêtes)

Solution :

1. Le système bascule automatiquement sur le fallback
2. Augmentez le debounceMs dans useWiseQuote
3. Activez le cache plus longtemps (cacheDurationMs)

---

📚 Ressources

• Documentation officielle Wise API
• Guide d'authentification
• Référence des endpoints
• Sandbox Wise

---

Questions ? Contactez l'équipe technique Africa Bridge Pay.