Guide d'implémentation du connecteur Stripe pour Salesforce B2C Commerce

Configurer Business Manager

Plusieurs cartouches sont nécessaires pour que le connecteur Stripe pour Salesforce B2C Commerce (cartouche LINK) fonctionne pleinement. En outre, la prise en charge contrôleur et SFRA est répartie entre deux cartouches distinctes, ce qui facilite l’installation et l’utilisation des différents modèles.

Importer les trois cartouches dans UX studio et les associer à une connexion au serveur.

Attribution des cartouches au site

Rendez-vous sur Administration > Sites > Manage Sites.
Cliquez sur le nom du site pour le site de vitrine auquel vous souhaitez ajouter la fonctionnalité Stripe.
Sélectionnez l’onglet Settings.
Pour l’architecture de référence de vitrine (SFRA), ajoutez app_stripe_sfra:int_stripe_sfra:int_stripe_core au chemin d’accès de la cartouche.

Répétez ces étapes pour chaque site de vitrine où vous souhaitez implémenter Stripe.

Attribution d’une cartouche à Business Manager

Rendez-vous sur Administration > Sites > Manage Sites.
Cliquez sur le Business Manager Site, puis sur le lien Manage the Business Manager site.
Ajoutez int_stripe_core au chemin d’accès Cartridges:.

Importation de métadonnées

Accédez au dossier des métadonnées du projet et ouvrez le dossier stripe_site_template.
Ouvrez le dossier des sites et renommez le dossier siteIDHere avec l’identifiant du site que vous voulez.
Ajoutez un dossier pour chaque site sur lequel vous souhaitez activer Stripe.
Rendez-vous sur Administration > Site Development > Site Import & Export.
Compressez le dossier stripe_site_template dans un fichier zip et importez-le.

Créer un style Stripe

Si nécessaire, mettez à jour le chemin d’accès à votre installation SFRA de base dans package.json à partir du même dossier racine.

En temps normal, il y a un dossier de projet de premier niveau dans lequel seraient clonés les référentiels de la cartouche SFRA de base et l’ensemble des modules d’extension, des bibliothèques et des autres cartouches LINK requises. Si vous avez également cloné la cartouche Stripe dans ce dossier, vous n’avez pas à mettre à jour la propriété paths.base. Si vous n’avez pas cloné la cartouche dans ce dossier, mettez à jour la propriété paths.base dans package.json en intégrant le chemin d’accès correspondant vers le répertoire local contenant le référentiel de l’architecture de référence de la vitrine. Voici la valeur par défaut de paths.base :

"paths": {
  "base": "../storefront-reference-architecture/cartridges/app_storefront_base/"
}

Dès que vous aurez la certitude que package.json a le bon chemin d’accès vers les cartouches SFRA, exécutez la commande npm run compile:scss à partir du dossier racine du référentiel Stripe.

Ajouter de nouveaux prestataires de services de paiement

La cartouche Stripe utilise deux prestataires de services de paiement. STRIPE_CREDIT gère les paiements par carte de crédit, alors que STRIPE_APM gère les modes de paiement par l’entremise de Payment Element et d’Express Checkout Element.

Prestataire de services de paiement par carte de crédit

Rendez-vous sur Outils du marchand > Commande > Traitement de paiements, et cliquez sur Nouveau.
Dans la fenêtre qui s’ouvre, sélectionnez la valeur STRIPE_CREDIT en tant qu’attribut de l’identifiant et cliquez sur Apply.

Prestataire de services de paiement APM

Rendez-vous sur Outils du marchand > Commande > Traitement de paiements, et cliquez sur Nouveau.
Dans la fenêtre qui s’ouvre, sélectionnez la valeur STRIPE_APM en tant qu’attribut de l’identifiant et cliquez sur Apply.

Mettre à jour des moyens de paiement

Rendez-vous sur Outils du marchand > Commandes > Moyens de paiement, cliquez sur le moyen de paiement CREDIT_CARD et sélectionnez le prestataire de services de paiement STRIPE_CREDIT dans la liste déroulante, sous la section des détails de CREDIT_CARD.

Pour les modes de paiement dynamiques ou le bouton de demande de paiement, activez STRIPE_APM_METHODS pour inclure les modes de paiement pris en charge par Stripe. Pour en savoir plus, consultez le guide sur les modes de paiement.

