Implementierungsleitfaden für Stripe Connector for Salesforce B2C Commerce

Business Manager einrichten

Der Stripe Connector for Salesforce B2C Commerce (LINK Cartridge) erfordert für die volle Funktionalität mehrere Cartridges. Darüber hinaus ist die Controller- und SFRA-Unterstützung in zwei separate Cartridges unterteilt, wodurch die Installation und Verwendung des einen oder anderen Modells erleichtert wird.

Importieren Sie alle drei Cartridges in UX Studio und verknüpfen Sie sie mit einer Serververbindung.

Website-Cartridge-Zuweisung

Navigieren Sie zu Administration > Sites > Manage Sites (Administration > Websites > Websites verwalten).
Klicken Sie auf den Namen der Storefront-Website, zu der Sie Stripe Funktionen hinzufügen möchten.
Wählen Sie die Registerkarte Settings (Einstellungen).
Für die Storefront Reference Architecture (SFRA) fügen Sie app_stripe_sfra:int_stripe_sfra:int_stripe_core zum Cartridge-Pfad hinzu.

Wiederholen Sie diese Schritte für jede Storefront-Site, auf der Sie Stripe implementieren möchten.

Zuweisung der Business Manager Cartridge

Navigieren Sie zu Administration > Sites > Manage Sites (Administration > Websites > Websites verwalten).
Klicken Sie auf Business Manager Site (Business Manager-Website) und dann auf den Link Manage the Business Manager site (Business Manager-Website verwalten).
Fügen Sie int_stripe_core zum Pfad „Cartridges:“ hinzu.

Metadaten-Import

Navigieren Sie zum Metadaten-Ordner des Projekts und öffnen Sie den Ordner stripe_site_template.
Öffnen Sie den Ordner sites und ändern Sie den Ordner siteIDHere in die Site-ID der gewünschten Site.
Fügen Sie einen Ordner für jede Website hinzu, die Sie mit Stripe verwenden möchten.
Navigieren Sie zu Administration > Site Development > Site Import & Export (Administration > Website-Entwicklung > Website-Import und -Export).
Komprimieren Sie den Ordner stripe_site_template in eine ZIP-Datei und importieren Sie sie.

Stripe-Styling erstellen

Aktualisieren Sie bei Bedarf in package.json im selben Stammverzeichnis den Pfad zu Ihrer SFRA-Basisinstallation.

Normalerweise gibt es einen übergeordneten Projektordner, in den die Repositorys der SFRA-Basis-Cartridge und aller erforderlichen Plugins, Bibliotheken und aller anderen LINK-Cartridges geklont werden. Wenn Sie die Stripe-Cartridge auch in diesen Ordner geklont haben, müssen Sie die Eigenschaft paths.base nicht aktualisieren. Wenn Sie die Cartridge nicht in diesen Ordner geklont haben, aktualisieren Sie die Eigenschaft paths.base in package.json mit dem relativen Pfad zu dem lokalen Verzeichnis, das das Storefront Reference Architecture-Repository enthält. Der folgende Standardwert für paths.base ist:

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

Wenn Sie sicher sind, dass package.json über den korrekten Pfad zu den SFRA-Cartridges verfügt, führen Sie den Befehl npm run compile:scss aus dem Stammverzeichnis des Stripe -Repositorys aus.

Neue Zahlungsabwickler hinzufügen

Es gibt zwei Zahlungsabwickler, die in der Stripe-Cartridge verwendet werden. STRIPE_CREDIT wickelt nur Kreditkartenzahlungen ab, während STRIPE_APM Zahlungsmethoden über Payment Element und Express Checkout Element abiwickelt.

Zahlungsabwickler für Kreditkarten

Klicken Sie unter Merchant Tools“ (Händlertools) > Ordering (Bestellungen) > Payment Processors (Zahlungsabwickler) auf New (Neu).
Legen Sie im neuen Fenster die ID auf STRIPE_CREDIT fest und klicken Sie auf Übernehmen.

Zahlungsabwickler für alternative Zahlungsmethoden (APM)

Klicken Sie unter Merchant Tools“ (Händlertools) > Ordering (Bestellungen) > Payment Processors (Zahlungsabwickler) auf New (Neu).
Legen Sie im neuen Fenster das ID-Attribut auf den Wert STRIPE_APM fest und klicken Sie auf Übernehmen.

Zahlungsmethoden aktualisieren

Klicken Sie unter Merchant Tools (Händlertools) > Ordering (Bestellungen) > Payment Methods (Zahlungsmethoden) auf die Zahlungsmethode CREDIT_CARD und wählen Sie im Abschnitt mit den Details zu CREDIT_CARD im Dropdown-Menü den Zahlungsabwickler STRIPE_CREDIT.

