Guida all'implementazione di Stripe Connector for Salesforce B2C Commerce

Configurare Business Manager

Per il funzionamento ottimale di Stripe Connector for Salesforce B2C Commerce (cartuccia LINK) sono necessarie diverse cartucce. Inoltre, il supporto per il controller e SFRA è suddiviso in cartucce diverse, semplificando così l’installazione e l’utilizzo dell’uno o dell’altro modello.

Importa tutte e tre le cartucce nella progettazione dell’esperienza d’uso e associale a una connessione server.

Assegnazione della cartuccia del sito

Vai in Administration > Sites > Manage Sites (Amministrazione > Siti > Gestione siti).
Fai clic sul nome del sito per il sito della vetrina in cui desideri implementare la funzionalità Stripe.
Seleziona la scheda Settings (Impostazioni).
Per Storefront Reference Architecture (SFRA), aggiungi app_stripe_sfra:int_stripe_sfra:int_stripe_core al percorso della cartuccia.

Ripeti questi passaggi per ciascun sito della vetrina in cui desideri implementare Stripe.

Assegnazione della cartuccia di Business Manager

Vai in Administration > Sites > Manage Sites (Amministrazione > Siti > Gestione siti).
Fai cli su Business Manager Site (Sito Business Manager), quindi sul link Manage the Business Manager site (Gestisci il sito Business Manager).
Aggiungi int_stripe_core al percorso della cartuccia.

Importazione dei metadati

Vai nella cartella dei metadati del progetto e apri la cartella stripe_site_template.
Apri la cartella sites e modifica la cartella siteIDHere con l’ID del sito che desideri modificare.
Aggiungi una cartella per ogni sito in cui desideri implementare Stripe.
Vai in Administration > Site Development > Site Import & Export (Amministrazione > Sviluppo sito > Importazione ed esportazione sito).
Comprimi la cartella stripe_site_template in un file zip e importala.

Creare la progettazione Stripe

Se necessario, aggiorna il percorso all’installazione SFRA di base in package.json dalla stessa cartella radice.

Di norma c’è una cartella di progetto di primo livello in cui sono clonati i repository della cartuccia SFRA di base e tutti i plug-in, le librerie e le altre cartucce LINK necessari. Se hai anche clonato la cartuccia Stripe in quella cartella, non è necessario aggiornare la proprietà paths.base. Altrimenti, aggiorna la proprietà paths.base in package.json con il percorso relativo alla directory locale contenente il repository di Storefront Reference Architecture. Il seguente è il valore paths.base predefinito:

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

Dopo aver verificato che la proprietà package.json abbia il percorso corretto per le cartucce SFRA, esegui il comando npm run compile:scss dalla cartella radice del repository di Stripe.

Aggiungere nuovi elaboratori di pagamento

Sono disponibili due elaboratori di pagamento nella cartuccia Stripe. STRIPE_CREDIT gestisce solo i pagamenti con carta di credito, mentre STRIPE_APM gestisce i metodi di pagamento tramite Payment Element e Express Checkout Element.

Elaboratore di pagamento tramite carta di credito

Vai in Merchant Tools > Ordering > Payment Processors (Strumenti per esercenti > Ordini > Elaboratori di pagamento) e fai clic su New (Nuovo).
Nella finestra, imposta l’ID su STRIPE_CREDIT e fai clic su Apply (Applica).

Elaboratore di pagamento APM

Vai in Merchant Tools > Ordering > Payment Processors (Strumenti per esercenti > Ordini > Elaboratori di pagamento) e fai clic su New (Nuovo).
Nella finestra, imposta l’attributo ID sul valore STRIPE_APM e fai clic su Apply (Applica).

Aggiornare le modalità di pagamento

Vai in Merchant Tools > Ordering > Payment Methods (Strumenti per esercenti > Ordini > Modalità di pagamento), fai clic sulla modalità di pagamento CREDIT_CARD e seleziona l’elaboratore di pagamento STRIPE_CREDIT nel menu a discesa presente nella sezione dei dettagli di CREDIT_CARD.

Per i metodi di pagamento dinamici o il pulsante di richiesta di pagamento, abilita STRIPE_APM_METHODS per includere i metodi di pagamento supportati da Stripe. Per ulteriori informazioni, consulta la guida ai metodi di pagamento.

Per utilizzare il pulsante di richiesta di pagamento Stripe, abilita il metodo di pagamento STRIPE_PAYMENT_REQUEST_BTN. Per ulteriori informazioni, consulta l’articolo sul pulsante di richiesta pagamento.

Installare l’app Stripe Salesforce Commerce

Usa Stripe Apps per rafforzare la sicurezza e semplificare l’uso di chiavi con limitazioni distinte per ogni integrazione con il tuo account Stripe. La procedura di installazione dell’app Stripe e di acquisizione delle nuove chiavi private e pubblicabili è essenziale per l’integrazione con il connettore Salesforce Commerce. Questo approccio elimina la necessità di creare manualmente una chiave con limitazioni o di utilizzare una chiave privata. Per integrare l’app Adobe Salesforce e rafforzare l’infrastruttura di sicurezza del tuo account:

Accedi a Stripe App Marketplace, poi fai clic su Installa l’app Salesforce Commerce.
Seleziona l’account Stripe in cui vuoi installare l’app.
Verifica e approva le autorizzazioni dell’app, installa l’app in un ambiente di test o in modalità live, quindi fai clic su Installa.
Dopo aver installato l’app, conserva le chiavi in un luogo sicuro senza perderle. Per ricordarti dove l’hai memorizzata, puoi lasciare una nota sulla chiave nella Dashboard.
Usa la chiave pubblicabile e la chiave privata appena generate per completare la configurazione del connettore.
Per gestire l’app o generare nuove chiavi di sicurezza dopo l’installazione, vai alla pagina delle impostazioni dell’applicazione in una sandbox o in modalità live.

Configurazione

Aggiorna la sezione Merchant Tools > Site Preferences > Custom Site Preferences > Stripe Configurations (Strumenti per esercenti > Preferenze sito > Preferenze personalizzate sito > Configurazioni Stripe) con i valori specifici per Stripe.

Compila la chiave API privata Stripe con i valori dell’app Stripe Salesforce Commerce.
Compila la chiave API pubblicabile con i valori dell’app Stripe Salesforce Commerce.
Is this SFRA installation (Installazione SFRA): scegli yes (Sì) se il sito attuale utilizza la Storefront Reference Architecture (SFRA).
Capture Funds on Stripe Charge (Acquisisci i fondi all’addebbito Stripe): il valore predefinito per questa opzione è true (Sì). Configuralo su false (No) per autorizzare gli addebiti Stripe.
Stripe card element CSS style (Stile CSS elemento carta Stripe): inserisci lo stile CSS che il pulsante dell’elemento carta deve ereditare per adattarsi agli stili complessivi della vetrina, ad esempio, {"base": {"fontFamily": "Arial, sans-serif","fontSize": "14px","color": "#C1C7CD"},"invalid": {"color": "red" } }).
Stripe API URL: https://js.stripe.com/basil/stripe.js
Stripe Payment Request Button Style: per il pulsante di richiesta di pagamento, seleziona lo stile CSS limitato che dovrà avere il pulsante. Per ulteriori informazioni, consulta l’argomento relativo alla progettazione degli elementi.
Apple Pay Verification String (Stringa di verifica di Apple Pay): inserisci la stringa di verifica Apple fornita nella Dashboard Stripe. Si tratta di un’attivazione una tantum. La console Stripe delega Apple Pay per la stringa di verifica al momento della configurazione. Effettua questa configurazione in ambiente sandbox se utilizzi il pulsante di richiesta pagamento come modalità di pagamento nella vetrina.
Country Code (Stripe Payment Request Button): è il codice Paese predefinito (ad es. US) del pulsante di richiesta pagamento. Potrebbe essere necessario personalizzarlo su un sito per più Paesi per trasmettere in modo dinamico il codice Paese anziché la preferenza del sito. Per ulteriori informazioni, consulta l’articolo sulla creazione di un’istanza di richiesta di pagamento.
Stripe webhook signing secret (Chiave privata di firma del webhook di Stripe): inserisci la chiave privata di firma del webhook fornita nella Dashboard Stripe. Stripe firma gli eventi webhook e passa una convalida a SFCC. SFCC convalida i contenuti del messaggio utilizzando la chiave privata.
Stripe allowed Webhook Statuses (Stati del webhook consentiti da Stripe): configura gli stati consentiti a cui i webhook devono rispondere.
Stripe Enabled (Stripe abilitata): abilita o disabilita la cartuccia.

Configurazione rapida di Stripe

In alternativa, puoi configurare Stripe in Business Manager utilizzando Stripe Quick Setup (Configurazione rapida di Stripe)

Accedi a Business Manager.
Cerca “Stripe Quick Setup” (Configurazione rapida di Stripe) in Administration (Amministrazione) di Business Manager.
Seleziona i siti per i quali vuoi configurare Stripe.
Inserisci la chiave Stripe Publishable Key e la chiave Restricted Access key recuperate dall’app Stripe Salesforce Commerce.
Fai clic su Quick setup (Configurazione rapida).

Configurare Apple Pay

Per Apple Pay:

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

Configura un alias per uno dei siti dell’ambiente sandbox temporaneamente così che il dominio possa essere verificato nella Dashboard Stripe. L’alias deve avere un aspetto simile a:

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

Il valore delle impostazioni locali deve corrispondere a una lingua non disabilitata.

Nella pagina Domini dei metodi di pagamento, fai clic su Aggiungi un nuovo dominio.
Inserisci il nome del tuo dominio.
Fai clic su Salva e continua.
Scarica il file di associazione del dominio.
Metti il file su /.well-known/apple-developer-merchantid-domain-association. Ad esempio, se registri https://example.com, rendi il file disponibile su https://example.com/.well-known/apple-developer-merchantid-domain-association.
Fai clic su Verifica.

Aggiornare il codice della vetrina