Pour utiliser le bouton de demande de paiement Stripe, activez le mode de paiement STRIPE_PAYMENT_REQUEST_BTN. Pour en savoir plus, consultez l’article sur le bouton de demande de paiement.

Installer l’application Stripe Salesforce Commerce

Utilisez Stripe Apps pour renforcer la sécurité et simplifier l’utilisation de clés limitées distinctes pour chaque intégration avec votre compte Stripe. Le processus d’installation de l’application Stripe et d’acquisition des clés secrètes et publiables nouvellement générées est essentiel pour votre intégration avec le connecteur Salesforce Commerce. Cette approche élimine la nécessité de créer manuellement votre propre clé limitée ou d’utiliser une clé secrète. Pour intégrer l’application Salesforce Commerce et renforcer l’infrastructure de sécurité de votre compte :

Accédez à Stripe App Marketplace, puis cliquez sur Installer l’application Salesforce Commerce.
Sélectionnez le compte Stripe sur lequel vous souhaitez installer l’application.
Vérifiez et approuvez les autorisations de l’application, installez l’application dans un environnement de test ou en mode production, puis cliquez sur Installer.
Après avoir installé l’application, conservez les clés dans un endroit sûr où vous ne risquez pas de les perdre. Pour vous aider à vous souvenir de l’endroit où vous la conservez, vous pouvez laisser une note à propos des clés dans le Dashboard.
Utilisez la clé publique et la clé secrète nouvellement générées pour terminer la configuration du connecteur.
Pour gérer l’application ou générer de nouvelles clés de sécurité après l’installation, accédez à la page des paramètres de l’application dans un bac à sable ou en mode production.

Configuration

Mettez à jour ** les outils du marchand > les préférences du site > les préférences du site > les configurations Stripe ** avec les valeurs propres au site.

Remplissez la clé API secrète de Stripe avec les valeurs de l’application Stripe Salesforce Commerce.
Remplissez la clé API publiable avec les valeurs de l’application Stripe Salesforce Commerce.
S’il s’agit d’une installation SFRA, choisissez yes si le site actuel utilise l’architecture de référence de vitrine (SFRA).
Capture des fonds sur le paiement Stripe : La valeur par défaut est true (Oui). Réglez sur false (Non) pour autoriser les frais Stripe à la place.
** Style CSS de l’élément de carte Stripe :** Définissez le style CSS que le bouton de l’élément de carte hérite pour s’adapter au style global de la vitrine (par exemple, {"base" : {"fontFamily" : "Arial, sans-serif", "fontSize" : "14px", "color" : "# C1C7CD"}, "invalid" : {"color" : "red" } }).
Stripe API URL: https://js.stripe.com/basil/stripe.js
**Style de bouton de demande de paiement Stripe : ** Pour le bouton de demande de paiement, sélectionnez le style CSS limité pour le bouton. Pour en savoir plus, consultez la section Styliser l’élément.
Chaîne de vérification ApplePay : saisissez la chaîne de vérification Apple fournie par le Dashboard Stripe. Il s’agit d’une activation ponctuelle. La console Stripe sert de proxy à Apple Pay aux fins de la chaîne de vérification Web au moment de la configuration. Il est nécessaire de la configurer dans le bac à sable (sandbox) si l’élément Payment Request Button est utilisé en tant que moyen de paiement sur la vitrine.
** Code de pays (bouton de demande de paiement Stripe) :** Il s’agit du code de pays par défaut (par exemple, É.-U.) du bouton de demande de paiement. Vous pourriez avoir besoin de personnaliser sur un site international et transmettre de manière dynamique le code de pays plutôt que les préférences du site. Pour en savoir plus, consultez l’article Créer une instance de demande de paiement.
Clé secrète de signature du webhook Stripe : Entrez la clé secrète de signature webhook fournie par le Dashboard Stripe. Stripe signe les événements webhook et transmet une validation à SFCC. SFCC valide le contenu du message à l’aide de ce secret.
** États de webhook autorisés de Stripe :** Configurez les états autorisés auxquels les webhooks doivent répondre.
Stripe Enabled : active ou désactive la cartouche.