Damit bei dynamischen Zahlungsmethoden oder Verwendung der Schaltfläche für die Zahlungsanfrage alle von Stripe unterstützten Zahlungsmethoden angeboten werden können, aktivieren Sie STRIPE_APM_METHODS. Weitere Informationen finden Sie im Leitfaden zu Zahlungsmethoden.

Um die Stripe-Schaltfläche für die Zahlungsanfrage zu verwenden, aktivieren Sie die Zahlungsmethode STRIPE_PAYMENT_REQUEST_BTN. Weitere Informationen finden Sie im Abschnitt Schaltfläche für die Zahlungsanfrage.

Stripe Salesforce Commerce-App installieren

Verwenden Sie Stripe-Apps, um die Sicherheit zu erhöhen und die Verwendung unterschiedlicher eingeschränkter Schlüssel für jede Integration mit Ihrem Stripe-Konto zu vereinfachen. Der Prozess der Installation der Stripe-App und des Erwerbs der neu generierten geheimen und veröffentlichbaren Schlüssel ist für Ihre Integration mit dem Salesforce Commerce-Connector von wesentlicher Bedeutung. Dieser Ansatz macht es überflüssig, manuell einen eigenen eingeschränkten Schlüssel zu erstellen oder einen geheimen Schlüssel zu verwenden. So integrieren Sie die Salesforce Commerce-App und verstärken die Sicherheitsinfrastruktur Ihres Kontos:

Navigieren Sie zum Stripe App Marketplace und klicken Sie dann auf Install the Salesforce Commerce app (Salesforce Commerce-App installieren).
Wählen Sie das Stripe-Konto aus, in dem Sie die App installieren möchten.
Überprüfen und genehmigen Sie die App-Berechtigungen, installieren Sie die App im Test-Modus oder Live-Modus und klicken Sie dann auf Installieren.
Bewahren Sie die Schlüssel nach der Installation der App an einem sicheren Ort auf, an dem Sie sie nicht verlieren. Um sich daran zu erinnern, wo Sie sie gespeichert haben, können Sie eine Notiz zu dem Schlüssel im Dashboard hinterlassen.
Verwenden Sie den neu generierten veröffentlichbaren Schlüssel und den geheimen Schlüssel, um die Connector-Konfiguration abzuschließen.
Um die App zu verwalten oder nach der Installation neue Sicherheitsschlüssel zu generieren, navigieren Sie im Test-Modus oder im Live-Modus zur Seite mit den Anwendungseinstellungen.

Konfiguration

Passen Sie die Konfigurationen unter Merchant Tools (Händlertools) > Site Preferences (Website-Einstellungen) > Custom Site Preferences (Benutzerdefinierte Website-Einstellungen) > Stripe Configurations (Stripe-Konfigurationen) mit websitespezifischen Werten an.

Füllen Sie den geheimen Stripe-API-Schlüssel mit den Werten aus der Stripe Salesforce Commerce-App.
Veröffentlichen Sie den veröffentlichbaren API-Schlüssel mit den Werten aus der Stripe Salesforce Commerce-App.
Is this SFRA installation (Ist dies eine SFRA-Installation): Auf yes setzen, wenn die aktuelle Website die Storefront Reference Architecture (SFRA) verwendet.
Capture Funds on Stripe Charge (Bei Stripe-Zahlung Gelder erfassen): Der Standardwert ist true (Ja). Setzen Sie den Wert auf false (Nein), um stattdessen Stripe-Zahlungen zu autorisieren.
Stripe Card Element CSS Style (CSS-Stil des Stripe-Card-Elements): Legen Sie das CSS-Styling fest, das auf das Card-Element angewendet werden soll, um es an den allgemeinen Storefront-Stil anzupassen (z. B. {"base": {"fontFamily": "Arial, sans-serif","fontSize": "14px","color": "#C1C7CD"},"invalid": {"color": "red" } }).
Stripe API URL (URL der Stripe-API): https://js.stripe.com/v3/
Stripe Payment Request Button Style: (Stil der Stripe-Schaltfläche für Zahlungsanfragen): Wählen Sie für die Schaltfläche für die Zahlungsanfrage das eingeschränkte CSS-Styling aus. Weitere Einzelheiten finden Sie unter Stil für das Element festlegen.
Verifizierungszeichenfolge für Apple Pay: Geben Sie die im Stripe-Dashboard bereitgestellte Apple-Verifizierungszeichenfolge ein. Dies ist eine einmalige Aktivierung. Die Stripe-Konsole übermittelt bei der Einrichtung eine Web-Verifizierungszeichenfolge für Apple Pay. Konfigurieren Sie dies in der Sandbox, wenn Sie die Schaltfläche für Zahlungsanfragen als Zahlungsmittel in der Storefront verwenden.
Country Code (Ländercode) (Stripe-Schaltfläche für Zahlungsanfrage): Hierbei handelt es sich um den Standard-Ländercode (zum Beispiel U.S.) für die Schaltfläche für die Zahlungsanfrage. Auf einer Website für mehrere Länder ist möglicherweise eine Anpassung erforderlich, damit statt der Website-Einstellung der Ländercode dynamisch übergeben wird. Weitere Informationen finden Sie unter Zahlungsanfrageinstanz erstellen.
Stripe Webhook Signing Secret (Stripe-Webhook-Signaturgeheimnis): Geben Sie das vom Stripe-Dashboard bereitgestellte Webhook-Signaturgeheimnis ein. Stripe signiert Webhook-Ereignisse und übergibt eine Validierung an SFCC. SFCC validiert die Inhalte der Nachricht anhand dieses Geheimnisses.
Stripe allowed Webhook Statuses (Von Stripe zugelassene Webhook-Statusangaben): Konfigurieren Sie die zulässigen Statusangaben, auf die Webhooks reagieren sollen.
Stripe Enabled (Stripe aktiviert): Aktiviert oder deaktiviert die Cartridge.

