SDK Node.js

Introduction

Pour créer des paiements, vous devez lier votre serveur à notre plateforme via l'une de nos modes d'intégration.
Notre bibliothèque SDK Node.js est la solution idéale pour se connecter à notre plateforme si vous préférez le faire avec votre propre système autonome utilisant le langage Node.js.

En choisissant le SDK Node.js, vous pouvez :

• Accéder à toutes les fonctionnalités de notre API RESTful de manière compacte, pratique et personnalisable.
• Utiliser toutes les modes d'intégration côté serveur de notre plateforme (Hosted Checkout Page / Hosted Tokenization Page / Server-to-server).
• Effectuer tous les appels API liés 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 à ces exigences :

• Node.js 18 ou supérieur

Installez la dernière version du SDK Node.js en utilisant le gestionnaire de packages NPM en exécutant :

npm i onlinepayments-sdk-nodejs

Trouvez plus de détails sur GitHub. Consultez également tous les objets et propriétés SDK disponibles dans notre Référence complète de l'API. Une fois prêt, lisez les chapitres suivants sur la préparation et l'utilisation du SDK.

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

Initialisation

Pour connecter votre système à notre plateforme en utilisant le SDK, vous devez d'abord l'initialiser.

L'initialisation du SDK nécessite de

• Créer un compte test/production.
• Créer une API Key et API Secret pour le PSPID que vous souhaitez utiliser pour le traitement des transactions.
• Initialiser une instance de directSdk en utilisant la API Key / API Secret pour configurer la connexion à notre plateforme de test/production.
  
  

Après l'initialisation, vous pouvez commencer à traiter les transactions via votre PSPID. Apprenez comment cela fonctionne dans le chapitre dédié.

Jetez un œil aux exemples de code de deux méthodes de connexion couvrant les étapes mentionnées ci-dessus :

const onlinePaymentsSdk = require('onlinepayments-sdk-nodejs');

const directSdk = onlinePaymentsSdk.init({
    integrator: '[your-company-name]', // used for identification in logs
    host: 'payment.preprod.direct.worldline-solutions.com', // Note: Use the endpoint without the /v2/ part here. This endpoint is pointing to the TEST server
    scheme: 'https', // default
    port: 443, // default
    enableLogging: true, // defaults to false
    logger: logger, // if undefined console.log will be used
    apiKeyId: '[your-api-key-id]',
    secretApiKey: '[your-secret-api-key]'
});

Le tableau suivant fournit un aperçu des arguments acceptés par les instances individuelles :

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

Utiliser le SDK

Après l'initialisation réussie de l'instance de directSdk, vous avez un accès complet à notre API RESTful. Cela vous permet de :