Configuration rapide de Stripe

Vous pouvez également configurer Stripe dans Business Manager à l’aide de Configuration rapide de Stripe

Connectez-vous à votre Business Manager.
Recherchez « Configuration rapide de Stripe » dans Business Manager sous Administration.
Sélectionnez les sites pour lesquels vous souhaitez configurer Stripe.
Saisissez votre Stripe Publishable Key et votre Restricted Access key récupérées de l’application Stripe Salesforce Commerce.
Cliquez sur Configuration rapide.

Configurez Apple Pay

Pour Apple Pay :

Mettre à jour de RedirectURL.js :

RedirectURL.js
server.extend(page);

server.replace('Start', function (req, res, next) {
  const URLRedirectMgr = require('dw/web/URLRedirectMgr');

  // Intercept the incoming path request
  if (URLRedirectMgr.getRedirectOrigin() === '/.well-known/apple-developer-merchantid-domain-association') {
    res.render('stripe/util/apple');
    return next();
  }

  const redirect = URLRedirectMgr.redirect;
  const location = redirect ? redirect.location : null;
  const redirectStatus = redirect ? redirect.getStatus() : null;

  if (!location) {
    res.setStatusCode(404);
    res.render('error/notFound');
  } else {
    if (redirectStatus) {
      res.setRedirectStatus(redirectStatus);
    }
    res.redirect(location);
  }

  return next();
});

Définissez temporairement un alias pour l’un des sites dans le bac à sable afin que le domaine puisse être vérifié dans le Dashboard Stripe. L’alias doit ressembler à ce qui suit :

{
  "__version": "1",
    "settings": {
      "http-host": "your.sandbox.domain.demandware.net",
      "https-host": "your.sandbox.domain.demandware.net",
      "default": "true",
      "site-path": "/",
  },
  "your.sandbox.domain.demandware.net": [
    {
      "locale": "en_GB",
      "if-site-path": "/",
    }
  ]
}

La valeur des paramètres régionaux doit être activée.

Dans la page Domaines des modes de paiement, cliquez sur Ajouter un nouveau domaine.
Saisissez votre nom de domaine.
Cliquez sur Enregistrer et continuer.
Téléchargez le fichier d’association de domaine.
Hébergez le fichier dans /.well-known/apple-developer-merchantid-domain-association. Par exemple, si vous enregistrez https://example.com, rendez ce fichier disponible à l’adresse https://example.com/.well-known/apple-developer-merchantid-domain-association.
Cliquez sur Vérifier.

Mettre à jour le code de la vitrine

Le code de la cartouche LINK contient une prise en charge de l’ensemble des cartes de crédit prises en charge par Stripe. Veuillez noter que la liste des cartes autorisées sur la vitrine se limite toujours à la liste des cartes de crédit et de débit de Business Manager (Outils du marchand > Commande > Moyens de paiement > Cartes de débit/crédit).

Apportez les modifications suivantes au code de vitrine. Les exemples cités sont basés sur SFRA version 4.4. Les sections suivantes détaillent les personnalisations apportées au code SFRA.

Il existe de nombreux points de terminaison de contrôleur qui sont des ajouts plutôt que des remplacements. Ils ne sont pas couverts puisqu’ils devraient fonctionner sans intervention de votre part.

Les mises à jour du contrôleur sont requises uniquement pour les points de terminaison remplacés, puisque vous avez peut-être déjà remplacé ce point de terminaison dans votre intégration. Utilisez simplement les modifications apportées à la cartouche de base et ajoutez-les au contrôleur que vous avez déjà remplacé. Si vous n’avez pas étendu/remplacé ces points de terminaison, vous n’avez rien à faire.

Contrôleur : CheckoutServices.js

Chemin d’accès : app_stripe_sfra/cartridge/controllers/CheckoutServices.js

Retirez la validation du mode de paiement dans le point de terminaison SubmitPayment :

CheckoutServices.js
if (!paymentMethodID && currentBasket.totalGrossPrice.value > 0) {
  const noPaymentMethod = {};

  noPaymentMethod[billingData.paymentMethod.htmlName] = Resource.msg(
    'error.no.selected.payment.method',
    'payment',
    null
  );

  delete billingData.paymentInformation;
  res.json({
    form: billingForm,
    fieldErrors: [noPaymentMethod],
    serverErrors: [],
    error: true
  });
  return;
}

