Jèko
Transfers

Gérer les échecs de transfert

Comprendre les raisons d'échec des transferts et comment les gérer

Toute la doc dans votre agent

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 pour Mobile Money - sauf Moov Money : 10 000 centimes = 100 XOF - et 2 000 000 centimes = 20 000 XOF pour un virement bancaire vers RIB - 1 XOF = 100 centimes)
  • 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 au minimum (500 centimes pour Mobile Money - 10 000 centimes pour Moov Money - et 2 000 000 centimes pour un virement bancaire ; 1 XOF = 100 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

API non activée (403 Forbidden)

Erreur : business_not_enabled_for_api_access

Message : "This business account is not enabled for API access"

Cause : Vos clés sont valides, mais l'accès API de votre entreprise n'a pas encore été activé. Générer des clés dans le Dashboard et disposer d'un accès API sont deux étapes distinctes.

Solution :

  • Faites vérifier votre boutique depuis l'application Jèko Business, onglet Paramètres, en touchant l'encart du plafond de collecte. Le premier niveau franchi active l'API immédiatement
  • La procédure complète est décrite sur la page Authentification

Gestion des erreurs dans votre application

Vérification préventive

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

  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"
  1. 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"
  1. Valider les données :
    • Montant supérieur ou égal à 500 centimes pour Mobile Money (10 000 centimes pour Moov Money, 2 000 000 centimes / 20 000 XOF pour un virement bancaire ; 1 XOF = 100 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

  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 : Traitez chaque code d'erreur listé ci-dessus
  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

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

Gestion des contacts bénéficiaires

Créer et gérer les contacts bénéficiaires pour les transferts

Les trois produits

Paiement en ligne, lien de paiement et terminal en magasin : ce que chacun demande en entrée et ce qu'il renvoie

On this page

Vue d'ensembleStatuts de transfertErreurs communesSolde insuffisant (400 Bad Request)Transfert échoué (400 Bad Request)Contact non trouvé (404 Not Found)Magasin non trouvé (404 Not Found)Erreur de validation (422 Unprocessable Entity)Clé API invalide (401 Unauthorized)Accès interdit (403 Forbidden)API non activée (403 Forbidden)Gestion des erreurs dans votre applicationVérification préventiveGestion des erreurs dans le codeUtilisation des webhooks pour le suiviBonnes pratiquesSupport