• Envoyer des demandes pour de nouvelles transactions pour l'une de nos modes d'intégration côté serveur.
• Obtenir le statut actuel de vos transactions.
• Effectuer des demandes de maintenance (c'est-à-dire, captures, remboursements) sur des transactions existantes.

Consultez nos cas de test sur GitHub, y compris des exemples de code complets, et notre référence complète de l'API pour découvrir ce qui est possible.

Ci-dessous, vous trouverez certaines des actions les plus courantes que vous pouvez effectuer :

• 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 une instance de directSdk pour l'une de nos modes d'intégration. Cela peut être fait par :

• Routage de la demande vers votre PSPID sur notre plateforme (pour directSdk).
• Création d'une demande pour les modes d'intégration respectives.

Obtenir le statut d'une transaction

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

• GetHostedCheckout
• GetPaymentDetails
• GetCaptures
• GetRefunds

Une requête GetPaymentDetails ressemble à ceci :

const merchantId = "PSPID";
const sdkResponse = await directSdk.payments.getPaymentDetails(merchantId, 'PAYMENT_ID',{});

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

Effectuer une opération de maintenance

Pour effectuer des actions de suivi sur les transactions existantes (ex. : captures ou remboursements), utilisez respectivement notre appel API CapturePayment ou RefundPayment :

CapturePayment

/* 
 *…. Initialisation....
 */
const merchantId = "PSPID";
const sdkResponse = await directSdk.payments.capturePayment(
merchantId,
"PAYMENT_ID",
{
amount: 2980,
isFinal: true,
},
{}
);

RefundPayment

/*  
 *…. Initialisation.... 
 */ 
 
const merchantId = "PSPID";
const sdkResponse = await directSdk.payments.refundPayment(
merchantId,
"PAYMENT_ID",
{
amountOfMoney: {
currencyCode: "EUR",
amount: 1,
},
},
{}
);

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

const merchantId = "PSPID";
const sdkResponse= await directSdk.hostedCheckout.createHostedCheckout(
merchantId,
{
order: {
amountOfMoney: {
currencyCode: "USD",
amount: 2345,
},
customer: {
merchantCustomerId: "1234",
billingAddress: {
countryCode: "US",
},
},
},
hostedCheckoutSpecificInput: {
variant: "testVariant",
locale: "en_GB",
},
},
{}
);

Cet appel renvoie une réponse CreateHostedCheckoutResponse. Stockez le hostedCheckoutId et le RETURNMAC qu'il contient, ainsi que toute autre information pertinente pour vous. Vous en aurez besoin pour les étapes décrites dans les chapitres suivants.

Cette réponse contient également une partialRedirectURL.

Vous devez concaténer l'URL de base "https://payment." avec partialRedirectURL selon la formule

https://payment. + partialRedirectURL

et effectuer une redirection de votre client vers cette URL. Une fois que le client visite le Hosted Checkout Page, le processus de paiement continue là-bas.

Hosted Tokenization Page

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

• Créer et télécharger un modèle comme décrit dans notre guide Page de Tokenisation Hébergée

// Initialisation

const merchantId = "PSPID";
const sdkResponse = await directSdk.hostedTokenization.createHostedTokenization(
merchantId,
{
askConsumerConsent: true,
locale: "en_GB",
variant: 'YOUR_TEMPLATE.html',
}, 
{}
);

À partir de sdkResponse, récupérez hostedTokenizationId et partialRedirectUrl. Utilisez partialRedirectUrl pour l'iframe et hostedTokenizationId ou tokenId (voir encadré d'information) pour créer le paiement réel via la méthode d'intégration Server-to-server.

// Initialisation

const merchantId = "PSPID";
const sdkResponse = await directSdk.payments.createPayment(
merchantId,
{
cardPaymentMethodSpecificInput: {
card: {
cvv: "123",
cardNumber: "4567350000427977",
expiryDate: "1220",
cardholderName: "Wile E. Coyote",
},
token: 'TOKEN_FROM_HOSTED_TOKENIZATION_RESPONSE',
},
order: {
amountOfMoney: {
currencyCode: "EUR",
amount: 2980,
},
},
},
  {}
);

Server-to-server

Une réponse de paiement minimale paymentResponse nécessite au moins de définir un objet Order et une méthode de paiement :

// The example object of the AmountOfMoney
 const merchantId = "PSPID";
const sdkResponse = await directSdk.payments.createPayment(
merchantId,
{
cardPaymentMethodSpecificInput: {
card: {
cvv: "123",
cardNumber: "4567350000427977", // // Find more test data here 
expiryDate: "1220",
cardholderName: "Wile E. Coyote",
},
paymentProductId: 3,
},
order: {
amountOfMoney: {
currencyCode: "EUR",
amount: 2980,
},
},
},
{}
);

Gérer les exceptions

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

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

Exceptions de transaction

Ce type d'exception concerne les demandes de transaction qui sont techniquement correctes mais qui ont été rejetées par l'émetteur de votre client ou par votre acquéreur. Si la transaction est renvoyé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
const merchantId = "PSPID";
let paymentId = null;
try {
paymentId = directSdk.payments.createPayment(merchantId, {}, {});
} catch (error) {
console.error(error);
return;
}

