SDK JavaScript & Intégration HTML

Le SDK JavaScript AlphaPay V2 vous permet d’intégrer une expérience de paiement moderne et sécurisée sur n’importe quel site web (HTML statique, WordPress/PHP, React, Vue, Laravel, etc.) sans redirection externe. Le formulaire de paiement s’ouvre sous forme d’overlay modal réactif au-dessus de votre page, permettant au client de sélectionner son opérateur mobile money (Wave, MTN, Orange, Moov) ou sa carte bancaire et de valider son paiement en toute sécurité.

1. Importer le SDK

Ajoutez la balise <script> suivante dans la balise <head> ou juste avant la fermeture de </body> de votre page HTML :

<script src="https://checkout.alphapay.me/sdk.js"></script>

Une fois chargé, le SDK expose l’objet global AlphaPayButton (ainsi que les alias AlphaPay et alphapay).

2. Modes d’intégration

Vous disposez de 3 méthodes simples selon l’architecture de votre page.

1. Conteneur automatique (Recommandé)
2. Bouton existant personnalisé
3. Déclenchement direct en JavaScript

Cette méthode génère automatiquement un bouton AlphaPay stylisé à l’intérieur du conteneur HTML de votre choix.

<!-- Conteneur cible -->
<div id="alphapay-container"></div>

<script>
  AlphaPayButton.init("alphapay-container", {
    amount: 15000,
    currency: "XOF",
    token: "pk_live_xxxxxxxxxxxxxxxx", // Ou votre clé API sk_live_...
    description: "Achat Pack Premium",
    customer_name: "Awa Sossou",
    customer_email: "awa@example.com",
    callback: function(response) {
      console.log("Paiement réussi !", response);
      window.location.href = "/merci?ref=" + response.reference;
    },
    error_callback: function(error) {
      console.error("Erreur de paiement :", error);
    },
    on_close: function() {
      console.log("Le client a fermé la fenêtre de paiement");
    }
  });
</script>

Si vous avez déjà votre propre bouton HTML avec votre propre design CSS, le SDK s’y rattache facilement.

<!-- Votre propre bouton stylisé -->
<button id="mon-bouton-payer" class="btn btn-primary">
  Payer 15 000 XOF
</button>

<script>
  AlphaPayButton.init(null, {
    amount: 15000,
    currency: "XOF",
    token: "pk_live_xxxxxxxxxxxxxxxx",
    custom_button: true,
    id_custom_button: "mon-bouton-payer",
    description: "Facture #1042",
    callback: function(response) {
      alert("Paiement validé avec succès !");
    }
  });
</script>

Idéal pour déclencher le paiement après avoir validé un panier ou un formulaire en JavaScript.

<button onclick="lancerPaiement()">Commander</button>

<script>
  function lancerPaiement() {
    AlphaPay.checkout({
      amount: 25000,
      currency: "XOF",
      token: "pk_live_xxxxxxxxxxxxxxxx",
      description: "Commande #9021",
      customer_name: "Jean Dupont",
      customer_email: "jean@example.com",
      custom_id: "CMD-9021",
      callback: function(response) {
        console.log("Succès :", response);
      }
    });
  }
</script>

3. Options de configuration

L’objet d’options passé à init ou checkout supporte les propriétés suivantes :

Propriété	Type	Requis	Description
`amount`	`Number`	Oui	Montant à payer (ex: `15000` pour 15 000 XOF).
`token`	`String`	Oui	Votre clé API AlphaPay (`pk_live_...` ou `sk_live_...`).
`currency`	`String`	Non	Code devise ISO (défaut : `"XOF"`). Supporte `XOF`, `EUR`, `USD`, `XAF`, `GNF`.
`description`	`String`	Non	Motif ou description de l’achat affiché sur l’interface de paiement.
`customer_name`	`String`	Non	Nom complet du client. Si renseigné avec l’email, évite à l’utilisateur de devoir les saisir à nouveau.
`customer_email`	`String`	Non	Adresse email du client pour l’envoi de son reçu de paiement.
`custom_id`	`String`	Non	Votre référence interne de commande. Transmise dans les métadonnées de la transaction et des webhooks.
`callback`	`Function`	Non	Fonction exécutée avec succès après confirmation du paiement : `callback(response)`.
`error_callback`	`Function`	Non	Fonction appelée en cas d’échec ou d’erreur : `error_callback(error)`.
`on_close`	`Function`	Non	Fonction appelée lorsque le client clique sur la croix de fermeture sans payer.
`custom_button`	`Boolean`	Non	Mettre à `true` pour relier le SDK à un bouton existant de votre page.
`id_custom_button`	`String`	Non	ID HTML du bouton personnalisé (requis si `custom_button: true`).

