Skip to main content

​
Vue d’ensemble

Les paiements en ligne utilisent des liens de paiement partageables. Le client est redirigé vers une page de paiement sécurisée JEKO où il peut sélectionner son moyen de paiement et confirmer la transaction.

​
Cas d’usage

  • Sites e-commerce
  • Paiements de factures en ligne
  • Collecte de fonds
  • Commandes en ligne
  • Paiements récurrents (avec liens réutilisables)

​
Créer un lien de paiement

Pour créer un lien de paiement, utilisez l’endpoint /partner_api/payment_links.

​
Paramètres requis

  • storeId : Identifiant du magasin
  • title : Titre du lien de paiement (10-255 caractères)
  • amountCents : Montant fixe en centimes (minimum 10000 centimes = 100 XOF)
  • currency : Code devise (ISO 4217), généralement “XOF”
  • allowMultiplePayments : (Optionnel) Permet plusieurs paiements sur le même lien (défaut: false)

​
Exemple : Lien à usage unique

curl -X POST "https://api.jeko.africa/partner_api/payment_links" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
    "title": "Paiement pour services - Commande #12345",
    "amountCents": 50000,
    "currency": "XOF",
    "allowMultiplePayments": false
  }'

​
Exemple : Lien réutilisable

curl -X POST "https://api.jeko.africa/partner_api/payment_links" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
    "title": "Dons pour association",
    "amountCents": 10000,
    "currency": "XOF",
    "allowMultiplePayments": true
  }'

​
Réponse réussie

{
  "id": "d22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc",
  "storeId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
  "title": "Paiement pour services - Commande #12345",
  "amount": {
    "amount": 50000,
    "currency": "XOF"
  },
  "allowMultiplePayments": false,
  "canReceivePayments": true,
  "link": "https://pay.jeko.africa/c/abc123def456"
}
Important : Le champ link contient l’URL partageable à envoyer au client. Le champ canReceivePayments indique si le lien peut actuellement accepter de nouveaux paiements.

​
Types de liens de paiement

​
Liens à usage unique (allowMultiplePayments: false)

  • Comportement : Le lien devient indisponible après le premier paiement réussi
  • Cas d’usage : Paiements de factures, commandes spécifiques
  • Disponibilité : canReceivePayments passe à false après le premier paiement
Note : Les liens de paiement n’ont pas de statut (pas de pending, success, error). Utilisez uniquement canReceivePayments pour vérifier la disponibilité.

​
Liens réutilisables (allowMultiplePayments: true)

  • Comportement : Le lien peut accepter plusieurs paiements
  • Cas d’usage : Collecte de fonds, dons, abonnements
  • Disponibilité : canReceivePayments reste true tant que le lien est actif

​
Vérifier la disponibilité d’un lien

Avant de diriger un client vers un lien, vérifiez qu’il peut encore accepter des paiements : 
curl -X GET "https://api.jeko.africa/partner_api/payment_links/{paymentLinkId}" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here"
Réponse : 
{
  "id": "d22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc",
  "storeId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
  "title": "Paiement pour services - Commande #12345",
  "amount": {
    "amount": 50000,
    "currency": "XOF"
  },
  "allowMultiplePayments": false,
  "canReceivePayments": false,
  "link": "https://pay.jeko.africa/c/abc123def456"
}
Important : Si canReceivePayments est false, ne dirigez pas le client vers le lien. Cela peut se produire si :
  • Le lien est à usage unique et a déjà été utilisé
  • Le lien a expiré
  • Le lien a été désactivé

​
Vérifier si un paiement a été complété (liens à usage unique)

Pour les liens à usage unique (allowMultiplePayments: false), vous pouvez vérifier si le paiement a été complété en vérifiant canReceivePayments :
  • canReceivePayments: true : Le lien peut encore accepter un paiement (pas encore payé)
  • canReceivePayments: false : Le paiement a été complété (pour les liens à usage unique)
Exemple : Vérifier si un paiement a été complété 
async function checkPaymentCompleted(paymentLinkId) {
  const response = await fetch(
    `https://api.jeko.africa/partner_api/payment_links/${paymentLinkId}`,
    {
      headers: {
        'X-API-KEY': apiKey,
        'X-API-KEY-ID': apiKeyId
      }
    }
  );
  
  const paymentLink = await response.json();
  
  // Pour les liens à usage unique, canReceivePayments: false signifie que le paiement a été complété
  if (paymentLink.allowMultiplePayments === false) {
    if (paymentLink.canReceivePayments === false) {
      return { completed: true, message: 'Le paiement a été complété' };
    } else {
      return { completed: false, message: 'Le paiement est en attente' };
    }
  }
  
  // Pour les liens réutilisables, canReceivePayments ne peut pas indiquer si un paiement spécifique a été complété
  // Utilisez les webhooks pour suivre les paiements individuels
  return { completed: null, message: 'Lien réutilisable - utilisez les webhooks pour suivre les paiements' };
}
Note : Cette méthode fonctionne uniquement pour les liens à usage unique. Pour les liens réutilisables, utilisez les webhooks pour suivre les paiements individuels.

​
Flux de paiement

  1. Créer le lien : Créez un lien de paiement via l’API
  2. Partager le lien : Envoyez le lien au client (email, SMS, message, etc.)
  3. Client clique : Le client clique sur le lien et est redirigé vers la page de paiement JEKO
  4. Sélection du moyen : Le client sélectionne son moyen de paiement
  5. Confirmation : Le client confirme le paiement
  6. Notification : Vous recevez une notification via webhook lorsque le paiement est complété

