SDK PHP

Ciblez l'URL de base de l'API la plus à jour

Pour créer des paiements, vous devez connecter votre serveur à notre plateforme via l'une de nos modes d'intégration.
Notre SDK PHP est la solution idéale pour vous connecter à notre plateforme si vous souhaitez le faire en utilisant le langage PHP.

En choisissant le SDK PHP, vous pouvez :

• Accéder à toutes les fonctionnalités de notre API
• Utiliser toutes les modes d'intégration de notre plateforme (Hosted Checkout Page / Hosted Tokenization Page / Server-to-server).
• Effectuer tous les appels liés à la création et au traitement des paiements (c'est-à-dire CreateHostedCheckout, CreatePayment, RefundPayment et bien d'autres).

Pour tirer pleinement parti de ce SDK, assurez-vous de répondre aux exigences suivantes :

• PHP 7.4 ou supérieur
• Recommandé : Installation de l'outil Composer

Vous pouvez télécharger et installer la dernière version du SDK PHP en :

• Utilisant le système Git et notre repo Github
• Installant le code fourni par Composer
• Installant notre bibliothèque manuellement sur votre système

Retrouvez plus de détails sur GitHub. Consultez également les Spécification de notre API. Une fois que tout est prêt, consultez les liens ci-dessous pour utiliser au mieux le SDK.

Initialisation

Pour connecter votre système à notre plateforme en utilisant le SDK, vous devez d'abord passer par une étape d'initialisation.

• Créez un PSPID de test / de production
• Créez une API Key et une API Secret pour le PSPID créé ci-dessus
• Utilisez la API Key et le API Secret pour établir la connexion à notre plateforme

Après cette initialisation, vous pouvez commencer à passer des transactions via votre PSPID. Découvrez comment cela fonctionne dans ce chapitre dédié.

Consultez l'exemple de code couvrant les étapes mentionnées ci-dessus :

// Your PSPID in either our test or live environment
$merchantId = "PSPID";

// Put the value of the API Key which you can find in the Merchant Portal
$apiKey = 'API KEY';

// Put the value of the API Secret which you can find in the Merchant Portal
$apiSecret = 'API Secret';

// This endpoint is pointing to the TEST server
// Note: Use the endpoint without the /v2/ part here
$apiEndpoint = 'https://payment.preprod.direct.worldline-solutions.com/';

// Additional settings to easily identify your company in our logs.
$integrator = 'YOUR COMPANY NAME';

$proxyConfiguration = null;
/*
* To use proxy, you should uncomment the section below
* and replace proper settings with your settings of the proxy.
* (additionally, you can comment on the previous setting).
*/
/*
$proxyConfiguration = new ProxyConfiguration(
    'proxyHost',
    'proxyPort',
    'proxyUserName',
    'proxyPassword'
);
*/
$communicatorConfiguration = new CommunicatorConfiguration(
    $apiKey,
    $apiSecret,
    $apiEndpoint,
    $integrator,
    $proxyConfiguration
);

$authenticator = new V1HmacAuthenticator($communicatorConfiguration);

$communicator = new Communicator($communicatorConfiguration, $authenticator);

$client = new Client($communicator);

$merchantClient = $client->merchant($merchantId);

Le tableau suivant fournit un aperçu des variables utilisées :

Après avoir initialisé le SDK, vous pouvez envoyer des requêtes à notre plateforme via votre PSPID. Apprenez comment faire cela dans le chapitre suivant.

Utiliser le SDK

Après cette étape d'initialisation, grâce à la création réussie de l'instance Client, vous avez un accès complet à notre API :

