PHP

Bienvenue dans la documentation officielle du SDK PHP de Yabetoo ! Ce SDK vous permet d’intégrer facilement le système de paiement sécurisé de Yabetoo dans vos applications PHP. Que vous souhaitiez accepter des paiements en ligne, gérer des sessions de paiement ou consulter les transactions effectuées, ce SDK vous fournit une interface simple et intuitive pour interagir avec l’API de Yabetoo.

Yabetoo simplifie l’intégration des paiements en ligne pour les développeurs. Ce SDK PHP est conçu pour être aussi flexible et facile à utiliser que possible, vous permettant de vous concentrer sur la croissance de votre entreprise sans vous soucier des détails complexes de la gestion des paiements. Que vous soyez en mode de test ou en production, Yabetoo prend en charge toutes les étapes du processus de paiement.

Le SDK Yabetoo PHP vous permet de :

Créer et gérer des paiements.
Créer et configurer des sessions de paiement.
Utiliser différents environnements (test et production) en fonction de la clé API.
Gérer les paiements en plusieurs devises.

Installation

Prérequis

PHP 7.4+ : Le SDK est compatible avec PHP 7.4 ou une version supérieure.
Composer : Le gestionnaire de dépendances PHP.

Installation via Composer

Pour installer le SDK, utilisez Composer. Exécutez la commande suivante dans votre projet

composer require yabetoo/yabetoo-php

Si vous rencontrez une erreur liée à la stabilité des versions, vous pouvez ajouter cette option dans votre fichier composer.json

{
    "minimum-stability": "dev",
    "prefer-stable": true
}

Configuration

Initialisation du SDK

Avant d’utiliser le SDK, vous devez initialiser une instance de la classe Yabetoo. Fournissez simplement votre clé API lors de l’initialisation. Le SDK détecte automatiquement si vous êtes en mode test ou en production.

require 'vendor/autoload.php';

use Yabetoo\Yabetoo;

$yabetoo = new Yabetoo('sk_test_XXXXXXXXXXXXXXXXXXXXXXXX'); // Utilisez votre clé API

Gestion des paiements avec Yabetoo

Vous pouvez créer des paiements, récupérer des informations sur des paiements spécifiques et gérer les paiements en utilisant la classe Payment.

Yabetoo fonctionne sur un modèle de paiements en deux étapes. Cela signifie que, pour traiter un paiement, vous devez d’abord créer une intention de paiement et ensuite confirmer cette intention pour capturer le montant.

Cette approche offre une flexibilité accrue, permettant par exemple de vérifier les fonds disponibles ou d’obtenir l’autorisation d’un utilisateur avant de finaliser une transaction. Voici comment cela fonctionne étape par étape :

Créer une intention de paiement

Une intention de paiement est une ressource qui représente votre souhait de recevoir un paiement pour un montant spécifique. Lorsque vous créez une intention de paiement, vous ne capturez pas immédiatement le montant ; c’est une étape préparatoire.

Voici un exemple de création d’une intentien de paiement avec le SDK

use Yabetoo\Yabetoo;


$payment = $yabetoo->payments->create([
    'amount' => 5000,
    'currency' => 'xaf',
    'description' => 'Achat de services Yabetoo',
]);

print_r($payment);

Ce code crée une intention de paiement pour un montant de 5000 XAF. La réponse de l’API contient un identifiant unique (id) de l’intention de paiement que vous utiliserez lors de la confirmation.

Confirmer une intention de paiement

Après avoir créé l’intention de paiement, vous devez la confirmer pour capturer le montant. Cela se produit généralement lorsque l’utilisateur final a terminé toutes les étapes nécessaires (comme fournir des informations de paiement ou accepter les conditions générales).

Voici comment confirmer une intention de paiement :

use Yabetoo\Yabetoo;

$paymentConfirmation = $yabetoo->payments->confirm($payment['id'], [
    "client_secret" => $payment['clientSecret'],
    "first_name" => "Loumbou",
    "last_name" => "Scoty",
    "email" => "scott@artkodes.com",
    "payment_method_data" => [
        "type" => "momo",
        "momo" => [
            "country" => "cg",
            "msisdn" => "242123456789",
            "operator_name" => "mtn"
        ],
    ],
]);

print_r($paymentConfirmation);

En appelant cette méthode, le montant associé à l’intention de paiement sera capturé, et le paiement sera considéré comme réussi si tout se passe bien.

Avec ce modèle en deux étapes, les développeurs peuvent avoir une meilleure maîtrise du processus de paiement tout en offrant une expérience utilisateur fluide. Vous pouvez adapter ces deux étapes à vos besoins spécifiques (par exemple, pré-autorisation ou paiement différé).

