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