Stripe Quick Setup

Alternativ können Sie Stripe im Business Manager über Stripe Quick Setup (Stripe-Schnelleinrichtung) konfigurieren.

Melden Sie sich bei Ihrem Business Manager an.
Suchen Sie im Business Manager unter Administration nach „Stripe Quick Setup“ (Stripe-Schnelleinrichtung).
Wählen Sie die Websites aus, für die Sie Stripe konfigurieren möchten.
Geben Sie Ihren aus der Stripe Salesforce Commerce-App abgerufenen Stripe Publishable Key und Restricted Access key ein.
Klicken Sie auf Quick Setup.

Apple Pay einrichten:

Für Apple Pay:

Aktualisieren Sie 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();
});

Richten Sie für eine der Websites in der Sandbox vorübergehend einen Alias ein, damit die Domain im Stripe-Dashboard verifiziert werden kann. Der Alias muss in etwa so lauten:

{
  "__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": "/",
    }
  ]
}

Der Wert für das Gebietsschema muss ein Gebietsschema sein, das nicht deaktiviert ist.

Klicken Sie auf der Seite Zahlungsmethoden-Domains auf Neue Domain hinzufügen.
Geben Sie den Namen Ihrer Domain ein.
Klicken Sie auf Speichern und fortfahren.
Laden Sie die Domain-Zuordnungsdatei herunter.
Hosten Sie die Datei unter /.well-known/apple-developer-merchantid-domain-association. Beispiel: Wenn Sie https://example.com registrieren, stellen Sie die Datei unter https://example.com/.well-known/apple-developer-merchantid-domain-association zur Verfügung.
Klicken Sie auf Verifizieren.

Storefront-Code aktualisieren

Der Code der LINK Basis-Cartridge unterstützt alle von Stripe unterstützten Kreditkarten. Die Liste der zulässigen Karten wird an der Storefont weiterhin durch die Liste der Kredit-/Debitkarten im Business Manager unter „Merchant Tools“ (Händlertools) > „Ordering“ (Bestellungen) > „Payment Methods“ (Zahlungsmethoden) > „Credit/Debit Cards“ (Kredit-/Debitkarten) begrenzt.

Nehmen Sie die folgenden Änderungen am Storefront-Code vor. Die angegebenen Beispiele basieren auf SFRA Version 4.4. In den folgenden Abschnitten werden die Anpassungen beschrieben, die am SFRA-Code vorgenommen wurden.

Es gibt viele Controller-Endpoints, die angehängt werden, anstatt zu ersetzen. Diese werden nicht behandelt, da sie ohne Änderungen funktionieren sollten.

Controller-Aktualisierungen sind nur für ersetzte Endpoints erforderlich. Wenn Sie diese Endpoints in Ihrer Integration bereits ersetzt haben, fügen Sie die Änderungen an der Basis-Cartridge dem ersetzten Controller hinzu. Wenn Sie diese Endpoints nicht erweitert/ersetzt haben, brauchen Sie nichts weiter zu tun.

Controller: CheckoutServices.js

Pfad: app_stripe_sfra/cartridge/controllers/CheckoutServices.js

Entfernen Sie die Validierung des Zahlungsinstruments im Endpoint 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 instrument
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 instrument
  const invalidPaymentMethod = Resource.msg('error.payment.not.valid', 'checkout', null);
  delete billingData.paymentInformation;
  res.json({
    form: billingForm,
    fieldErrors: [],
    serverErrors: [invalidPaymentMethod],
    error: true
  });
  return;
}