Gestion des erreurs lors de la confirmation

Il est important de gérer les erreurs, car la confirmation d’une intention de paiement peut échouer pour diverses raisons (insuffisance de fonds, informations de paiement incorrectes, etc.).

Voici un exemple d’utilisation de la gestion des erreurs lors de la confirmation

try {
    $paymentConfirmation = $yabetoo->payments->confirm($paymentIntent['id'], [...]);
    print_r($paymentConfirmation);
} catch (\Exception $e) {
    echo 'Erreur lors de la confirmation du paiement : ' . $e->getMessage();
}

Récupérer les détails d’un paiement

Pour récupérer les informations sur un paiement existant, utilisez l’ID du paiement comme paramètre

use Yabetoo\Yabetoo;

$response = $yabetoo->payments->retrieve('pi_XXXXXXXXXXXX');
print_r($response);

Récupérer la liste de tous vos paiements

Pour récupérer les informations sur tous les paiements de votre compte Yabetoo

use Yabetoo\Yabetoo;

$response = $yabetoo->payments->list();
print_r($response);

Utilisation d’une session de paiement avec Yabetoo

Avec Yabetoo, vous pouvez créer des sessions de paiement qui permettent à vos utilisateurs de passer par une page de paiement hébergée. Cette page est entièrement gérée et sécurisée par Yabetoo, simplifiant l’intégration des paiements en ligne tout en garantissant la conformité et la sécurité des transactions.

Qu’est-ce qu’une session de paiement ?

Une session de paiement est une instance qui génère une URL unique pointant vers une page de paiement hébergée par Yabetoo. Cette page permet à vos clients de finaliser leur paiement de manière simple et sécurisée, sans que vous ayez besoin de gérer directement les détails sensibles, tels que les informations de carte bancaire ou mobile money.

Avantages d’utiliser une session de paiement

L’utilisation d’une page de paiement hébergée présente plusieurs avantages pour vous en tant que développeur ou marchand.

Sécurité accrue : Vous n’avez pas besoin de collecter ou de stocker les informations de paiement sensibles, car cela est entièrement pris en charge par Yabetoo. Cela réduit votre charge en matière de conformité avec les réglementations.
Rapidité de mise en œuvre : La page de paiement est prête à l’emploi et personnalisable. Vous pouvez l’intégrer avec un minimum d’effort, ce qui vous permet de vous concentrer sur le cœur de votre application.
Mises à jour automatiques : Toute mise à jour de la page (sécurité, UI/UX, compatibilité mobile) est automatiquement gérée par Yabetoo, sans que vous ayez à déployer de modifications côté serveur.
Personnalisation : Bien que la page de paiement soit hébergée, elle peut être personnalisée avec des informations comme les produits, la description de commande, et bien plus, pour offrir une expérience utilisateur cohérente.

Créer une session de paiement

Les sessions de paiement vous permettent de créer un processus de paiement sécurisé et fluide pour vos utilisateurs. Cette session redirige l’utilisateur vers une page de paiement hébergée pour finaliser la transaction.

use Yabetoo\Session;

$response = $yabetoo->sessions->create([
    "total" => 200000, 
    "currency" => "xaf",
    "accountId" => "acct_xxxxxxxx", // ID du compte de l'utilisateur
    "successUrl" => "https://votre-site.com/checkout-success", // URL en cas de succès
    "cancelUrl" => "https://votre-site.com/checkout-cancel",   // URL en cas d'annulation
    "metadata" => ["orderID" => "1234"], // Métadonnées associées à la session
    "items" => [
        [
            "productId" => "prod_12345",
            "quantity" => 1,
            "price" => 200000,
            "productName" => "Écran HD"
        ]
    ]
]);

print_r($response);

Fonctionnement de la session de paiement

Création de la session : Lorsque vous créez une session, vous envoyez les informations sur les articles, le montant total, la devise, et les URLs de redirection (pour succès ou annulation).
Page de paiement hébergée : Yabetoo vous renvoie une URL unique que vous pouvez utiliser pour rediriger vos utilisateurs vers la page de paiement hébergée.
Confirmation du paiement : Une fois le paiement effectué avec succès, l’utilisateur est redirigé vers l’URL que vous avez définie dans successUrl, avec les détails de la transaction. Si l’utilisateur annule, il sera redirigé vers l’URL définie dans cancelUrl.

Exemple de redirection après le paiement

