Processus d'intégration iPay88

L'implémentation de la passerelle iPay88 suit un flux logique standard pour les paiements en ligne. Le cycle de trnasaction se décompose en trois étapes majeures : la préparation des données de commande, la génération d'une signature sécurisée et la soumission des paramètres via un formulaire POST vers les serveurs d'iPay88.

Pour débuter, vous devez posséder vos identifiants marchands (Merchant Code et Merchant Key) fournis par le portail iPay88. Durant la phase de test, la passerelle limite généralement les transactions aux cartes de crédit (Visa/Mastercard) avec un montant symbolique de 1.00.

Configuration technique

L'exemple suivant illustre une structure de configuration typique pour initialiser le composant de paiement :

$ipayConfig = [
    'merchant_code' => 'VOTRE_CODE_MARCHAND',
    'merchant_key'  => 'VOTRE_CLE_MARCHANDE',
    'currency'      => 'MYR',
    'url_retour'    => 'https://votre-site.com/payment/success',
    'url_callback'  => 'https://votre-site.com/payment/webhook',
    'endpoint'      => 'https://payment.ipay88.com.my/ePayment/entry.asp'
];

Logique de traiteemnt des paiements

La classe ci-dessous encapsule la logique nécessaire pour générer la signature de sécurité et préparer les champs requis pour la requête de paiement.

class Ipay88Manager {
    private $mCode;
    private $mKey;

    public function __construct($code, $key) {
        $this->mCode = $code;
        $this->mKey = $key;
    }

    /**
     * Génère la signature SHA1 requise par iPay88
     */
    public function generateSignature($refNo, $amount, $currency) {
        // Le montant doit être formaté sans points ni virgules pour la signature
        $cleanAmount = str_replace(['.', ','], '', $amount);
        $rawString = $this->mKey . $this->mCode . $refNo . $cleanAmount . $currency;
        
        return base64_encode($this->hexToBinary(sha1($rawString)));
    }

    private function hexToBinary($hexString) {
        $binary = "";
        for ($i = 0; $i < strlen($hexString); $i += 2) {
            $binary .= chr(hexdec(substr($hexString, $i, 2)));
        }
        return $binary;
    }

    /**
     * Valide la signature reçue lors du retour de paiement
     */
    public function validateResponse($params) {
        $raw = $this->mKey . $this->mCode . $params['RefNo'] . 
               str_replace(['.', ','], '', $params['Amount']) . 
               $params['Currency'] . $params['Status'];
               
        $expected = base64_encode($this->hexToBinary(sha1($raw)));
        return ($expected === $params['Signature']);
    }
}

Initialisation d'une transacsion

Avant de rediriger l'utilisateur, vous devez définir les détails de la commande. Voici comment préparer ces données dans votre contrôleur :

// Exemple de préparation de commande
$orderData = [
    'RefNo'       => 'INV-' . time(),
    'Amount'      => '1.00',
    'Currency'    => 'MYR',
    'ProdDesc'    => 'Achat de services numériques',
    'UserName'    => 'Jean Dupont',
    'UserEmail'   => 'jean.dupont@example.com',
    'UserContact' => '0123456789',
    'Remark'      => 'Commande web',
    'Lang'        => 'UTF-8'
];

$manager = new Ipay88Manager($ipayConfig['merchant_code'], $ipayConfig['merchant_key']);
$signature = $manager->generateSignature($orderData['RefNo'], $orderData['Amount'], $orderData['Currency']);

Soumission vers la passerelle

L'interaction finale s'effectue via un formulaire HTML masqué qui redirige automatiquement l'utilisateur vers la page de paiement sécurisée d'iPay88.

<form method="post" id="ipay88_form" action="https://payment.ipay88.com.my/ePayment/entry.asp">
    <input type="hidden" name="MerchantCode" value="<?php echo $ipayConfig['merchant_code']; ?>">
    <input type="hidden" name="PaymentId" value="">
    <input type="hidden" name="RefNo" value="<?php echo $orderData['RefNo']; ?>">
    <input type="hidden" name="Amount" value="<?php echo $orderData['Amount']; ?>">
    <input type="hidden" name="Currency" value="<?php echo $orderData['Currency']; ?>">
    <input type="hidden" name="ProdDesc" value="<?php echo $orderData['ProdDesc']; ?>">
    <input type="hidden" name="UserName" value="<?php echo $orderData['UserName']; ?>">
    <input type="hidden" name="UserEmail" value="<?php echo $orderData['UserEmail']; ?>">
    <input type="hidden" name="UserContact" value="<?php echo $orderData['UserContact']; ?>">
    <input type="hidden" name="Remark" value="<?php echo $orderData['Remark']; ?>">
    <input type="hidden" name="Lang" value="UTF-8">
    <input type="hidden" name="Signature" value="<?php echo $signature; ?>">
    <input type="hidden" name="ResponseURL" value="<?php echo $ipayConfig['url_retour']; ?>">
    <input type="hidden" name="BackendURL" value="<?php echo $ipayConfig['url_callback']; ?>">
    <button type="submit">Procéder au paiement</button>
</form>

Traitement de la réponse (Callback)

Une fois le paiement effectué, iPay88 envoie les résultats à votre BackendURL. Il est crucial de capturer ces données brutes et de vérifier l'intégrité de la signature avant de mettre à jour le statut de la commande dans votre base de données.

// Capture des données envoyées par iPay88
$responseParams = $_POST;

if (!empty($responseParams)) {
    $manager = new Ipay88Manager($config['merchant_code'], $config['merchant_key']);
    
    if ($manager->validateResponse($responseParams)) {
        if ($responseParams['Status'] == '1') {
            // Succès : Mettre à jour la commande ici
            echo "RECEIVEOK"; // Confirmation attendue par le serveur iPay88
        } else {
            // Échec du paiement
        }
    } else {
        // Erreur de signature : Alerte de sécurité potentielle
    }
}