Il codice di base della cartuccia LINK prevede il supporto per tutte le carte di credito compatibili con Stripe. L’elenco delle carte il cui uso è consentito nella vetrina è ancora limitato dall’elenco di carte di credito e di debito in Business Manager: Merchant Tools > Ordering > Payment Methods > Credit/Debit Cards (Strumenti per esercenti > Ordini > Modalità di pagamento > Carte di credito/debito).

Effettua i seguenti aggiornamenti al codice della vetrina. Gli esempi forniti si basano sulla versione 4.4 di SFRA. Le seguenti sezioni descrivono in dettaglio le personalizzazioni eseguite al codice SFRA.

Sono disponibili molti endpoint del controller che rappresentano aggiunte e non sostituzioni. Questi non verranno trattati poiché dovrebbero funzionare senza alcun intervento.

Gli aggiornamenti al controller sono necessari solo per gli endpoint di sostituzione poiché potresti aver già sostituito l’endpoint nella tua integrazione. Usa le modifiche apportate alla cartuccia di base e aggiungile al controller già sostituito. Se non hai esteso/sostituito questi endpoint non devi fare nulla.

Controller: CheckoutServices.js

Percorso: app_stripe_sfra/cartridge/controllers/CheckoutServices.js

Remove the payment method validation in the SubmitPayment endpoint:

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

Aggiorna il codice di creazione dell’ordine:

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

Aggiorna il codice di invio dell’ordine:

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

Percorso: app_stripe_sfra/cartridge/controllers/PaymentInstruments.js

Sostituisci l’endpoint DeletePayment con il codice seguente:

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

Percorso: app_stripe_sfra/cartridge/controllers/RedirectURL.js

Aggiungi il codice seguente alla funzione 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();
});

Interfacce esterne

La funzionalità di Stripe si basa molto sulle chiamate esterne ai servizi Stripe. Tutte le interfacce esterne impiegano il framework del servizio per comunicare con l’API Stripe.

La creazione e l’utilizzo degli account Stripe sono gratuiti. La maggioranza delle comunicazioni con i servizi Stripe viene registrata ed è accessibile nella Dashboard Stripe. Ti consigliamo l’uso della Dashboard Stripe per monitorare e testare l’integrazione. La principale configurazione per l’integrazione dei servizi Stripe è reperibile in Administration > Operations > Services (Amministrazione > Procedure operative > Servizi) con un diverso servizio per ciascuna chiamata esterna:

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

Tutti questi servizi impiegano il medesimo profilo e le stesse credenziali. L’unica cosa che potrebbe differire è se il registro delle comunicazioni è abilitato e il prefisso del nome del registro. Ecco la configurazione di alcuni dei servizi:

Stripe Payment Element

La cartuccia Stripe supporta Stripe Payment Element come modalità di pagamento.

Payment Element è un componente dell’interfaccia utente integrabile che ti consente di accettare più di 25 modalità di pagamento con una sola integrazione.

Per abilitare Payment Element, vai a Business Manager > Merchant Tools > Ordering > Payment Methods (Business Manager > Strumenti per esercenti > Ordini > Modalità di pagamento) e abilita la modalità di pagamento con ID impostato su STRIPE_PAYMENT_ELEMENT. In Storefront Checkout > Payment (Storefront Checkout > Pagamento) è disponibile un widget con tutte le modalità di pagamento abilitate nella Dashboard di Stripe.

Quando abiliti il Payment Element in Business Manager, questo può sostituire tutte le altre modalità di pagamento. Puoi disabilitare tutte le modalità di pagamento e utilizzare STRIPE_PAYMENT_ELEMENT.

Per abilitare il salvataggio delle modalità di pagamento di Stripe Payment Element per un uso futuro, vai a Business Manager > Custom Preferences > Stripe Configs (Business Manager > Preferenze personalizzate > Configurazioni Stripe) e imposta Stripe Payment Element: Enable Save Payment Method for Future Purchases (Stripe Payment Element: abilita il salvataggio della modalità di pagamento per acquisiti futuri) su Yes (Sì).

Per visualizzare un elenco delle modalità pagamento salvate nella procedura di pagamento, vai a Business Manager > Payments Methods (Business Manager > Modalità di pagamento) e abilita la modalità di pagamento CREDIT_CARD. Una volta abilitata con STRIPE_PAYMENT_ELEMENT, la scheda della carta di credito includerà un elenco delle carte salvate, se presenti.

Visualizzare gli approfondimenti di Stripe Radar

La cartuccia Stripe LINK supporta la visualizzazione dei dati Radar per mostrare le informazioni approfondite sul rischio nella sezione Orders (Ordini) di Business Manager. Radar fornisce una protezione in tempo reale contro le frodi senza ulteriori tempi di sviluppo. I professionisti antifrode possono aggiungere Radar for Fraud Teams per personalizzare la protezione e recuperare informazioni più approfondite.

Per abilitare la visualizzazione degli approfondimenti, vai a Business Manager > Merchant Tools > Custom Preferences > Stripe Configs (Business Manager > Strumenti per esercenti > Preferenze personalizzate > Configurazioni Stripe) e imposta Risk Score Data (Dati sul punteggio di rischio su Yes (Sì).