• Vous pouvez envoyer des demandes de création de transactions via l'une de nos modes d'intégration
• Vous pouvez obtenir le statut actuel de vos transactions
• Vous pouvez effectuer des opérations de maintenance (c'est-à-dire des captures, des remboursements, etc) sur vos transactions existantes

Consultez nos cas de test sur GitHub, incluant des exemples de code complets, et notre API Reference pour découvrir tout ce qui est possible de faire. Voici la liste des actions les plus courantes :

• Créer de nouvelles transactions
• Obtenir le statut d'une transaction
• Effectuer une opération de maintenance

Créer de nouvelles transactions

Pour créer une nouvelle transaction, vous pouvez utiliser soit l'instance Client, soit l'instance MerchantClient avec l'une de nos modes d'intégration. Cela peut se faire par :

• Acheminer la requête de votre PSPID vers notre plateforme (pour Client)
• Créer une requête pour la mode d'intégration respective

Vous trouverez ci-dessous des exemples de code pour chachune des modes d'intégration:

• Hosted Checkout Page
• Hosted Tokenization Page
• Server-to-server

Hosted Checkout Page

Pour utiliser cette méthode d'intégration, vous devez faire un appel à CreateHostedCheckoutRequest. Cet appel doit contenir au moins un objet Order.

/*
 *…. Initialisation....
 */

/*
 * L'objet HostedCheckoutClient est basé sur l'objet MerchantClient
 * créé lors de l'initialisation 
 */ 
$hostedCheckoutClient = $merchantClient->hostedCheckout();

$createHostedCheckoutRequest = new CreateHostedCheckoutRequest();

$order = new Order();

// Example object of the AmountOfMoney
$amountOfMoney = new AmountOfMoney();
$amountOfMoney->setCurrencyCode("EUR");
$amountOfMoney->setAmount(100);
$order->setAmountOfMoney($amountOfMoney);

$createHostedCheckoutRequest->setOrder($order);

// Obtenez la réponse pour le HostedCheckoutClient
$createHostedCheckoutResponse = $hostedCheckoutClient->createHostedCheckout($createHostedCheckoutRequest);

Cet appel retourne un objet CreateHostedCheckoutResponse. Stockez le hostedCheckoutId et le RETURNMAC qu'il contient, ainsi que toute autre information pertinente pour vous. Vous aurez besoin de ces éléments pour les étapes décrites dans les chapitres suivants.

Cette réponse contient également un partialRedirectUrl. Vous devez concaténer l'URL de base "https://payment." avec partialRedirectUrl selon la formule suivante :

https://payment. + partialRedirectUrl

et réaliser une redirection de votre client vers cette URL. Une fois que le client visite la Hosted Checkout Page, le processus de paiement se poursuit là-bas.

Hosted Tokenization Page

Pour utiliser cette méthode d'intégration, vous devez :

• Créer et télécharger un modèle tel que décrit dans notre guide Hosted Tokenization Page.

/*
 *…. Initialisation....
 */

/*
 * L'objet HostedTokenizationClient est basé sur l'objet   
 * MerchantClient créé lors de l'initialisation 
 */
$hostedTokenizationClient = $merchantClient->hostedTokenization();

$createHostedTokenizationRequest = new CreateHostedTokenizationRequest();

$createHostedTokenizationRequest->setVariant("my-custom-template.html");

// Obtenez la réponse pour le HostedTokenizationClient
$createHostedTokenizationResponse = $hostedTokenizationClient->createHostedTokenization($createHostedTokenizationRequest);

A partir de l'objet $createHostedTokenizationResponse, récupérez les données $hostedTokenizationId et hostedTokenizationUrl. Utilisez le $hostedTokenizationUrl pour l'iframe et le $hostedTokenizationId ou $tokenId (voir infobox) pour créer le paiement réel via la méthode Server-to-server.

$hostedTokenizationId = $createHostedTokenizationResponse->getHostedTokenizationId();
$hostedTokenizationUrl = $createHostedTokenizationResponse->getHostedTokenizationUrl();

$createPaymentRequest = new CreatePaymentRequest();
$createPaymentRequest->setHostedTokenizationId($hostedTokenizationId);

$order = new Order();

$amountOfMoney = new AmountOfMoney();
$amountOfMoney->setCurrencyCode("EUR");
$amountOfMoney->setAmount(100);
$order->setAmountOfMoney($amountOfMoney);

$createPaymentRequest->setOrder($order);

// Obtenez la réponse pour le PaymentsClient 
$createPaymentResponse = $merchantClient->payments()->createPayment($createPaymentRequest);

Server-to-server

Une CreatePaymentRequest minimale nécessite que vous définissiez au moins un objet Order et un moyen de paiement :

/* 
 *…. Initialisation....
 */

$merchantClient = $client->merchant($merchantId);

/*
 * L'objet PaymentsClient est basé sur le MerchantClient  
 * créé lors de l'initialisation 
 */
$paymentsClient = $merchantClient->payments();

$createPaymentRequest = new CreatePaymentRequest(); 

$order = new Order();

// Exemple de l'objet AmountOfMoney 
$amountOfMoney = new AmountOfMoney();
$amountOfMoney->setCurrencyCode("EUR");
$amountOfMoney->setAmount(100);
$order->setAmountOfMoney($amountOfMoney);

$createPaymentRequest->setOrder($order);
 
$cardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput();

// Exemple de l'objet Card
$card = new Card();
$card->setCvv("123");
$card->setCardNumber("4111111111111111"); // Trouvez plus de données de test ici 
$card->setExpiryDate("1236");
$card->setCardholderName("Wile E. Coyote");
$cardPaymentMethodSpecificInput->setCard($card);
 
$createPaymentRequest->setCardPaymentMethodSpecificInput($cardPaymentMethodSpecificInput);
 
// Obtenez la réponse pour le PaymentsClient
$createPaymentResponse = $paymentsClient->createPayment($createPaymentRequest);

Obtenir le statut de la transaction

Notre API vous permet de demander le statut d'une transaction à tout moment grâce à l'un de nos appels GET :

• GetHostedCheckout
• GetPaymentDetails
• GetCaptures
• GetRefunds

Un appel GetPaymentDetails ressemble à ceci :

// Obtenez la réponse pour le PaymentsClient
$createPaymentResponse = $merchantClient->payments()->createPayment($createPaymentRequest);

// Ici, vous obtenez $paymentId que vous pouvez utiliser dans le code suivant
$paymentId = $createPaymentResponse->getPayment()->getId();

// Obtenez l'objet PaymentResponse avec les informations de statut
// concernant le paiement de l'ID donné
$paymentResponse = $merchantClient->payments()->getPaymentDetails($paymentId);

Pour plus d'informations sur les statuts, visitez la page de documentation des statuts.

Effectuer une opération de maintenance

Pour effectuer des opérations de maintenance sur des transactions existantes (c'est-à-dire des captures ou des remboursements), utilisez respectivement nos API CapturePayment et RefundPayment.

CapturePayment

/* 
 *…. Initialisation....
 */

$merchantClient = $client->merchant($merchantId);

// Ici, vous obtenez $paymentId que vous pouvez utiliser dans le code suivant
$paymentID = $createPaymentResponse->getPayment()->getId();

$capturePaymentRequest = new CapturePaymentRequest();
$capturePaymentRequest->setAmount(100);
$capturePaymentRequest->setIsFinal(true);

// Obtenez l'objet CaptureResponse
$captureResponse = $merchantClient->payments()->capturePayment($paymentID, $capturePaymentRequest);

Rembourser le paiement

/*  
 *…. Initialisation.... 
 */ 
 
$merchantClient = $client->merchant($merchantId); 

// Ici, vous obtenez $paymentId que vous pouvez utiliser dans le code suivant 
$paymentID = $createPaymentResponse->getPayment()->getId(); 

$refundRequest = new RefundRequest(); 

$amountOfMoney = new AmountOfMoney(); 
$amountOfMoney->setCurrencyCode("EUR"); 
$amountOfMoney->setAmount(100); 

$refundRequest->setAmountOfMoney($amountOfMoney); 


// Obtenez l'objet RefundResponse 
$refundResponse = $merchantClient->payments()->refundPayment($paymentID, $refundRequest );

Gérer les exceptions

Si une transaction est rejetée, notre plateforme fournit des informations détaillées avec l'objet Exception. Le code HTTP status associé vous aide également à diagnostiquer l'erreur.

Vous pouvez rencontrer deux types d'exceptions : exceptions de transaction et exceptions HTTP.

Exceptions de transaction

Ce type d'exception fait référence aux demandes de transaction qui sont techniquement correctes mais ont été rejetées par l'émetteur de votre client ou par votre acquéreur. Si la transaction est retournée dans l'exception, cela signifie qu'elle a été créée dans nos systèmes mais n'a pas été traitée avec succès.

/*
 * Initialisation....
 */

$paymentID = "";
$createPaymentRequest = new CreateRequest();

try {
     $createPaymentResponse = 
         $paymentsClient->createPayment(
             $createPaymentRequest
        );

     $paymentID = $createPaymentResponse
        ->getPayment()->getId();
     } 
catch (DeclinedPaymentException $e) {
     $paymentResult = $e->getPaymentResult();
     $payment = $paymentResult->getPayment();
     handleError($payment);
     return;
     }


$paymentResponse = $merchantClient
    ->payments()->getPayment($paymentID);

// Votre code pour vérifier le statut de la transaction et 
// gérer les erreurs

if (isNotSuccessful($paymentResponse)) {
    handleError($paymentResponse);
}

/*
 * Initialisation....
 */


$paymentID = $createPaymentResponse
   ->getPayment()->getId();

$refundID = "";
$refundRequest = new CreateRequest();

try {
     // Obtenez l'objet RefundResponse
     $refundResponse = $merchantClient
        ->payments()
        ->refundPayment(
             $paymentID,
             $refundRequest
         );

      $refundID = $refundResponse->getId();
    }
catch (DeclinedRefundException $e) {
    $refundResult = $e->getRefundResult();

    handleError($refundResult);
    return;
}

$refundResponse = $merchantClient
    ->payments()
    ->refundPayment($paymentID, $refundRequest);

// Votre code pour vérifier le statut de la transaction et 
// gérer les erreurs

if (isNotSuccessful($refundResponse, $refundID)) {
   handleError($refundResponse);
}

Exceptions HTTP

Ce type d'exception fait référence à divers problèmes causés par des erreurs techniques dans l'appel API ou dans la demande de paiement.

Vous pouvez combiner l'un des extraits de code suivants avec un appel API CreatePayment :

/* 
 *…. Initialisation....
 */

$createPaymentRequest = new CreatePaymentRequest(); 

$order = new Order();

// L'objet exemple de AmountOfMoney 
$amountOfMoney = new AmountOfMoney();
$amountOfMoney->setCurrencyCode("EUR");
$amountOfMoney->setAmount(100);
$order->setAmountOfMoney($amountOfMoney);
 
$createPaymentRequest->setOrder($order);

$cardPaymentMethodSpecificInput = 
new CardPaymentMethodSpecificInput();

// L'objet exemple de la carte – vous pouvez trouver des cartes de test sur
// /documentation/test-cases/
$card = new Card();
$card->setCvv("123");
$card->setCardNumber("4111111111111111");
$card->setExpiryDate("1236");
$card->setCardholderName("Wile E. Coyote");
$cardPaymentMethodSpecificInput->setCard($card);
 
$createPaymentRequest->setCardPaymentMethodSpecificInput(
$cardPaymentMethodSpecificInput
);

try { 
// Obtenez la réponse pour le PaymentsClient
$createPaymentResponse = 
$paymentsClient
->createPayment($createPaymentRequest);
} catch (ApiException $e) {
// reportez-vous à la liste ci-dessous pour voir comment des 
// implémentations spécifiques de ApiException peuvent être gérées.
}

catch (ValidationException $e) {
    $message = 'Erreur de validation des entrées:' . PHP_EOL;
    foreach ($e->getErrors() as $error) {
        $message .= '- ';
        if (!empty($error->getPropertyName())) {
            $message .= $error->getPropertyName() . ': ';
        }

        $message .= $error->getMessage();
        $message .= '(' . $error->getCode() . ')' . PHP_EOL;
    }
    // Faites quelque chose avec $message
}

catch (AuthorizationException $e) {
    $message = 'Erreur d\'autorisation:' . PHP_EOL;
    foreach ($e->getErrors() as $error) {
       $message .= '- ' . $error->getMessage();
       $message .= '(' . $error->getCode() . ')' . PHP_EOL;
    }
    // Faites quelque chose avec $message
}

catch (IdempotenceException $exception) {
    $message = 'Erreur d\'idempotence:' . PHP_EOL;
    foreach ($e->getErrors() as $error) {
       $message .= '- ' . $error->getMessage();
       $message .= '(' . $error->getCode() . ')' . PHP_EOL;
    }
    // Faites quelque chose avec $message
}

catch (ReferenceException $e) {
    $message = 'Référence d\'objet incorrecte:' . PHP_EOL;
    foreach ($e->getErrors() as $error) {
       $message .= '- ' . $error->getMessage();
       $message .= '(' . $error->getCode() . ')' . PHP_EOL;
    }
    // Faites quelque chose avec $message
}

catch (PaymentPlatformException $e) {
    $message = 'Erreur survenue chez Direct ou ';
    $message .= 'un partenaire/acquéreur en aval:' . PHP_EOL;
    foreach ($e->getErrors() as $error) {
       $message .= '- ' . $error->getMessage();
       $message .= '(' . $error->getCode() . ')' . PHP_EOL;
    }
    // Faites quelque chose avec $message
}

catch (ApiException $e) {
    $message = 'Erreur imprévue:' . PHP_EOL;
    foreach ($e->getErrors() as $error) {
       $message .= '- ' . $error->getMessage();
       $message .= '(' . $error->getCode() . ')' . PHP_EOL;
    }
    // Faites quelque chose avec $message
}

Codes d'état HTTP

Toutes nos exceptions sont liées à un ou plusieurs codes d'état HTTP, indiquant la cause profonde de nombreux possibles erreurs.

DeclinedPaymentException

DeclinedPayoutException

DeclinedRefundException

ValidationException

AuthorizationException

ReferenceException

IdempotenceException
ReferenceException

ReferenceException

PaymentPlatformException

PaymentPlatformException

PaymentPlatformException

ApiException

Fonctionnalités supplémentaires

Le SDK a beaucoup plus à offrir. Découvrez les fonctionnalités suivantes, car elles vous aideront à construire la solution parfaite.

• Obtenir les méthodes de paiement disponibles
• Envoyer des requêtes idempotentes
• Utiliser la Logging
• Mise en pool de connexions
• Personnaliser la communication
• Webhooks

Obtenir les méthodes de paiement disponibles

Avant d'initier le processus de paiement réel, vous pouvez faire un appel GetPaymentProducts. La réponse contiendra la liste des moyens de paiement disponibles pour votre PSPID. Vous pouvez laisser vos clients sélectionner le moyen de paiement de leur choix grâce à notre Hosted Checkout Page ou héberger vous-même votre propre page de sélection puis faire des appels à CreatePayment.

/* 
 *…. Initialisation....
 */

$merchantClient = $client->merchant($merchantId);

// Préparer la demande pour obtenir toutes les méthodes de paiement actives de votre PSPID
$queryParams = new GetPaymentProductsParams();

// Paramètres d'exemple
$queryParams->setCountryCode("BE");
$queryParams->setCurrencyCode("EUR");

// Envoyer la demande et obtenir la réponse
$paymentProductsResponse = $merchantClient->products()->getPaymentProducts($queryParams);

Envoyer des requêtes idempotentes

Une des principales fonctionnalités de l'API est sa capacité à détecter et à empêcher l'envoi accidentel de requêtes de paiement en double. Le SDK vous facilite grandement la tâche pour vous assurer que vous n'envoyez que des requêtes uniques – idempotentes – à notre plateforme.

Utilisez l'argument supplémentaire CallContext et définissez sa propriété nommée $idempotenceKey en appelant le setter setIdempotenceKey() sur l'objet créé précédemment et appelez la fonction API CreatePayment. Le SDK enverra un en-tête X-GCS-Idempotence-Key avec la clé d'idempotence comme valeur.

Si vous envoyez des requêtes de cette manière à notre plateforme, nous vérifierons ce qui suit :

• Si vous envoyez une requête subséquente avec la même clé d'idempotence, la réponse contient un en-tête X-GCS-Idempotence-Request-Timestamp. Le SDK définira la propriété $idempotenceRequestTimestamp de l'argument CallContext.
• Si la première demande n'est pas encore terminée, l'API renverra un code de statut 409. Dans ce cas, le SDK déclenchera une IdempotenceException avec la clé d'idempotence d'origine et le timestamp de la requête d'idempotence.

/* 
 *…. Initialisation....
 */

$merchantClient = $client->merchant($merchantId);

$createPaymentRequest = new CreatePaymentRequest();

$idempotenceKey = "VotreCléPourLePaiement";
 
$callContext = new CallContext();
$callContext->setIdempotenceKey($idempotenceKey);

try {
    $createPaymentResponse = $merchantClient
        ->payments()
        ->createPayment(
            $createPaymentRequest, 
            $callContext
        );
} catch (IdempotenceException $e) {
    // une demande avec le même $idempotenceKey est toujours en cours, essayez à nouveau après une brève pause
    // $e->getIdempotenceRequestTimestamp() contient la valeur de l'en-tête
    // X-GCS-Idempotence-Request-Timestamp
} finally {
    $idempotenceRequestTimestamp = 
        $callContext->getIdempotenceRequestTimestamp();
    // $idempotenceRequestTimestamp contient la valeur de l'en-tête
    // X-GCS-Idempotence-Request-Timestamp
    // si $idempotenceRequestTimestamp n'est pas vide, ce n'était pas la première demande
}

Utiliser la Logging

Le SDK prend en charge la Logging des requêtes, des réponses, et des exceptions. Cela peut être utile pour le dépannage ou le suivi des étapes dans un flux de paiement.
Le SDK offre deux implémentations de la fonctionnalité de Logging :

• SplFileObjectLogger (en utilisant SplFileObject)
• ResourceLogger

Vous pouvez activer/désactiver la logging en appelant :

/* 
 *…. Initialisation....
 */

$client = new Client($communicator);

// Vous pouvez entrer un pointeur de fichier vers le fichier 
// dans lequel vous souhaitez enregistrer les données à la place de STDOUT
$logger = new ResourceLogger(STDOUT); 
$client->enableLogging($logger); 
//... Effectuez quelques appels 
$client->disableLogging();

Mise en pool de connexions

Vous pouvez gérer vos ressources réseau en limitant le nombre de connexions possibles que le SDK crée et maintient. Les instances de Client créées comme discuté dans le chapitre Initialiser le SDK disposeront de leur propre pool de connexions. Les instances de Client créées avec le même objet Communicator partagent un même pool de connexions.

Si vous utilisez plusieurs instances de Client pour partager un seul pool de connexions, assurez-vous de suivre ces étapes :

1. Créer un Communicator partagé.
2. Créer des instances de Client avec ce Communicator.

/* 
 *…. Initialisation....
 */

// Créez une instance de CommunicatorConfiguration 
// avec les paramètres appropriés
$sharedCommunicatorConfiguration = 
new CommunicatorConfiguration(
    $apiKey,
    $apiSecret,
    $apiEndpoint,
    $integrator,
    $proxyConfiguration
);
 
$connection = new DefaultConnection();

// Instance de Communicator
$communicator = new Communicator(
$connection, 
$sharedCommunicatorConfiguration
);
 
$client1 = new Client($communicator);
$client2 = new Client($communicator);

Personnaliser la communication

Les instances de Client utilisent une instance de Communicator pour communiquer avec notre plateforme. Tandis que Communicator utilise Connection pour effectuer les requêtes HTTP réelles et une ConnectionResponse pour contenir la réponse HTTP.

Connection et ConnectionResponse sont des interfaces. Le SDK fournit une implémentation par défaut de ces interfaces via les classes DefaultConnection et DefaultConnectionResponse.

Vous pouvez fournir votre propre implémentation de l'interface de Connection à utiliser dans l'objet Communicator, par exemple la classe YourConnection.

/* 
 *…. Initialisation....
 */

$merchantClient = $client->merchant($merchantId);

$createPaymentRequest = new CreatePaymentRequest(); 

$idempotenceKey = "VotreCléPourLePaiement"; 

$callContext = new CallContext();
$callContext->setIdempotenceKey($idempotenceKey);

try {
    $createPaymentResponse = $merchantClient
        ->payments()
        ->createPayment(
            $createPaymentRequest, 
            $callContext
        );
} catch (IdempotenceException $e) {
    // une requête avec la même $idempotenceKey est toujours en cours, essayez à nouveau après une brève pause
    // $e->getIdempotenceRequestTimestamp() contient la valeur de l'en-tête
    // X-GCS-Idempotence-Request-Timestamp
} finally {
    $idempotenceRequestTimestamp = 
        $callContext->getIdempotenceRequestTimestamp();
    // $idempotenceRequestTimestamp contient la valeur de l'en-tête
    // X-GCS-Idempotence-Request-Timestamp
    // si $idempotenceRequestTimestamp n'est pas vide, ce n'était pas la première requête
}

Webhooks

La partie du SDK qui gère le support des webhooks est appelée le helper des webhooks. Il gère de manière transparente à la fois la validation des signatures par rapport aux corps des événements envoyés par le système de webhooks (y compris la recherche de la clé secrète pour les ID de clés - à ne pas confondre avec la API Key et API Secret ), et le désérialisation de ces corps en objets. Cela vous permet de vous concentrer sur l'essentiel, sans devoir passer par toutes les informations supplémentaires et extraire celles qui vous intéressent. Pour en savoir plus sur les webhooks, lisez notre guide dédié.

Fournissez des clés secrètes

Configurez le "WebhooksKey" / "WebhooksKeySecret" et les API endpoints de vos webhooks serveur dans le Merchant Portal :

$keyId = "WebhooksKey";
$secretKey = "WebhooksKeySecret";

Les clés secrètes sont fournies à l'aide d'une fonction qui prend deux arguments :

• L'ID de la clé pour laquelle vous souhaitez obtenir la clé secrète.
• Une fonction de rappel qui prend soit une erreur comme premier argument, soit la clé secrète pour l'ID de clé donné comme second argument (dans ce cas, le premier argument doit être null).

Le SDK fournit une implémentation pour cette fonction : InMemorySecretKeyStore::getSecretKey($keyId). Cela récupérera les clés secrètes à partir d'un magasin de clés en mémoire pour le $keyId approprié.

Les clés peuvent être ajoutées ou supprimées à l'aide des fonctions suivantes :

• InMemorySecretKeyStore::storeSecretKey($keyId, $secretKey) pour stocker une clé secrète pour un ID de clé.
• InMemorySecretKeyStore::removeSecretKey($keyId) pour supprimer la clé secrète stockée pour un ID de clé.
• InMemorySecretKeyStore::clear() pour supprimer toutes les clés secrètes stockées.

Si un stockage plus avancé est requis, par exemple en utilisant une base de données ou un système de fichiers, nous vous recommandons d'écrire votre propre implémentation.

Initialisez le helper des webhooks

Incluez et initialisez le helper des webhooks comme suit :

$keyId = 'dummy-key-id';
$secretKey = 'dummy-secret-key’';
$secretKeys = array(
   $keyId => $secretKey
);
$secretKeyStore = new InMemorySecretKeyStore($secretKeys);
// À ce moment, les $secretKeys sont stockées car elles ont été données au constructeur
// mais vous pouvez définir un tableau vide de $secretKeys et après cela vous pouvez 
// utiliser les fonctions de InMemorySecretKeyStore comme mentionné ci-dessus 
// ou même vous pouvez étendre la classe InMemorySecretKeyStore pour 
// implémenter vos propres méthodes pour gérer les $secretKeys
$helper = new WebhooksHelper($secretKeyStore);

Utilisez le helper des webhooks

À partir d'un point d'entrée que vous avez créé vous-même, appelez la méthode de désérialisation du helper des webhooks. Elle prend les arguments suivants :

• Le corps, sous forme de chaîne ou de tampon. Cela doit être le corps brut tel que reçu du système de webhooks.
• Un objet contenant les en-têtes de requête tels que reçus du système de webhooks. Les clés doivent être les noms des en-têtes.

// Initialisation
$bodyOfRequest = 'JSON_Body_Of_The_Request';

// Récupérez les en-têtes du message webhook, cela dépend de votre implémentation.
$webhookHeaders = $request->getHeaders();

// Transformez les en-têtes reçus
$requestHeaders = [];
foreach ($webhookHeaders as $webhookHeader) {
    $requestHeaders[$webhookHeader->getName()] = $webhookHeader->getValue();
}

try {
    $webhook_event = $helper->unmarshal($bodyOfRequest, $requestHeaders);
} catch (SignatureValidationException $e) {
    // Votre code pour gérer les erreurs
}