Acceptez des paiements en ligne en Côte d’Ivoire en quelques minutes

Introduction

Bienvenue sur la documentation Kadev Pay. Notre objectif est de vous permettre d'intégrer une solution de paiement complète (Mobile Money, Carte Bancaire) de la manière la plus simple et sécurisée possible. L'intégration se fait en deux temps : l'initialisation du paiement côté client (Frontend) et la confirmation sécurisée de la transaction côté serveur (Backend) via Webhook.

🚀 Quick Start – 3 étapes

Suivez ces étapes pour réaliser votre premier paiement test en moins de 10 minutes.

Flux de Paiement

Comprendre le cycle de vie d'une transaction est essentiel pour une intégration réussie.

🔑 Authentification

Kadev Pay utilise des clés API pour authentifier les requêtes. Vous trouverez vos clés dans votre Dashboard Développeur. Il existe trois types de clés :

• Clé Publique (kdvp_...): Sûre à utiliser dans votre code frontend (JavaScript).
• Clé Secrète (kdvs_...): À utiliser uniquement sur votre serveur. Ne l'exposez jamais côté client.
• Secret Webhook: Utilisé pour vérifier l'authenticité des webhooks reçus sur votre serveur.

Pour les appels API serveur-à-serveur, incluez votre clé secrète dans le header `Authorization` :

Authorization: Bearer VOTRE_CLE_SECRETE

💻 Créer un paiement

La méthode la plus simple pour accepter un paiement est d'utiliser notre SDK JavaScript. Intégrez le script sur votre page, puis appelez la fonction `KadevPay.checkout`.

Installation du SDK

<script src="https://pay.kadev.ci/js/v1/kadev-pay.js"></script>

Exemple d'appel

Associez cette fonction au clic sur votre bouton de paiement. Fournissez une `callback_url` pour rediriger le client après un paiement réussi.

// Remplacez par votre propre clé publique Kadev Pay
const KADEV_PUBLIC_KEY = "kdvp_test_XXXXXXXXXXXXXXXXXXXXX";

function payerAvecKadev() {
    KadevPay.checkout({
        public_key: KADEV_PUBLIC_KEY,
        amount: 5000,                          // Montant de base de l'article (ex: 5000 FCFA)
        email: "client@email.com",             // Email du client (obligatoire)
        name: "Jean Dupont",                   // Nom du client (Optionnel)
        phone: "0102030405",                   // Numéro de téléphone (Optionnel)
        
        // ⚠️ IMPORTANT : Spécifiez la méthode pour un calcul exact des frais
        // 'momo' (2.3% de frais) ou 'card' (4.5% de frais)
        method: "momo",                        
        
        // 🔗 URL de redirection immédiate après succès (Recommandé)
        callback_url: "https://votre-boutique.ci/commande-reussie", 
        
        // Données supplémentaires à récupérer dans votre Webhook
        metadata: {
            cart_id: "CMD-9982",
            custom_field: "valeur"
        },
        
        // Exécuté uniquement si aucune callback_url n'est fournie
        onSuccess: function(response) {
            console.log("Paiement validé ! Référence : ", response.reference);
        },
        
        // Exécuté si le client ferme la fenêtre sans payer
        onClose: function() {
            console.log("Le client a abandonné le paiement.");
        }
    });
}

🔍 Vérifier un paiement

Bien que le webhook soit la méthode de confirmation recommandée, vous pouvez vérifier manuellement le statut d'une transaction via notre API. Cet appel doit être fait depuis votre serveur.

curl -X GET "https://pay.kadev.ci/api/v1/transactions/verify/KDV-1775413916000" \
-H "Authorization: Bearer kdvs_test_VOTRE_CLE_SECRETE"

🛡️ Webhooks

Les webhooks sont le moyen le plus fiable de confirmer un paiement. Configurez une URL sur votre serveur depuis le Dashboard, et nous y enverrons une requête POST sécurisée pour chaque événement, comme `payment.success`.

Vérification de la Signature

Pour garantir que le webhook provient bien de Kadev Pay, chaque requête est signée. Vérifiez cette signature en utilisant votre "Secret Webhook".

<?php
// 1. Récupérez votre Secret Webhook dans le Dashboard Kadev Pay
$webhook_secret = "VOTRE_SECRET_WEBHOOK"; 

$signature = $_SERVER['HTTP_X_KADEVPAY_SIGNATURE'] ?? '';
$payload = file_get_contents('php://input');
$computed_signature = hash_hmac('sha512', $payload, $webhook_secret);

if (hash_equals($computed_signature, $signature)) {
    $event = json_decode($payload, true);
    
    // On vérifie que Kadev Pay nous dit bien que c'est "paid"
    if ($event['event'] === 'payment.success' && $event['data']['status'] === 'paid') {
        $reference = $event['data']['reference'];
        $amount_paid = $event['data']['amount'];
        
        // --- Tout est bon, on valide la commande chez nous ! ---
        // my_custom_db_update_order($reference, 'payé');
        
        http_response_code(200);
        echo "Webhook traité avec succès.";
    }
} else {
    http_response_code(401);
    echo "Signature invalide.";
}
?>

🔌 Plugins & CMS

Intégrez Kadev Pay sans une ligne de code sur les plateformes les plus populaires.

⚠️ Codes d'Erreur API

Notre API utilise les codes de réponse HTTP standards pour indiquer le succès ou l'échec d'une requête.

🧪 Sandbox & Test

Toutes les fonctionnalités de l'API sont disponibles en mode test. Utilisez vos clés API de test (commençant par `kdvp_test_` et `kdvs_test_`) pour effectuer des transactions fictives sans aucun coût.