Documentation API TalyPay

Authentification

L'API TalyPay utilise des clés API pour authentifier les requêtes. Vous pouvez gérer vos clés API depuis votre tableau de bord.

Authentification des requêtes API

Incluez votre clé secrète dans le header Authorization :

curl https://api.talypay-me.com/v1/payments \
  -H "Authorization: Bearer tk_live_your_secret_key" \
  -H "Content-Type: application/json"

Environnements

TalyPay propose deux environnements pour faciliter le développement et les tests.

API Paiements

{
  "response_code": 201,
    "status": "created",
    "message": "The payment has been init successfully. Please check its status",
    "payment_ref": "c7dfi3j1-2i52-0289"
  }
}

 curl --location 'https://api.talypay-me.com/api/v1/check-payment-status' \
--header 'Request-Environment: production' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer tk_live_USFHpBGl9o3DoxYL0Mki4SmKINroIEqF8XMz7TyoMUGIuf2MAXUfntm71KsIu8dS' \
--data '{
    "payment_mode" : "mtn_momo",
    "country" : "Benin",
    "payment_ref" : "c649b648-7314-94ed"
}'
                                
                                

{
    "response_code": 200,
    "status": "successful",
    "message": "Transaction proceed successfully."
  }

API Disbursements

L'API Disbursement permet d'effectuer des remboursements et des transferts d'argent vers des comptes Mobile Money. Cette API supporte deux types d'opérations : Refund (remboursement d'un paiement existant) et Withdrawal/Transfer (transfert vers un bénéficiaire).

curl --location 'https://www.talypay-me.com/api/v1/init-disbursement' \\
--header 'Authorization: Bearer tk_live_your_token' \\
--header 'Request-Environment: sandbox' \\
--header 'Content-Type: application/json' \\
--data '{
    "payment_mode": "mtn_momo",
    "disbursement_type": "refund",
    "payment_ref": "7b90507a-627b-0497",
    "amount": 100,
    "description": "Remboursement pour produit défectueux"
}'

{
    "status": "success",
    "message": "Disbursement initiated successfully",
    "disbursement_ref": "REFUND-1737202847-4567",
    "data": {
        "amount": 100,
        "currency": "XOF",
        "type": "refund",
        "state": "pending"
    }
}

curl --location 'https://www.talypay-me.com/api/v1/init-disbursement' \\
--header 'Authorization: Bearer tk_live_your_token' \\
--header 'Request-Environment: sandbox' \\
--header 'Content-Type: application/json' \\
--data '{
    "payment_mode": "mtn_momo",
    "disbursement_type": "withdrawal",
    "country": "benin",
    "customer_firstname": "Jean",
    "customer_name": "Dupont",
    "customer_tel": "+22997123456",
    "customer_email": "jean.dupont@example.com",
    "amount": 5000,
    "disbursement_ref": "TRANS-2024-001",
    "description": "Paiement pour service rendu"
}'

{
    "status": "success",
    "message": "Disbursement initiated successfully",
    "disbursement_ref": "TRANSFER-1737202847-8912",
    "data": {
        "amount": 5000,
        "currency": "XOF",
        "type": "withdrawal",
        "state": "pending"
    }
}

curl --location 'https://www.talypay-me.com/api/v1/check-disbursement-status' \\
--header 'Authorization: Bearer tk_live_your_token' \\
--header 'Request-Environment: sandbox' \\
--header 'Content-Type: application/json' \\
--data '{
    "disbursement_ref": "REFUND-1737202847-4567"
}'

{
    "status": "success",
    "disbursement_ref": "REFUND-1737202847-4567",
    "transaction_state": "successful",
    "data": {
        "amount": 100,
        "currency": "XOF",
        "type": "refund",
        "customer_tel": "+22997123456",
        "description": "Remboursement pour produit défectueux",
        "initiated_at": "2024-01-18 10:30:45",
        "completed_at": "2024-01-18 10:31:12"
    }
}

curl --location 'https://www.talypay-me.com/api/v1/get-available-balance' \\
--header 'Authorization: Bearer tk_live_your_token' \\
--header 'Request-Environment: sandbox' \\
--header 'Content-Type: application/json' \\
--data '{}'

{
    "status": "success",
    "available_balance": 15000,
    "currency": "XOF",
    "details": {
        "total_received": 50000,
        "total_withdrawals": 30000,
        "total_disbursements": 5000
    }
}

Webhooks (En cours de développement)

Les webhooks vous permettent de recevoir des notifications en temps réel sur les événements de votre compte.

Configuration

Configurez vos URLs de webhook dans votre tableau de bord :

1. Accédez à Paramètres → Webhooks
2. Cliquez sur "Ajouter un webhook"
3. Entrez votre URL de endpoint
4. Sélectionnez les événements à écouter
5. Sauvegardez et récupérez votre secret de signature

Exemple de payload

{
  En cours de développement
}

JavaScript Widget

Le widget TalyPay est la solution la plus simple pour intégrer les paiements sur votre site web. Il suffit d'inclure un script et d'ajouter une balise personnalisée pour créer un bouton de paiement complet.

Installation

<script src="https://talypay-me.com/cdn-talypay/talypay.min.js"></script>

<talypay-widget
  label="Faire un paiement"
  amount="1000"
  key="votre_cle_api_publique"
  callback=""
  sandbox="false"
  color="#0044cc"
  description="Paiement de la commande #12345"
  api-url="https://talypay-me.com"
>
</talypay-widget>

Paramètres du Widget

Exemple complet

<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Paiement TalyPay</title>
    <!-- Inclure le script TalyPay -->
    <script src="https://talypay-me.com/cdn-talypay/talypay.min.js"></script>
