Gérer les échecs de transfert

Vue d'ensemble

Un transfert échoue le plus souvent pour trois raisons : le solde du magasin ne couvre pas le montant et les frais, le contact bénéficiaire est introuvable, ou l'opérateur refuse l'opération. Cette page liste chaque erreur renvoyée par l'API et ce qu'il faut en faire.

Statuts de transfert

Les transferts peuvent avoir les statuts suivants :

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)

Erreur : insufficient_balance

Message : "Insufficient balance"

Cause : Le magasin ne dispose pas de fonds suffisants pour effectuer le transfert (montant + frais).

Solution :

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

Exemple de réponse :

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

Transfert échoué (400 Bad Request)

Erreur : transfer_failed

Message : "Transfer failed to finish"

Cause : Le traitement du transfert a échoué côté opérateur (Mobile Money ou banque).

Solution :

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

Exemple de réponse :

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

Contact non trouvé (404 Not Found)

Erreur : contact_not_found

Message : "Contact not found"

Cause : Le contactId fourni n'existe pas ou n'appartient pas à votre entreprise.

Solution :

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

Exemple de réponse :

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

Magasin non trouvé (404 Not Found)

Erreur : store_not_found

Message : "Store not found"

Cause : Le storeId fourni n'existe pas ou n'appartient pas à votre entreprise.

Solution :

Vérifiez que le storeId est correct
Utilisez l'endpoint pour lister vos magasins
Assurez-vous que le magasin existe et est actif

Exemple de réponse :

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

Erreur de validation (422 Unprocessable Entity)

Erreur : validation_error

Message : "Validation error"

Cause : Les données fournies ne respectent pas les règles de validation (montant minimum, format de devise, etc.).

Solution :

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

Exemples de problèmes de validation :

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)

Erreur : unauthorized

Message : "Unauthorized"

Cause : Les clés API sont invalides, manquantes ou expirées.

Solution :

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 Dashboard Business si nécessaire

Accès interdit (403 Forbidden)

Erreur : forbidden

Message : "Forbidden"

Cause : La clé API n'a pas la permission d'accéder à cette ressource ou d'effectuer cette action.

Solution :

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

Avant de créer un transfert, effectuez ces vérifications :

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"

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"

Valider les données :
- Montant supérieur ou égal à 500 centimes
- Code devise valide (ISO 4217)
- Description d'au plus 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

Configurez des webhooks pour être notifié automatiquement des changements de statut des transferts. Cela vous permet de :

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

Consultez la documentation Webhooks pour plus d'informations.

Bonnes pratiques

Vérifications préventives : Toujours vérifier le solde et l'existence du contact avant de créer un transfert
Gestion d'erreurs : Traitez chaque code d'erreur listé ci-dessus
Logging : Enregistrez toutes les erreurs pour le débogage et l'analyse
Retry logic : Pour les erreurs temporaires (comme transfer_failed), implémentez une logique de réessai avec backoff exponentiel
Notifications utilisateur : Informez l'utilisateur des erreurs de manière claire et actionnable
Monitoring : Surveillez les taux d'échec pour identifier les problèmes récurrents

Support

Si vous rencontrez des erreurs persistantes ou des problèmes non documentés, contactez le support Jèko à hello@jeko.africa.

On this page