Skip to main content

AdjeminPay JS SDK

Le seamless javascript vous permet d'intégrer le paiement en ligne via mobile money dans votre site

L'intégration de ce SDK se fait en trois étapes :

Etape 1 : Avoir un compte et une application sur AdjeminPay#

Avant d'intégrer le seamless vous devez d'abord vous inscrire et créer une application sur AdjeminPay.

Etape 2 : Page de paiement#

La page de paiement est la page où vous envoyez les clients de votre site pour finaliser leur commande A cette étape vous devez avoir déjà généré une reference pour la transaction

Ajouter le lien du sdk et de jquery:

<script src="https://api.adjeminpay.net/release/seamless/latest/adjeminpay.min.js" type="text/javascript"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.js"></script>

Etape 2.1 : Informations sur votre transaction#

Pour faire une transaction avec AdjeminPay vous devez definir les champs suivant :

  • amount : Montant du paiement
  • currency : Devise du paiement
  • transaction_id : Référence de la transaction
  • designation : Designation du paiement
  • notify_url : uri de notification ou vous recevrez les informations après le paiement

Exemple :

<div id="result">
<h1 id="result-title"></h1>
<p id="result-message"></p>
<p id="result-status"></p>
</div>
<form id="paiement">
<input type="hidden" id="amount" value="25000">
<input type="hidden" id="currency" value="CFA">
<input type="hidden" id="adp_signature" >
<input type="hidden" id="transaction_id" value="nkHgzAivULfVzvvEkbMsEI7ZjOlRxl9G">
<input type="hidden" id="designation" value="Paire de basket Air Force">
<button type="submit" id="payBtn">Payer avec AdjeminPay</button>
</form>

NB : Veuillez générer votre transaction_id dynamiquement et enregistré votre transaction dans votre base de donnée

Etape 2.2 : Lier le formulaire au SDK Javascript#

Cliquez sur "Payer" pour commencer, le paiement sera préparé par AdjeminPay et la page de paiement sera générée et affichée.

L'exemple suivant vous montre comment initialiser et lancer le paiement :

<script>
var AdjeminPay = AdjeminPay();
AdjeminPay.on('init', function (e) {
// retourne une erreur au cas où votre CLIENT_ID ou CLIENT_SECRET est incorrecte
signature = e;
$("#adp_signature").val(signature);
});
// Lance une requete ajax pour vérifier votre API_KEY et APPLICATION_ID et initie le paiement
AdjeminPay.init({
client_id : 'VOTRE_CLIENT_ID',
client_secret : "VOTRE_CLIENT_SECRET",
transaction_id : $('#transaction_id').val(),
designation : $('#designation').val(),
amount : parseInt($('#amount').val()),
});
// Ecoute le feedback sur les erreurs
AdjeminPay.on('error', function (e) {
// la fonction que vous définirez ici sera exécutée en cas d'erreur
console.log(e);
$("#result-title").html(e.title);
$("#result-message").html(e.message);
$("#result-status").html(e.status);
});
// Lancer la procédure de paiement au click
$('#payBtn').on('click', function () {
// Vérifie vos informations et prépare le paiement
// S'il y a une erreur à cette étape, AdjeminPay.on('error') sera exécuté
AdjeminPay.preparePayment({
amount: parseInt($('#amount').val()),
transaction_id: $('#transaction_id').val(),
currency: $('#currency').val(),
designation: $('#designation').val(),
custom: $('#custom_field').val(),
notify_url: 'https://webhook.site/427ed2b8-db3e-4ac6-be64-9ecb5b68e420',
signature : $('#adp_signature').val(),
return_url :'https://application.example.com/return',
cancel_url : 'https://application.example.com/cancel'
// le notify_url est TRES IMPORTANT
// c'est lui qui permettra de notifier votre backend
});
// Si l'étape précédante n'a pas d'erreur,
// cette ligne génère et affiche l'interface de paiement AdjeminPay
AdjeminPay.renderPaymentView();
});
</script>

Etape 3 : Réagir aux évènements et exécuter des callbacks lors de l'exécution de votre transaction#

Lorsque la page de paiement est générée, AdjeminPay vous permet de suivre toutes les étapes du paiement via des évènements. Ces évènements retournent des données sous forme d'objet que vous pouvez utiliser dans vos callbacks

  • error : Une ou plusieurs erreurs se sont produites :
    • soit dans la vérification de vos données de paiement, notamment transaction_id, client_id et client_secret
    • soit dans les requetes sur notre serveur Un message d'erreur s'affiche et le paiement est stoppé
AdjeminPay.on('error', function(errorData)){
console.log(errorData.error);
console.log(errorData.message);
}