​
Intégration dans votre site e-commerce

​
Exemple : Bouton de paiement

<!-- Dans votre page de commande -->
<button id="pay-button" onclick="createPaymentLink()">
  Payer maintenant
</button>

<script>
async function createPaymentLink() {
  const response = await fetch('https://api.jeko.africa/partner_api/payment_links', {
    method: 'POST',
    headers: {
      'X-API-KEY': 'your_api_key_here',
      'X-API-KEY-ID': 'your_api_key_id_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      storeId: '59ae202a-f583-4a15-970f-9e99bd1e0baa',
      title: `Paiement - Commande #${orderId}`,
      amountCents: orderAmount,
      currency: 'XOF',
      allowMultiplePayments: false
    })
  });
  
  const paymentLink = await response.json();
  
  // Rediriger le client vers le lien de paiement
  window.location.href = paymentLink.link;
}
</script>

​
Exemple : Lien pré-créé

Si vous créez le lien à l’avance (par exemple, lors de la création de la commande), vous pouvez stocker le lien et l’afficher plus tard : 
// Lors de la création de la commande
const paymentLink = await createPaymentLink(orderId, amount);

// Stocker paymentLink.id et paymentLink.link dans votre base de données

// Plus tard, afficher le lien au client
function displayPaymentLink(orderId) {
  // Récupérer le lien depuis votre base de données
  const link = getStoredPaymentLink(orderId);
  
  // Vérifier que le lien peut encore accepter des paiements
  checkLinkAvailability(link.id).then(available => {
    if (available) {
      // Afficher le bouton de paiement
      document.getElementById('pay-button').href = link.link;
    } else {
      // Créer un nouveau lien
      createNewPaymentLink(orderId, amount);
    }
  });
}

​
Gestion des erreurs

​
Lien expiré

Si un client essaie d’utiliser un lien expiré, il recevra un message d’erreur. Vérifiez toujours canReceivePayments avant de diriger un client vers un lien.

​
Lien déjà utilisé

Pour les liens à usage unique, si le lien a déjà été utilisé, canReceivePayments sera false. Créez un nouveau lien si nécessaire.

​
Polling pour vérifier la complétion du paiement

Pour les liens à usage unique, vous pouvez implémenter un polling pour vérifier si le paiement a été complété : 
async function pollPaymentCompletion(paymentLinkId, maxAttempts = 60, intervalMs = 5000) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(
      `https://api.jeko.africa/partner_api/payment_links/${paymentLinkId}`,
      {
        headers: {
          'X-API-KEY': apiKey,
          'X-API-KEY-ID': apiKeyId
        }
      }
    );
    
    const paymentLink = await response.json();
    
    // Pour les liens à usage unique, canReceivePayments: false signifie paiement complété
    if (paymentLink.allowMultiplePayments === false && !paymentLink.canReceivePayments) {
      return { completed: true, paymentLink };
    }
    
    // Attendre avant le prochain essai
    await new Promise(resolve => setTimeout(resolve, intervalMs));
  }
  
  return { completed: false, message: 'Timeout - le paiement n\'a pas été complété dans le délai imparti' };
}

// Utilisation
const result = await pollPaymentCompletion(paymentLinkId);
if (result.completed) {
  console.log('Paiement complété !');
  // Mettre à jour la commande, envoyer un email de confirmation, etc.
}
Note : Le polling est une alternative aux webhooks. Pour une meilleure expérience, utilisez les webhooks comme méthode principale et le polling comme fallback. Consultez Gérer les échecs pour plus de détails sur les erreurs.

​
Bonnes pratiques

  1. Vérifier la disponibilité : Toujours vérifier canReceivePayments avant de diriger un client vers un lien
  2. Vérifier la complétion : Pour les liens à usage unique, utilisez canReceivePayments: false pour détecter que le paiement a été complété
  3. Liens à usage unique : Utilisez des liens à usage unique pour les paiements de factures ou commandes spécifiques
  4. Liens réutilisables : Utilisez des liens réutilisables pour les collectes de fonds ou dons
  5. Titres descriptifs : Utilisez des titres clairs qui aident le client à identifier le paiement
  6. Webhooks : Configurez des webhooks pour être notifié automatiquement des paiements (méthode recommandée)
  7. Polling : Pour les liens à usage unique, vous pouvez utiliser le polling comme alternative aux webhooks pour vérifier la complétion
  8. Expiration : Les liens peuvent expirer, prévoyez une gestion des liens expirés

​
Cas d’usage avancés

​
Paiements récurrents

Créez un lien réutilisable pour permettre aux clients de payer régulièrement : 
// Créer un lien réutilisable pour un abonnement mensuel
const subscriptionLink = await createPaymentLink({
  storeId: storeId,
  title: "Abonnement mensuel - Janvier 2024",
  amountCents: 10000,
  currency: "XOF",
  allowMultiplePayments: true
});

// Le même lien peut être utilisé chaque mois

​
Paiements de factures

Créez un lien à usage unique pour chaque facture : 
// Créer un lien unique pour chaque facture
const invoiceLink = await createPaymentLink({
  storeId: storeId,
  title: `Facture #${invoiceNumber} - ${customerName}`,
  amountCents: invoiceAmount,
  currency: "XOF",
  allowMultiplePayments: false
});

// Envoyer le lien au client par email
sendInvoiceEmail(customerEmail, invoiceLink.link);