// Validate payment method
const creditCardPaymentMethod = PaymentMgr.getPaymentMethod(PaymentInstrument.METHOD_CREDIT_CARD);
const paymentCard = PaymentMgr.getPaymentCard(billingData.paymentInformation.cardType.value);

const applicablePaymentCards = creditCardPaymentMethod.getApplicablePaymentCards(
  req.currentCustomer.raw,
  req.geolocation.countryCode,
  null
);

if (!applicablePaymentCards.contains(paymentCard)) {
  // Invalid payment method
  const invalidPaymentMethod = Resource.msg('error.payment.not.valid', 'checkout', null);
  delete billingData.paymentInformation;
  res.json({
    form: billingForm,
    fieldErrors: [],
    serverErrors: [invalidPaymentMethod],
    error: true
  });
  return;
}

Mettez le code de création de commande à jour :

CheckoutServices.js
// Re-calculate the payments
const calculatedPaymentTransactionTotal = COHelpers.calculatePaymentTransaction(currentBasket);
if (calculatedPaymentTransactionTotal.error) {
  res.json({
      error: true,
      errorMessage: Resource.msg('error.technical', 'checkout', null);
  });
  return next();
}
const stripeCheckoutHelper = require('int_stripe_core').getCheckoutHelper();
const order = stripeCheckoutHelper.createOrder(currentBasket);

if (!order) {
  res.json({
    error: true,
    errorMessage: Resource.msg('error.technical', 'checkout', null);
  });
  return next();
}

Mettez le code de création de commande à jour :

CheckoutServices.js
var isAPMOrder = stripeCheckoutHelper.isAPMORder(order);