Aktualisieren Sie den Code für die Bestellungserstellung:

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();
}

Aktualisieren Sie den Code für die Bestellungsplatzierung:

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();
}

Controller: PaymentInstruments.js

Pfad: app_stripe_sfra/cartridge/controllers/PaymentInstruments.js

Ersetzen Sie den Endpoint DeletePayment durch folgenden Code:

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();
});

Controller: RedirectURL.js

Pfad: app_stripe_sfra/cartridge/controllers/RedirectURL.js

Fügen Sie der Funktion Start folgenden Code hinzu:

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();
});

Externe Schnittstellen

Die Stripe-Funktionalität ist stark von externen Aufrufen der Stripe-Dienste abhängig. Alle externen Schnittstellen verwenden das Service Framework, um mit der Stripe-API zu kommunizieren.

Die Erstellung und Nutzung von Stripe-Konten ist kostenlos. Der überwiegende Anteil der Kommunikation mit Stripe-Diensten wird im Stripe-Dashboard protokolliert und kann dort eingesehen werden. Wir empfehlen Ihnen, das Stripe-Dashboard zum Überwachen und Testen Ihrer Integration zu verwenden. Die Hauptkonfiguration für die Integration der Stripe-Dienste finden Sie unter „Administration“ > „Operations“ (Betrieb) > „Services“ (Dienste) mit einem anderen Dienst für jeden externen Aufruf:

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

Alle diese Dienste verwenden das gleiche Profil und die gleichen Anmeldedaten. Nur bei der Aktivierung des Kommunikationsprotokolls und beim Präfix für den Protokollnamen können sie sich unterscheiden. So sieht die Konfiguration einiger Dienste aus:

Stripe Payment Element

Die Stripe Cartridge unterstützt Stripe Payment Element als Zahlungsmethode.

Das Payment Element ist eine integrierbare Komponente der Nutzeroberfläche, mit der Sie mehr als 25 Zahlungsmethoden mit einer einzigen Integration akzeptieren können.

Um das Payment Element zu aktivieren, navigieren Sie zu Business Manager > Merchant Tools (Händlertools) > Ordering (Bestellung) > Payment Methods (Zahlungsmethoden) und aktivieren Sie die Zahlungsmethode mit der auf STRIPE_PAYMENT_ELEMENT festgelegten ID. In der Storefront „Checkout > Payment“ (Checkout > Zahlung) gibt es ein Widget mit allen im Stripe-Dashboard aktivierten Zahlungsmethoden.

Wenn Sie Payment Element im Business Manager aktivieren, kann es alle anderen Zahlungsmethoden ersetzen. Sie können alle Zahlungsmethoden deaktivieren und stattdessen STRIPE_PAYMENT_ELEMENT verwenden.

Damit die Zahlungsmethode aus dem Stripe Payment Element für die zukünftige Verwendung gespeichert werden kann, navigieren Sie zu Business Manager > Custom Preferences > Stripe Configs (Business Manager > Nutzerdefinierte Einstellungen > Stripe-Konfigurationen) und legen Sie Stripe Payment Element: Enable Save Payment Method for Future Purchases (Stripe Payment Element: Speichern der Zahlungsmethode für zukünftige Einkäufe aktivieren) auf Yes fest.

Um eine Liste der gespeicherten Zahlungsmethoden beim Bezahlvorgang anzuzeigen, navigieren Sie zu Business Manager > Payment Methodes (Business Manager > Zahlungsmethoden) und aktivieren Sie die Zahlungsmethode CREDIT_CARD. Wenn sie mit STRIPE_PAYMENT_ELEMENT aktiviert ist, enthält die Registerkarte mit Kreditkarten eine Liste gespeicherter Karten (falls vorhanden).

Stripe Radar-Ansicht zur Darstellung von Einblicken

Die Stripe LINK Cartridge unterstützt die Radar-Ansicht zur Darstellung von Risikoeinblicken im Abschnitt „Orders“ (Bestellungen) von Business Manager. Radar bietet Betrugsschutz in Echtzeit und benötigt keine zusätzliche Entwicklungszeit. Betrugsexperten können Radar for Fraud Teams hinzufügen, um den Schutz anzupassen und weitergehende Einblicke zu erhalten.

Um die Anzeige von Einblicken zu aktivieren, navigieren Sie zu Business Manager > Merchant Tools (Händlertools) > Custom Preferences (Nutzerdefinierte Einstellungen) > Stripe Configs (Stripe-Konfigurationen) und legen Sie Risk Score Data“ (Risikobewertungsdaten) auf Yes fest.