Utilisation de l’IPN (URL de notification)

IPN signifie Instant Payment Notification. Quand une transaction est créée ou que son statut change, nos serveurs lancent une IPN en appelant une URL de notification située sur vos serveurs. Cela vous permet d’être notifié en temps réel des changements intervenus sur une transaction.

Pour plus d’informations générales sur les IPNs, vous pouvez consulter l’article suivant: IPN: généralités

Une IPN est le seul moyen d’être notifié dans les cas suivants :

• La connexion internet de l’acheteur est coupée
• L’acheteur ferme son navigateur au cours du paiement
• Une transaction est refusée

Il est donc impératif d’intégrer les IPN !

Lorsque l’acheteur valide le paiement, une transaction est créée. Nos serveurs vont tenter de joindre vos serveurs pour transmettre toutes les informations concernant la transaction.

L’étape 3 a lieu seulement après que vos serveurs ont répondu (le temps d’attente maximum est de 30 secondes). Cela vous permet de mettre à jour votre système d’information avant que l’acheteur ne soit redirigé sur votre page de confirmation d’achat.

Pour configurer la notification :

1. Connectez vous sur le Back Office Lyra Collect
2. Rendez-vous sur le menu suivant : Paramétrage > Règles de notifications.

1. Effectuez un clic-droit sur URL de notification à la fin du paiement.
2. Sélectionnez Gérer la règle.
3. Dans la section Paramétrage général, renseignez le champ Adresse(s) e-mail(s) à avertir en cas d’échec.
4. Cochez la case Rejeu automatique en cas d’échec si vous souhaitez autoriser la plateforme à renvoyer automatiquement la notification en cas d’echec, et ce, jusqu’à 4 fois.
5. Dans la section URL de notification de l’API REST, renseignez l’URL de votre page dans les champs URL cible de l’IPN à appeler en mode TEST et URL cible de l’IPN à appeler en mode PRODUCTION.
6. Sauvegardez les modifications.

Si le serveur cible de l’IPN est hors ligne, un e-mail vous sera envoyé à l’adresse définie dans la configuration de la règle.

Cet e-mail contient :

• Le code d’erreur HTTP retourné par votre serveur
• Des éléments d’analyse
• L’explication sur les conséquences de l’erreur
• Les instructions pour relancer l’IPN (à travers le Back Office Expert)

Lors de la création du formToken, vous pouvez définir l’URL cible de l’IPN dynamiquement avec le paramètre ipnTargetUrl:

{
    "amount": 990,
    "currency": "EUR",
    "ipnTargetUrl": "https://my.super.site/ipn"
}

L’IPN est envoyée sur vos serveurs en utilisant la même procédure que le client JavaScript. Cela vous permet d’utiliser un code similaire pour traiter la réponse:

• Les données sont envoyées sous forme de formulaire (content-type: x-www-form-urlencoded),
• Les paramètres qui contiennent les données sont les mêmes.

Les différences sont:

• kr-answer contient les objets transactions complets,
• la signature contenue dans kr-hash est calculée de façon différente.

L’IPN est envoyée en POST de la façon suivante sur vos serveurs:

kr-hash=c3c0323c748fdb7c2d24bd39ada99663526236828efa795193bebfdea022fe58
kr-hash-algorithm=sha256_hmac
kr-hash-key=password
kr-answer-type=V4/Payment
kr-answer={"shopId":"33148340","orderCycle":"CLOSED",(...)}

Les paramètres POST correspondent à :

Avant d’entrer dans le détail du contenu de kr-answer, nous devons vérifier s’il est valide.

Afin de détecter les fraudes potentielles, vous devez vérifier l’authenticité du champ kr-answer.

Le champ kr-hash contient le hash de kr-answer généré avec le mot de passe (qui commence par testpassword* ou prodpassword*).

Le mot de passe est disponible dans votre Back Office (menu Paramétrage > Boutique, onglet Clés d’API REST, section Clés d’API REST).