if (!isAPMOrder) {
  var stripePaymentInstrument = stripeCheckoutHelper.getStripePaymentInstrument(order);

  if (stripePaymentInstrument && order.custom.stripeIsPaymentIntentInReview) {
    res.json({
      error: false,
      orderID: order.orderNo,
      orderToken: order.orderToken,
      continueUrl: URLUtils.url('Order-Confirm').toString()
    });

    return next();
  }
  // Places the order
  var placeOrderResult = COHelpers.placeOrder(order, fraudDetectionStatus);

  if(placeOrderResult.error) {
    stripeCheckoutHelper.refundCharge(order);
    res.json({
      error: true,
      errorMessage: Resource.msg('error.technical', 'checkout', null)
    });
  const fraudDetectionStatus = hooksHelper(
    'app.fraud.detection',
    'fraudDetection',
    currentBasket,
    require('*/cartridge/scripts/hooks/fraudDetection').fraudDetection
  );

  if (fraudDetectionStatus.status === 'fail') {
    Transaction.wrap(function () {
      OrderMgr.failOrder(order);
    });

    // Fraud detection failed
    req.session.privacyCache.set('fraudDetectionStatus', true);

    res.json({
      error: true,
      cartError: true,
      redirectUrl: URLUtils.url('Error-ErrorCode', 'err', fraudDetectionStatus.errorCode).toString(),
      errorMessage: Resource.msg('error.technical', 'checkout', null);
    });
    return next();
  }
  COHelpers.sendConfirmationEmail(order, req.locale.id);

  // Reset usingMultiShip after successful Order placement
  req.session.privacyCache.set('usingMultiShip', false);

  res.json({
    error: false,
    orderID: order.orderNo,
    orderToken: order.orderToken,
    continueUrl: URLUtils.url('Order-Confirm').toString()
  });

  return next();
}

Contrôleur : PaymentInstruments.js

Chemin d’accès : app_stripe_sfra/cartridge/controllers/PaymentInstruments.js

Remplacer le point de terminaison DeletePayment par le code suivant :

PaymentInstruments.js
server.replace('DeletePayment', function(req, res, next) {
  var stripeHelper = require ('int_stripe_core').getStripeHelper();
  var wallet = stripeHelper.getStripeWallet(customer);
  var UUID = req.querystring.UUID;
  wallet.removePaymentInstrument({ custom: { stripeId: UUID }});

  res.json({  UUID: UUID });
  next();
});

Contrôleur : RedirectURL.js

Chemin d’accès : app_stripe_sfra/cartridge/controllers/RedirectURL.js

Ajouter le code suivant à la fonction Start :

RedirectURL.js
server.replace('Start', function (req, res, next) {
  const URLRedirectMgr = require('dw/web/URLRedirectMgr');

  // Intercept the incoming path request
  if (URLRedirectMgr.getRedirectOrigin() === '/.well-known/apple-developer-merchantid-domain-association') {
    res.render('stripe/util/apple');
    return next();
  }

  const redirect = URLRedirectMgr.redirect;
  const location = redirect ? redirect.location : null;
  const redirectStatus = redirect ? redirect.getStatus() : null;

  if (!location) {
    res.setStatusCode(404);
    res.render('error/notFound');
  } else {
    if (redirectStatus) {
      res.setRedirectStatus(redirectStatus);
    }
    res.redirect(location);
  }

  return next();
});

Interfaces externes

La fonctionnalité Stripe repose en grande partie sur les appels externes aux services de Stripe. Toutes les interfaces externes utilisent le cadre de service pour communiquer avec l’API Stripe.

La création et l’utilisation des comptes Stripe sont gratuites. La plupart des communications avec les services de Stripe sont archivées et facilement accessibles dans le Dashboard Stripe. Nous vous recommandons d’utiliser le Dashboard Stripe pour contrôler et tester votre intégration. Vous pouvez trouver la configuration principale de l’intégration des services Stripe sur Administration > Opérations > Services avec un service propre à chaque appel externe :

stripe.http.addCard
stripe.http.authorizePayment
stripe.http.createCharge
stripe.http.createCustomer
stripe.http.deleteCard
stripe.http.fetchCustomerCards
stripe.http.fetchCustomerSources
stripe.http.refundCharge
stripe.http.retrieveCustomer
stripe.http.service
stripe.http.updateCard

Tous ces services utilisent le même profil et les mêmes identifiants de connexion. La seule chose susceptible de varier est le fait de savoir si le journal des communications est activé ou non, ainsi que le préfixe du nom du journal. Voici la configuration de certains de ces services :

Payment Element Stripe

La cartouche Stripe prend en charge Payment Element Stripe en tant que moyen de paiement.

Payment Element est un composant d’interface utilisateur intégré qui vous permet d’accepter plus de 25 moyens de paiement à l’aide d’une seule intégration.

Pour activer Payment Element, accédez à Gestionnaire des transferts > Outils du marchand > Commande > Moyens de paiement et activez le moyen de paiement avec ID = STRIPE_PAYMENT_ELEMENT.In storefront Checkout > Payment, il y a un widget avec tous les moyens de paiement activés dans Stripe > Paramètres > Moyens de paiement Dashboard.

Lorsque vous activez Payment Element dans Business Manager, il peut remplacer tous les autres moyens de paiement. Vous pouvez désactiver les moyens de paiement et utiliser STRIPE_PAYMENT_ELEMENT à la place.

Pour activer l’enregistrement de moyens de paiement pour utilisation ultérieure à partir de Stripe Payment Element, accédez à Business Manager > Préférences personnalisées > Configurations Stripe et définissez Stripe Payment Element : Activer l’enregistrement du moyen de paiement pour les achats futurs à Yes.

Pour afficher une liste des moyens de paiement enregistrés lors de la commande, accédez à **Business Manager > Moyens de paiement ** et activez le moyen de paiement CREDIT_CARD. Lorsqu’il est activé avec STRIPE_PAYMENT_ELEMENT, l’onglet carte de crédit inclut une liste des cartes enregistrées (le cas échéant).

Affichage des données Stripe Radar

La cartouche Stripe LINK prend en charge la vue d’informations Radar pour présenter les informations sur les risques dans la section Commandes du Business Manager. Radar offre une protection contre la fraude en temps réel sans exiger de développement supplémentaire. Les professionnels de la lutte contre la fraude peuvent ajouter Radar for Fraud Teams pour personnaliser leur protection et obtenir des informations plus détaillées.

Pour activer l’affichage des données, accédez à Gestionnaire des transferts > Outils du marchand > Préférences personnalisées > Configurations Stripe et sélectionnez Yes pour les données sur l’indice de risque.