Paiement en ligne (ecommerce / lien de paiement)

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. Pour plus de détails : /api-reference/liens-de-paiement/créer-un-lien-de-paiement

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
  }'

<?php
$ch = curl_init('https://api.jeko.africa/partner_api/payment_links');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: your_api_key_here',
    'X-API-KEY-ID: your_api_key_id_here',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'storeId' => '59ae202a-f583-4a15-970f-9e99bd1e0baa',
    'title' => 'Paiement pour services - Commande #12345',
    'amountCents' => 50000,
    'currency' => 'XOF',
    'allowMultiplePayments' => false
]));

$response = curl_exec($ch);
curl_close($ch);
$paymentLink = json_decode($response, true);
?>

const fetch = require('node-fetch');

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 pour services - Commande #12345',
    amountCents: 50000,
    currency: 'XOF',
    allowMultiplePayments: false
  })
});

const paymentLink = await response.json();

require 'net/http'
require 'json'
require 'uri'

uri = URI('https://api.jeko.africa/partner_api/payment_links')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request['X-API-KEY'] = 'your_api_key_here'
request['X-API-KEY-ID'] = 'your_api_key_id_here'
request['Content-Type'] = 'application/json'
request.body = {
  storeId: '59ae202a-f583-4a15-970f-9e99bd1e0baa',
  title: 'Paiement pour services - Commande #12345',
  amountCents: 50000,
  currency: 'XOF',
  allowMultiplePayments: false
}.to_json

response = http.request(request)
payment_link = JSON.parse(response.body)

import requests

url = 'https://api.jeko.africa/partner_api/payment_links'
headers = {
    'X-API-KEY': 'your_api_key_here',
    'X-API-KEY-ID': 'your_api_key_id_here',
    'Content-Type': 'application/json'
}
data = {
    'storeId': '59ae202a-f583-4a15-970f-9e99bd1e0baa',
    'title': 'Paiement pour services - Commande #12345',
    'amountCents': 50000,
    'currency': 'XOF',
    'allowMultiplePayments': False
}

response = requests.post(url, headers=headers, json=data)
payment_link = response.json()

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
  }'

<?php
$ch = curl_init('https://api.jeko.africa/partner_api/payment_links');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: your_api_key_here',
    'X-API-KEY-ID: your_api_key_id_here',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'storeId' => '59ae202a-f583-4a15-970f-9e99bd1e0baa',
    'title' => 'Dons pour association',
    'amountCents' => 10000,
    'currency' => 'XOF',
    'allowMultiplePayments' => true
]));

$response = curl_exec($ch);
curl_close($ch);
$paymentLink = json_decode($response, true);
?>

const fetch = require('node-fetch');

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: 'Dons pour association',
    amountCents: 10000,
    currency: 'XOF',
    allowMultiplePayments: true
  })
});

const paymentLink = await response.json();

require 'net/http'
require 'json'
require 'uri'

uri = URI('https://api.jeko.africa/partner_api/payment_links')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request['X-API-KEY'] = 'your_api_key_here'
request['X-API-KEY-ID'] = 'your_api_key_id_here'
request['Content-Type'] = 'application/json'
request.body = {
  storeId: '59ae202a-f583-4a15-970f-9e99bd1e0baa',
  title: 'Dons pour association',
  amountCents: 10000,
  currency: 'XOF',
  allowMultiplePayments: true
}.to_json

response = http.request(request)
payment_link = JSON.parse(response.body)

import requests

url = 'https://api.jeko.africa/partner_api/payment_links'
headers = {
    'X-API-KEY': 'your_api_key_here',
    'X-API-KEY-ID': 'your_api_key_id_here',
    'Content-Type': 'application/json'
}
data = {
    'storeId': '59ae202a-f583-4a15-970f-9e99bd1e0baa',
    'title': 'Dons pour association',
    'amountCents': 10000,
    'currency': 'XOF',
    'allowMultiplePayments': True
}

response = requests.post(url, headers=headers, json=data)
payment_link = response.json()

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"

<?php
$paymentLinkId = 'd22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc';
$ch = curl_init("https://api.jeko.africa/partner_api/payment_links/{$paymentLinkId}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: your_api_key_here',
    'X-API-KEY-ID: your_api_key_id_here'
]);

$response = curl_exec($ch);
curl_close($ch);
$paymentLink = json_decode($response, true);
?>

const fetch = require('node-fetch');