const payment = await directSdk.payments.getPayment(merchantId, paymentId, {});

if (isNotSuccessful(payment)) {
handleError(payment);
}

// Initialisation
const merchantId = "PSPID";
const payId = "PAY_ID";
let refundId = null;
try {
refundId = await sdkInstance.payments.refundPayment(
merchantId,
payId,
{
amountOfMoney: {
currencyCode: "EUR",
amount: 1,
},
},
{}
);
} catch (error) {
console.error(error);
return;
}
const refunds = await directSdk.refunds.getRefunds(merchantId, payId, {});
if (isNotSuccessful(refunds, refundId)) {
handleError(refunds);
}

Exceptions HTTP

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

Vous pouvez combiner l'un des extraits de code suivants avec cette requête standard CreatePayment :

// Initialisation
const merchantId = "PSPID";
const sdkResponse = null;
try {
sdkResponse = await directSdk.payments.createPayment(
merchantId,
{
cardPaymentMethodSpecificInput: {
card: {
cvv: "123",
cardNumber: "4567350000427977",
expiryDate: "1220",
cardholderName: "Wile E. Coyote",
},
paymentProductId: 3,
},
order: {
amountOfMoney: {
currencyCode: "EUR",
amount: 2980,
},
},
},
{}
);
} catch (error) {
// quelque chose a mal tourné, enregistrons-le...
console.error(error);
return;
}
if (sdkResponse.errors.length > -1) {
// nous avons une erreur spécifique 
sdkResponse.forEach((error) => {
// votre logique de gestion des erreurs
console.error(error);
});
}

if (response.status === 400) {
console.log("Erreur de validation de l'entrée :");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}

if (response.status === 403) {
console.log("Erreur d'autorisation :");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}

if (response.status === 409) {
console.log("Erreur d'idempotence :");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}

if (
response.status === 404 ||
response.status === 409 ||
response.status === 410
) {
console.log("Référence d'objet incorrecte :");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}

if (
response.status === 500 ||
response.status === 502 ||
response.status === 503
) {
console.log("Erreur survenue chez Direct ou un partenaire/acquéreur en aval :");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}

if (response.errors.length > -1) {
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}

if (response.status.match(/3[0-9]{2}\b/)) {
console.log("Erreur de communication :");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}

Codes de statut HTTP

Toutes nos exceptions sont liées à un ou plusieurs codes de statut HTTP, indiquant la cause principale de nombreuses erreurs possibles.

DeclinedPaymentException

DeclinedPayoutException

DeclinedRefundException

ValidationException

AuthorizationException

ReferenceException

IdempotenceException
ReferenceException

ReferenceException

PlatformException

PlatformException

PlatformException

ApiException

Fonctionnalités supplémentaires

Le SDK a beaucoup plus à offrir. Jetez un œil aux 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
• Webhooks

Obtenir les méthodes de paiement disponibles

Avant d'initier le processus de paiement réel, vous envoyez une requête GetPaymentProducts à notre plateforme. La réponse contient une liste des méthodes de paiement disponibles dans votre PSPID. Selon les préférences de vos clients, vous pouvez offrir une sélection sur notre Hosted Checkout Page ou sur votre propre environnement de boutique en ligne en utilisant des requêtes CreatePayment ultérieures.

// Initialisation
const merchantId = "PSPID"

const paymentProducts = await directSdk.products.getPaymentProducts(merchantId, {
countryCode: 'NL',
currencyCode: 'EUR',
});

Envoyer des requêtes idempotentes

L'une des principales fonctionnalités de l'API REST est sa capacité à détecter et à éviter l'envoi de requêtes (par exemple, des requêtes de paiement) accidentellement en double. Le SDK rend très facile pour vous de vous assurer que vous envoyez uniquement des requêtes uniques – idempotentes – à notre plateforme.