4. Exemple HTML complet prêt à l’emploi

Voici un fichier HTML autonome (index.html) que vous pouvez enregistrer et tester directement dans votre navigateur :

<!DOCTYPE html>
<html lang="fr">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Exemple Intégration AlphaPay</title>
  
  <!-- 1. Chargement du SDK AlphaPay -->
  <script src="https://checkout.alphapay.me/sdk.js"></script>

  <style>
    body {
      font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      background-color: #f8fafc;
      color: #0f172a;
      display: flex;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      margin: 0;
      padding: 20px;
    }
    .card {
      background: white;
      border-radius: 16px;
      padding: 32px;
      max-width: 440px;
      width: 100%;
      box-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.05), 0 8px 10px -6px rgba(0, 0, 0, 0.05);
      border: 1px border #e2e8f0;
    }
    h2 {
      margin-top: 0;
      font-size: 20px;
      color: #0f172a;
    }
    .price-tag {
      font-size: 28px;
      font-weight: 800;
      color: #2563eb;
      margin: 16px 0 24px;
    }
    .status-box {
      margin-top: 20px;
      padding: 12px;
      border-radius: 8px;
      font-size: 14px;
      display: none;
    }
    .status-success {
      background-color: #ecfdf5;
      color: #065f46;
      border: 1px solid #a7f3d0;
    }
  </style>
</head>
<body>

  <div class="card">
    <h2>Abonnement Formation Pro</h2>
    <p>Accès complet à la plateforme et au support pendant 1 an.</p>
    <div class="price-tag">15 000 XOF</div>

    <!-- Emplacement où le SDK insère le bouton -->
    <div id="mon-bouton-alphapay"></div>

    <div id="message-statut" class="status-box"></div>
  </div>

  <script>
    // Initialisation du SDK
    AlphaPayButton.init("mon-bouton-alphapay", {
      amount: 15000,
      currency: "XOF",
      token: "pk_live_xxxxxxxxxxxxxxxx", // Remplacez par votre clé API
      description: "Formation Pro 1 An",
      customer_name: "Koffi Mensah",
      customer_email: "koffi@example.com",
      custom_id: "COMMANDE_9482",
      callback: function(res) {
        var box = document.getElementById("message-statut");
        box.className = "status-box status-success";
        box.style.display = "block";
        box.innerHTML = "✅ <strong>Paiement validé !</strong><br>Référence : " + (res.reference || "Confirmée");
      },
      error_callback: function(err) {
        alert("Erreur lors de l'opération : " + JSON.stringify(err));
      }
    });
  </script>

</body>
</html>

5. Sécurité et Bonnes Pratiques

Important : Ne validez jamais la livraison d’un produit uniquement sur le callback JavaScript côté navigateur.

Un utilisateur averti peut techniquement modifier le code exécuté dans son navigateur. Pour sécuriser votre intégration de bout en bout :

Activez les Webhooks : Configurez votre endpoint de webhook sur votre tableau de bord marchand AlphaPay sous Développeur > Webhooks.
Vérifiez la signature : Assurez-vous que chaque notification reçue sur votre serveur provient bien d’AlphaPay via le header X-AlphaPay-Signature.
Vérification API de secours : Vous pouvez également appeler notre endpoint de vérification côté serveur :
GET https://api.alphapay.me/api/v1/payments/{id}/verify/
avant de débloquer l’accès aux services payants.

Prise en main

SDKs & Intégration

SDK JavaScript & Intégration HTML

1. Importer le SDK

2. Modes d’intégration

3. Options de configuration

4. Exemple HTML complet prêt à l’emploi

5. Sécurité et Bonnes Pratiques

​1. Importer le SDK

​2. Modes d’intégration

​3. Options de configuration

​4. Exemple HTML complet prêt à l’emploi

​5. Sécurité et Bonnes Pratiques

1. Importer le SDK

2. Modes d’intégration

3. Options de configuration

4. Exemple HTML complet prêt à l’emploi

5. Sécurité et Bonnes Pratiques