Lorsque le paiement est effectué via la page de paiement hébergée par Yabetoo, vous serez redirigé vers l’URL que vous avez définie dans le champ successUrl. Yabetoo ajoute automatiquement un paramètre dans cette URL : l’ID de paiement. Cet ID de paiement est crucial pour vérifier les détails du paiement et effectuer une double vérification du statut du paiement afin de garantir qu’il a bien été finalisé.

Étape 1 : Récupérer l’ID du paiement depuis l’URL

Lorsque l’utilisateur est redirigé vers votre site après un paiement réussi, l’URL de redirection contiendra un paramètre paymentId. Vous devez récupérer cet ID pour pouvoir obtenir les détails du paiement.

Exemple d’URL de redirection après un paiement réussi

https://votre-site.com/checkout-success?paymentId=pi_1234567890abcdef

Étape 2 : Récupérer les détails du paiement à partir de l’ID

Après avoir récupéré l’ID de paiement, vous devez interroger l’API de Yabetoo pour obtenir les détails complets du paiement. Cela vous permettra de vérifier le statut du paiement et d’obtenir des informations précises sur la transaction.

use Yabetoo\Payment;

$payment = new Payment($yabetoo);

// Récupérer l'ID de paiement depuis l'URL de redirection
if (isset($_GET['paymentId'])) {
    $paymentId = $_GET['paymentId'];

    // Récupérer les détails du paiement
    $paymentDetails = $payment->retrieve($paymentId);

    print_r($paymentDetails);
}

Étape 3 : Effectuer une double vérification du statut du paiement

Pour renforcer la sécurité, il est recommandé de toujours vérifier le statut du paiement directement via l’API de Yabetoo. Cela vous permet de vous assurer que le paiement a bien été capturé avant de procéder à la livraison du service ou produit à l’utilisateur.

Le champ status dans la réponse du paiement peut indiquer plusieurs états, comme succeeded, pending, ou failed. Vous devez vérifier que le statut est bien succeeded avant de finaliser le processus de commande.

if (isset($_GET['paymentId'])) {
    $paymentId = $_GET['paymentId'];

    // Récupérer les détails du paiement
    $paymentDetails = $payment->retrieve($paymentId);

    // Double vérification du statut du paiement
    if ($paymentDetails['status'] === 'succeeded') {
        // Le paiement est confirmé, vous pouvez procéder à la livraison du produit/service
        echo "Paiement réussi. Vous pouvez maintenant traiter la commande.";
    } else {
        // Le paiement n'a pas été finalisé ou a échoué
        echo "Paiement en attente ou échoué. Veuillez vérifier.";
    }
}

Pourquoi effectuer une double vérification ?

Sécurité accrue : La double vérification assure que même si l’utilisateur est redirigé vers votre site, le statut du paiement est confirmé avec l’API avant de traiter la commande.
Prévention des fraudes : Cela aide à éviter les tentatives de fraude où l’utilisateur pourrait essayer de manipuler l’URL de redirection.
Conformité et audit : En ayant une vérification formelle du statut du paiement via l’API, vous conservez une trace fiable des transactions réussies et échouées.

L’étape de redirection après le paiement est cruciale pour la finalisation d’une transaction. En récupérant l’ID de paiement fourni dans l’URL et en effectuant une double vérification avec l’API de Yabetoo, vous renforcez la sécurité de votre processus de commande et vous assurez que seuls les paiements confirmés sont traités.

L’utilisation d’une page de paiement hébergée avec des sessions de paiement simplifie considérablement le processus d’intégration des paiements dans votre application. Elle vous permet de déléguer la gestion des données sensibles à Yabetoo, tout en offrant une expérience de paiement fluide et sécurisée à vos utilisateurs.

Configuration avancée

Le SDK utilise Guzzle pour toutes les requêtes HTTP. Vous pouvez personnaliser les requêtes en passant des options supplémentaires lors de la création du client dans la classe Yabetoo. Par exemple, si vous avez besoin de configurer un proxy ou des paramètres de timeout, vous pouvez modifier l’initialisation comme ceci

$yabetoo = new Yabetoo('sk_test_XXXXXXXXXXXXXXXXXXXXXXXX', [
    'timeout' => 5.0,
    'proxy' => 'tcp://localhost:8125'
]);

Gestion des erreurs

Toutes les requêtes API via le SDK peuvent renvoyer des erreurs HTTP en fonction de la réponse du serveur. Vous pouvez capturer les erreurs avec un bloc try-catch

try {
    $response = $yabetoo->payment->create([...]);
} catch (\Exception $e) {
    echo 'Erreur : ' . $e->getMessage();
}

Dernière mise à jour il y a 5 mois