Utilisez l'argument supplémentaire paymentContext et définissez sa propriété nommée idempotence sur une requête 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 demande ultérieure 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é idempotence.requestTimestamp de l'argument CallContext.
• Si la première requête n'est pas encore terminée, l'API du serveur RESTful renvoie un code de statut 409. Ensuite, le SDK lance une IdempotenceException avec la clé d'idempotence originale et l'horodatage de la requête d'idempotence.

// Initialisation
const merchantId = "PSPID";
const idempotenceKey = newUUID();
const paymentContext: PaymentContext = {
idempotence: {
key: idempotenceKey
}
};
directSdk.payments.createPayment(
merchantId,
{
cardPaymentMethodSpecificInput: {
card: {
cvv: "123",
cardNumber: "4567350000427977",
expiryDate: "1220",
cardholderName: "Wile E. Coyote",
},
paymentProductId: 3,
},
order: {
amountOfMoney: {
currencyCode: "EUR",
amount: 2980,
},
},
},
paymentContext,
(error, sdkResponse) => {
if (paymentContext.idempotence.requestTimestamp) {
// this call is made with idempotence and is still being handled
console.log(
"idempotence timestamp",
paymentContext.idempotence.requestTimestamp
);
}
}
);

Utiliser la logging

Le SDK prend en charge la logging des requêtes, des réponses et des exceptions de la communication API. Cela peut être utile pour le dépannage ou le suivi des étapes individuelles dans le flux de paiement.

Pour utiliser cette fonctionnalité de logging, vous devez implémenter l'interface CommunicatorLogger.

Le SDK propose deux implémentations de la fonctionnalité de logging :

• System.out (SysOutCommunicatorLogger)
• java.util.logging.Logger (JdkCommunicatorLogger)

Pour utiliser cette fonctionnalité, fournissez une implémentation de l'interface Logger. Vous pouvez activer/désactiver la journalisation en appelant setLogger sur un objet directSdk.context et en fournissant le logger comme argument logger.

Webhooks

La partie du SDK qui gère la prise en charge des webhooks est appelée le webhooks helper. Elle 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 identifiants de clé - à ne pas confondre avec la API Key et le API Secret ), et le dé-marquage de ces corps vers des objets. Cela vous permet de vous concentrer sur l'essentiel, sans parcourir toutes les informations supplémentaires et les extraire vous-même. Pour en savoir plus sur les webhooks, lisez notre guide dédié. 

Fournir des clés secrètes

Configurez les "WebhooksKey" / "WebhooksKeySecret" et les 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 clé pour retourner la clé secrète.
• Une fonction de rappel qui prend soit une erreur en tant que premier argument, soit la clé secrète pour l'ID de clé donnée en tant que deuxième argument (dans ce cas, le premier argument doit être nul).

Le SDK fournit une implémentation pour cette fonction : webhooks.inMemorySecretKeyStore.getSecretKey. Cela récupérera les clés secrètes à partir d'un magasin de clés en mémoire.

Vous pouvez ajouter ou supprimer des clés en utilisant les fonctions suivantes :

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

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

Initialiser le webhooks helper

Incluez et initialisez le webhooks helper comme suit :

// Initialisation
const webhooks = require("direct-sdk-nodejs").webhooks;
// remplacez webhooks.inMemorySecretKeyStore.getSecretKey par votre propre fonction si nécessaire
webhooks.init({
    getSecretKey: webhooks.inMemorySecretKeyStore.getSecretKey,
});

Utiliser le webhooks helper

Depuis un point d'entrée que vous avez créé vous-même, appelez la méthode unmarshal de l'instance du webhooks helper:

• Le corps en tant que string ou tampon. Cela devrait ê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
const webhooks = require("direct-sdk-nodejs").webhooks;
const webhooksHelper = webhooks.init();
webhooksHelper.unmarshal(body, requestHeaders, (error, event) => {
  if (error) {
    // something went wrong in validating the signature or unmarshalling the event
  } else {
    // process the event
  }
});