Les évènements suivants retournent un objet qui contient les informations de la transaction (title, status, message)

  • paymentPending : Le paiement est en attente (le client a ouvert l'interface de paiement)
  • paymentTerminated : Le paiement est terminé, le status est soit validé ou échoué ou annulé
  • paymentSuccessful : Le paiement est réussi, le client a payé et l'interface de paiement s'est fermée
  • paymentFailed : Le paiement a échoué :
    • soit le solde du client n'est pas suffisant
    • soit le code otp n'est pas correct
    • soit le client n'a pas confirmé le paiement
    • soit une erreur au niveau de l'opérateur s'est produite NB : ces détails sont disponiblent dans le callback des evenements
  • paymentCancelled : Le paiement a été annulé : le client a cliqué sur le bouton 'Annuler'

Exemple :

// Payment en attente
AdjeminPay.on('paymentPending', function (e) {
console.log('<<<<<<< pending !');
console.log('>>>>>>> Paiement en attente !');
console.log(e.title);
console.log(e.status);
console.log(e.message);
// ATTENDRE
});
// Payment terminé
AdjeminPay.on('paymentTerminated', function (e) {
console.log('<<<<<<< terminated !');
console.log('>>>>>>> Paiement terminé !');
console.log(e.title);
console.log(e.status);
console.log(e.message);
// EXECUTER UN CALLBACK
});
// Payment réussi
AdjeminPay.on('paymentSuccessful', function (e) {
console.log('<<<<<<< Successful !');
console.log('>>>>>>> Paiement réussi !');
console.log(e.title);
console.log(e.status);
console.log(e.message);
// ACTION redirection, popup de félicitation etc
});
// Payment échoué
AdjeminPay.on('paymentFailed', function (e) {
console.log('<<<<<<< Echec !');
console.log('>>>>>>> Paiement echoué !');
console.log(e.message)
// ACTION redirection etc
});
// Payment annulé
AdjeminPay.on('paymentCancelled', function (e) {
console.log('<<<<<<< Echec !');
console.log('>>>>>>> Paiement annulé !');
console.log(e.title);
console.log(e.status);
console.log(e.message);
// ACTION
});

Etape 4 : Capter la notification de paiement dans votre backend#

Vous souvenez-vous du paramètre notify_url ou notification_url VOTRE URL DE NOTIFICATION ?

Vous devez maintenant l'implémenter dans votre backend pour être notifié de l'évolution du paiement et mettre à jour votre base de données

Lorsque vous initier une transaction vous fournissez une URL de notification à laquelle nous vous notifions du résultat de la transaction afin de vous permettre d'avoir les détails de la transaction.

AdjeminPay fait une requete HTTP à votre VOTRE URL DE NOTIFICATION avec la méthode POST et les paramètres suivant en BODY:

Le Content-Type de la requête est application/x-www-form-urlencoded

  • transaction_id : la référence de la transaction fournit par le marchand (vous)
  • status : le status du paiement
  • amount : le montant de la transaction
  • phone_number : le numéro de téléphone fourni par l'utilisateur qui fait le paiement
  • buyer_name : le nom de l'utilisateur
  • buyer_reference : le numéro de téléphone ou la référence fourni par l'utilisateur qui fait le paiement
  • currency_code : la devise
  • cancelled_at : si la transaction est annulée, la date à laquelle la transaction est annulée
  • approuved_at : si la transaction est approuvée, la date à laquelle la transaction est approuvée
  • transaction_type : le moyen de paiement utilisé ORANGE_CI ou MTN_CI

Code PHP#

Exemple de gestion des notifications provenant de AdjeminPay

hook.php
<?php
public function notifyAdjeminPay(Request $request)
{
$input = $request->all();
$transaction_reference = $input['transaction_id'];
$status = $input['status'];
if(empty($transaction_reference)){
return response()->json([
'error' => [
'message' => "Transaction not found",
'transaction_reference' => $transaction_reference
],
]);
}
// Recuperation de la ligne de la transaction dans votre base de données
$transaction = InvoicePayment::where(['payment_reference' => $transaction_reference])->first();
if(empty($transaction)){
return response()->json([
'error' => [
'message' => "Transaction not found",
'transaction_reference' => $transaction_reference
],
]);
}
$invoice = Invoice::where(["id" => $transaction->invoice_id])->first();
$responseData = null;
if($invoice->status == 'UNPAID'){
if ($transaction != null) {
switch ($status) {
case 'SUCCESSFUL' :
$transaction->status = 'SUCCESSFUL';
$transaction->is_waiting = false;
$transaction->is_completed = true;
$transaction->save();
$this->validateTransaction($transaction_reference);
break;
case 'FAILED' :
$transaction->status = 'FAILED';
$transaction->is_waiting = false;
$transaction->is_completed = true;
$transaction->save();
$this->cancelTransaction($transaction_reference);
break;
case 'CANCELLED' :
$transaction->status = 'CANCELLED';
$transaction->is_waiting = false;
$transaction->is_completed = true;
$transaction->save();
$this->cancelTransaction($transaction_reference);
break;
case 'EXPIRED' :
$transaction->status = 'EXPIRED';
$transaction->is_waiting = false;
$transaction->is_completed = true;
$transaction->save();
break;
default:
return response()->json([
'error' => [
'message' => 'MISSING_TRANSACTION_STATUS'
],
]);
break;
}
}
}
?>