</head>
<body>
    <div class="container">
        <h1>Faire un don</h1>
        <p>Soutenez notre cause avec un don sécurisé</p>
        
        <!-- Widget TalyPay -->
        <talypay-widget
          label="Faire un don de 1000 FCFA"
          amount="1000"
          key="G0mfRWqGTrKscbpnUiksFbpHj1gwmjuDNuhA1nhGMgstL3eaAGrVFBTlCbO1k1eFybpTK2Ixv9tQykQigroDKL2wMg8l5e9M1Oo9b57pPY6X9muUl4e"
          callback="https://monsite.com/merci"
          sandbox="false"
          color="#0044cc"
          description="Don pour SOS Enfants"
          api-url="https://talypay-me.com"
        >
        </talypay-widget>
    </div>
</body>
</html>

JavaScript SDK v1.1.0

Le SDK JavaScript TalyPay offre une API programmatique complète avec vérification automatique du statut, gestion des callbacks, et support des modes sandbox/production.

Installation

<script src="https://www.talypay-me.com/js-sdk/talypay-sdk.js"></script>

Initialisation

// Initialisation basique
const talypay = new TalyPay('tk_live_votre_cle_api_publique');

// Initialisation avec callbacks et options
const talypay = new TalyPay('tk_live_votre_cle_api', {
    sandbox: false,                    // true pour test, false pour production
    maxStatusCheckAttempts: 60,        // Nombre max de vérifications (défaut: 60)
    
    // Callback appelé quand le paiement est confirmé
    onSuccess: (response) => {
        console.log('✅ Paiement réussi!', response);
        alert(`Paiement confirmé! Réf: ${response.payment_ref}`);
        // Rediriger l'utilisateur, mettre à jour l'UI, etc.
    },
    
    // Callback appelé en cas d'erreur
    onError: (error, details) => {
        console.error('❌ Erreur:', error.message);
        alert('Erreur: ' + error.message);
        // Afficher un message d'erreur à l'utilisateur
    },
    
    // Callback appelé pendant la vérification
    onPending: (data) => {
        console.log(`⏳ Vérification ${data.attempt}/${data.max_attempts}`);
        // Mettre à jour un indicateur de progression
    }
});

Initier un paiement

// Initier un paiement avec vérification automatique
talypay.initPayment({
    payment_mode: 'mtn_momo',           // 'mtn_momo', 'moov_money', 'celtiis_money', 'card'
    customer_name: 'AKOSSOU',
    customer_firstname: 'Francinne',    // Optionnel
    customer_email: 'francinne@example.com',
    customer_tel: '229019000000',       // Format international
    amount: 1000,                       // Montant en FCFA (minimum: 100)
    currency: 'XOF',                    // Devise (défaut: XOF)
    country: 'benin',                   // Pays (défaut: benin)
    payment_ref: 'ORDER-' + Date.now(), // Référence unique (auto-généré si non fourni)
    description: 'Paiement de la commande #12345',
    callback_url: '',                   // URL de callback (optionnel)
    metadata: {}                        // Métadonnées (optionnel)
}, true)  // true = vérification automatique activée
.then(response => {
    console.log('Paiement initié:', response);
    // La vérification automatique se lance
    // Les callbacks onSuccess/onError seront appelés automatiquement
})
.catch(error => {
    console.error('Erreur:', error.message);
});

Exemple complet avec formulaire

<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <title>Paiement TalyPay</title>
    <script src="https://www.talypay-me.com/js-sdk/talypay-sdk.js"></script>
</head>
<body>
    <h1>Paiement avec TalyPay</h1>
    <div id="alert" class="alert hidden"></div>
    
    <form id="payment-form">
        <select id="payment_mode" required>
            <option value="mtn_momo">MTN Mobile Money</option>
        </select>
        <input type="text" id="name" placeholder="Nom" required>
        <input type="email" id="email" placeholder="Email" required>
        <input type="tel" id="phone" placeholder="229019000000" required>
        <input type="number" id="amount" placeholder="1000" min="100" required>
        <button type="submit" id="submitBtn">Payer maintenant</button>
    </form>

    <script>
        // Initialiser TalyPay avec callbacks
        const talypay = new TalyPay('tk_live_votre_cle_api', {
            sandbox: false,
            onSuccess: (response) => {
                alert(`✅ Paiement confirmé! Réf: ${response.payment_ref}`);
                document.getElementById('payment-form').reset();
            },
            onError: (error) => {
                alert('❌ ' + error.message);
            },
            onPending: (data) => {
                console.log(`Vérification ${data.attempt}/${data.max_attempts}`);
            }
        });

        // Gérer la soumission
        document.getElementById('payment-form').addEventListener('submit', async (e) => {
            e.preventDefault();
            
            try {
                await talypay.initPayment({
                    payment_mode: document.getElementById('payment_mode').value,
                    customer_name: document.getElementById('name').value,
                    customer_firstname: '',
                    customer_email: document.getElementById('email').value,
                    customer_tel: document.getElementById('phone').value,
                    amount: parseInt(document.getElementById('amount').value),
                    currency: 'XOF',
                    country: 'benin',
                    payment_ref: 'ORDER-' + Date.now(),
                    description: 'Paiement en ligne'
                }, true);
            } catch (error) {
                alert('Erreur: ' + error.message);
            }
        });
    </script>
</body>
</html>

Plugin WordPress / WooCommerce

Installez TalyPay sur votre boutique WordPress/WooCommerce en quelques clics.

Installation

1. Téléchargez le plugin depuis talypay-me.com/downloads
2. Allez dans WordPress → Extensions → Ajouter
3. Cliquez sur "Téléverser une extension"
4. Sélectionnez le fichier ZIP et installez
5. Activez le plugin
6. Configurez vos clés API dans WooCommerce → Réglages → Paiements → TalyPay