Pour vérifier la validité de la signature avec nos SDKs :

/* Check the signature using password */

if (!$client->checkHash()) {
    //something wrong, probably a fraud ....
    signature_error($formAnswer['kr-answer']['transactions'][0]['uuid'], $hashKey, 
                    $client->getLastCalculatedHash(), $_POST['kr-hash']);
    throw new Exception('invalid signature');
}

Une fois la signature vérifiée, vous pouvez récupérer les informations liées à la transaction ainsi:

/* Retrieve the IPN content */
$rawAnswer = $client->getParsedFormAnswer();
$formAnswer = $rawAnswer['kr-answer'];

/* Retrieve the transaction id from the IPN data */
$transaction = $formAnswer['transactions'][0];

/* get some parameters from the answer */
$orderStatus = $formAnswer['orderStatus'];
$orderId = $formAnswer['orderDetails']['orderId'];
$transactionUuid = $transaction['uuid'];

Voir la section suivante pour plus de détails.

Exemple d’implémentation de la vérification du hash en PHP :

    /**
     * check kr-answer object signature
     */
    public function checkHash($key=NULL)
    {
        $supportedHashAlgorithm = array('sha256_hmac');

        /* check if the hash algorithm is supported */
        if (!in_array($_POST['kr-hash-algorithm'],  $supportedHashAlgorithm)) {
            throw new LyraException("hash algorithm not supported:" . $_POST['kr-hash-algorithm'] .". Update your SDK");
        }

        /* on some servers, / can be escaped */
        $krAnswer = str_replace('\/', '/', $_POST['kr-answer']);

        /* if key is not defined, we use kr-hash-key POST parameter to choose it */
        if (is_null($key)) {
            if ($_POST['kr-hash-key'] == "sha256_hmac") {
                $key = $this->_hashKey;
            } elseif ($_POST['kr-hash-key'] == "password") {
                $key = $this->_password;
            } else {
                throw new LyraException("invalid kr-hash-key POST parameter");
            }
        }
    
        $calculatedHash = hash_hmac('sha256', $krAnswer, $key);
        $this->_lastCalculatedHash = $calculatedHash;

        /* return true if calculated hash and sent hash are the same */
        return ($calculatedHash == $_POST['kr-hash']);
    }
}

Le choix de la clé doit être basé sur la valeur de kr-hash-key:

L’objet transaction est contenu dans le paramètre POST kr-answer au format JSON:

Le paramètre kr-answer contient les informations sur l’état de la session de paiement :

{
    "shopId": "69876357",
    "orderCycle": "CLOSED",
    "orderStatus": "PAID",
    "serverDate": "2018-09-27T14:02:17+00:00",
    "orderDetails": (...)
    "customer": (...)
    },
    "transactions": [{
        "shopId": "69876357",
        "uuid": "5b158f084502428499b2d34ad074df05",
        "amount": 990,
        (...)
        "_type": "V4/PaymentTransaction"
    }],
    "_type": "V4/Payment"
}

Vous pouvez utiliser n’importe quelle fonction stantard pour y accéder, ou via notre SDK:

/* Retrieve the IPN content */
$rawAnswer = $client->getParsedFormAnswer();
$formAnswer = $rawAnswer['kr-answer'];

/* Retrieve the transaction id from the IPN data */
$transaction = $formAnswer['transactions'][0];

/* get some parameters from the answer */
$orderStatus = $formAnswer['orderStatus'];
$orderId = $formAnswer['orderDetails']['orderId'];
$transactionUuid = $transaction['uuid'];

Pour comprendre la signification des champs status et detailedStatus, rendez-vous ici: Référence de status

En cas de restriction mise en place du côté du site marchand, il faudra autoriser la plage d’adresses IP 194.50.38.0/24.

Les notifications sont envoyées depuis une adresse IP comprise dans la plage 194.50.38.0/24 en mode Test et en mode Production.