Gérer les échecs de transfert

​

Vue d’ensemble

​

Statuts de transfert

• pending : Le transfert est en cours de traitement
• success : Le transfert a été effectué avec succès
• error : Le transfert a échoué

​

Erreurs communes

​

Solde insuffisant (400 Bad Request)

• Vérifiez le solde du magasin avant de créer le transfert
• Assurez-vous que le solde couvre le montant du transfert plus les frais
• Provisionnez le compte du magasin si nécessaire

{
  "id": "insufficient_balance",
  "message": "Insufficient balance",
  "extras": "Wallet balance is not sufficient for this transfer"
}

​

Transfert échoué (400 Bad Request)

• Vérifiez que les informations du contact bénéficiaire sont correctes
• Vérifiez que le numéro de téléphone ou le compte bancaire est actif
• Réessayez le transfert après un court délai
• Contactez le support si le problème persiste

{
  "id": "transfer_failed",
  "message": "Transfer failed to finish",
  "extras": "Transfer processing failed"
}

​

Contact non trouvé (404 Not Found)

• Vérifiez que le contactId est correct
• Assurez-vous que le contact a été créé avant d’effectuer le transfert
• Utilisez l’endpoint /partner_api/contacts pour lister vos contacts

{
  "id": "contact_not_found",
  "message": "Contact not found",
  "extras": "Contact not found"
}

​

Magasin non trouvé (404 Not Found)

• Vérifiez que le storeId est correct
• Utilisez l’endpoint /partner_api/stores pour lister vos magasins
• Assurez-vous que le magasin existe et est actif

{
  "id": "store_not_found",
  "message": "Store not found",
  "extras": "Store not found"
}

​

Erreur de validation (422 Unprocessable Entity)

• Vérifiez que le montant respecte le minimum (500 centimes = 5 XOF)
• Vérifiez que la devise est au format ISO 4217 (3 caractères)
• Vérifiez que tous les champs requis sont présents et valides
• Vérifiez que la description ne dépasse pas 255 caractères

• Montant inférieur à 500 centimes
• Code devise invalide (doit être “XOF” ou autre code ISO 4217 valide)
• Champs requis manquants

​

Clé API invalide (401 Unauthorized)

• Vérifiez que les en-têtes X-API-KEY et X-API-KEY-ID sont présents
• Vérifiez que les clés API sont correctes
• Régénérez vos clés API depuis le Jeko Cockpit si nécessaire

​

Accès interdit (403 Forbidden)

• Vérifiez les permissions de votre clé API
• Contactez le support pour vérifier les permissions de votre compte

​

Gestion des erreurs dans votre application

​

Vérification préventive

1. Vérifier l’existence du contact :

curl -X GET "https://api.jeko.africa/partner_api/contacts/{contactId}" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here"

2. Vérifier le solde du magasin :

curl -X GET "https://api.jeko.africa/partner_api/stores/{storeId}/balance" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here"

3. Valider les données :
   • Montant superieur ou égale 500 centimes
   • Code devise valide (ISO 4217)
   • Description inferieur ou égale 255 caractères

​

Gestion des erreurs dans le code

async function createTransfer(storeId, contactId, amountCents, currency, description) {
  try {
    // Vérifier le solde avant le transfert
    const balance = await checkStoreBalance(storeId);
    const requiredAmount = amountCents + estimatedFees; // Inclure les frais estimés
    
    if (balance < requiredAmount) {
      throw new Error('Solde insuffisant');
    }
    
    // Créer le transfert
    const response = await fetch('https://api.jeko.africa/partner_api/transfers', {
      method: 'POST',
      headers: {
        'X-API-KEY': apiKey,
        'X-API-KEY-ID': apiKeyId,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        storeId,
        contactId,
        amountCents,
        currency,
        description
      })
    });
    
    if (!response.ok) {
      const error = await response.json();
      
      // Gérer les erreurs spécifiques
      switch (error.id) {
        case 'insufficient_balance':
          // Gérer le solde insuffisant
          console.error('Solde insuffisant:', error.message);
          break;
        case 'contact_not_found':
          // Gérer le contact introuvable
          console.error('Contact introuvable:', error.message);
          break;
        case 'store_not_found':
          // Gérer le magasin introuvable
          console.error('Magasin introuvable:', error.message);
          break;
        case 'transfer_failed':
          // Gérer l'échec du transfert
          console.error('Transfert échoué:', error.message);
          // Optionnel : réessayer après un délai
          break;
        default:
          console.error('Erreur inconnue:', error);
      }
      
      throw error;
    }
    
    return await response.json();
  } catch (error) {
    // Gérer les erreurs réseau ou autres
    console.error('Erreur lors de la création du transfert:', error);
    throw error;
  }
}

​

Utilisation des webhooks pour le suivi

• Suivre les transferts en temps réel
• Gérer les échecs automatiquement
• Mettre à jour votre système lorsque le statut change

​

Bonnes pratiques

1. Vérifications préventives : Toujours vérifier le solde et l’existence du contact avant de créer un transfert
2. Gestion d’erreurs robuste : Implémentez une gestion d’erreurs complète pour tous les cas d’échec
3. Logging : Enregistrez toutes les erreurs pour le débogage et l’analyse
4. Retry logic : Pour les erreurs temporaires (comme transfer_failed), implémentez une logique de réessai avec backoff exponentiel
5. Notifications utilisateur : Informez l’utilisateur des erreurs de manière claire et actionnable
6. Monitoring : Surveillez les taux d’échec pour identifier les problèmes récurrents

​

Support