const paymentLinkId = 'd22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc';
const response = await fetch(
  `https://api.jeko.africa/partner_api/payment_links/${paymentLinkId}`,
  {
    headers: {
      'X-API-KEY': 'your_api_key_here',
      'X-API-KEY-ID': 'your_api_key_id_here'
    }
  }
);

const paymentLink = await response.json();

require 'net/http'
require 'json'
require 'uri'

payment_link_id = 'd22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc'
uri = URI("https://api.jeko.africa/partner_api/payment_links/#{payment_link_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.path)
request['X-API-KEY'] = 'your_api_key_here'
request['X-API-KEY-ID'] = 'your_api_key_id_here'

response = http.request(request)
payment_link = JSON.parse(response.body)

import requests

payment_link_id = 'd22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc'
url = f'https://api.jeko.africa/partner_api/payment_links/{payment_link_id}'
headers = {
    'X-API-KEY': 'your_api_key_here',
    'X-API-KEY-ID': 'your_api_key_id_here'
}

response = requests.get(url, headers=headers)
payment_link = response.json()

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

Créer le lien : Créez un lien de paiement via l’API
Partager le lien : Envoyez le lien au client (email, SMS, message, etc.)
Client clique : Le client clique sur le lien et est redirigé vers la page de paiement JEKO
Sélection du moyen : Le client sélectionne son moyen de paiement
Confirmation : Le client confirme le paiement
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

Vérifier la disponibilité : Toujours vérifier canReceivePayments avant de diriger un client vers un lien
Vérifier la complétion : Pour les liens à usage unique, utilisez canReceivePayments: false pour détecter que le paiement a été complété
Liens à usage unique : Utilisez des liens à usage unique pour les paiements de factures ou commandes spécifiques
Liens réutilisables : Utilisez des liens réutilisables pour les collectes de fonds ou dons
Titres descriptifs : Utilisez des titres clairs qui aident le client à identifier le paiement
Webhooks : Configurez des webhooks pour être notifié automatiquement des paiements (méthode recommandée)
Polling : Pour les liens à usage unique, vous pouvez utiliser le polling comme alternative aux webhooks pour vérifier la complétion
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);

Guide de démarrage

Transfers

Paiements

Webhooks

Service Providers

Paiement en ligne (ecommerce / lien de paiement)

Vue d’ensemble

Cas d’usage

Créer un lien de paiement

Paramètres requis

Exemple : Lien à usage unique

Exemple : Lien réutilisable

Réponse réussie

Types de liens de paiement

Liens à usage unique (`allowMultiplePayments: false`)

Liens réutilisables (`allowMultiplePayments: true`)

Vérifier la disponibilité d’un lien

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

Flux de paiement

Intégration dans votre site e-commerce

Exemple : Bouton de paiement

Exemple : Lien pré-créé

Gestion des erreurs

Lien expiré

Lien déjà utilisé

Polling pour vérifier la complétion du paiement

Bonnes pratiques

Cas d’usage avancés

Paiements récurrents

Paiements de factures

​Vue d’ensemble

​Cas d’usage

​Créer un lien de paiement

​Paramètres requis

​Exemple : Lien à usage unique

​Exemple : Lien réutilisable

​Réponse réussie

​Types de liens de paiement

​Liens à usage unique (allowMultiplePayments: false)

​Liens réutilisables (allowMultiplePayments: true)

​Vérifier la disponibilité d’un lien

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

​Flux de paiement

​Intégration dans votre site e-commerce

​Exemple : Bouton de paiement

​Exemple : Lien pré-créé

​Gestion des erreurs

​Lien expiré

​Lien déjà utilisé

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

​Bonnes pratiques

​Cas d’usage avancés

​Paiements récurrents

​Paiements de factures

Vue d’ensemble

Cas d’usage

Créer un lien de paiement

Paramètres requis

Exemple : Lien à usage unique

Exemple : Lien réutilisable

Réponse réussie

Types de liens de paiement

Liens à usage unique (`allowMultiplePayments: false`)

Liens réutilisables (`allowMultiplePayments: true`)

Vérifier la disponibilité d’un lien

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

Flux de paiement

Intégration dans votre site e-commerce

Exemple : Bouton de paiement

Exemple : Lien pré-créé

Gestion des erreurs

Lien expiré

Lien déjà utilisé

Polling pour vérifier la complétion du paiement

Bonnes pratiques

Cas d’usage avancés

Paiements récurrents

Paiements de factures