Documentation Index
Fetch the complete documentation index at: https://developer.jeko.africa/llms.txt
Use this file to discover all available pages before exploring further.
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
}'
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
- 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);