Set Up SFCC for Bolt

Before You Start

Set up a store with a base SFCC storefront cartridge.
Download the Bolt cartridge from this GitHub Repository.
Obtain your Bolt API credentials.
Ensure your store is using SFRA v6.0 or above.

Install Cartridge

Login to Business Manager.
Navigate to Administration > Sites > Manage Sites and select the Settings tab.
Add int_bolt_embedded_sfra to the cartridge path.
Unzip the Bolt cartridge and upload it. For detailed instructions on doing this, see Upload Code for SFRA.

Configure Business Manager

The next step is configuring metadata, site preferences, service, payment methods and OCAPI.

Import Metadata

Navigate to Business Manager > Administration > Site Development > Site Import & Export.
Upload the metadata zipfile contained in the cartridge by running the following:
- • npm run zipMetadata
- • npm run uploadMetadata
Navigate to Business Manager > Administration > Open Commerce API Settings.
Copy the metadata under metadata/ocapi/OCAPIshop_embedded.json to the SHOP API section and replace «client_id» with your own client ID, then save.
Copy the metadata under metadata/ocapi/OCAPIdata_embedded.json to the DATA API section and replace «client_id» with your own client ID, then save.

Site Preferences

In Business Manager, navigate to Merchant Tools > Site Preferences > Custom Preferences.
Set the following values in preference group Bolt Payment Setting - Embedded:
- • API Key: Your Bolt API key.
- • Bolt Merchant Division ID: The unique ID associated with the merchant Bolt Account division.
- • Publishable Key: Your Bolt merchant division specific value. The publishable key is a long string of lower and upper case letters and numbers that consists of three sections.
- • Bolt Environment: String Enum used to switch between different Bolt environment endpoint hostnames. Select either Sandbox, Staging or Production.
- • Enable Bolt Pay: Enable or disable Bolt Pay.
- • Enable Auto Capture: Enable or disable auto-capture.

Payment Method

Ensure Bolt Payments is enabled by navigating to Merchant Tools > Ordering > Payment Methods. BOLT_PAY should be enabled and the payment processor should appear configured.

HTTP Service

Navigate to Administration > Operations > Services and ensure bolt.http is selected.

Authentication Flow

Review the Bolt Accounts diagram to gain insight into how Bolt and your backend work to authenticate customers, populate the Bolt modal, and authorize checkout.

Add Bolt to Template

To include Bolt in your template take the following steps.

Checkout

In /templates/default/checkout/checkout.isml add the following code snippet before the first <isscript> tag:

<isinclude template="checkout/boltEmbed" />

Add a check for which type of Bolt shopper is checking out:

<div id="checkout-main" class="container data-checkout-stage <isif condition=" ${pdict.order.usingMultiShipping && pdict.order.shipping.length > 1}">multi-ship</isif>" data-customer-type="${pdict.isBoltShopperLoggedIn ? 'boltShopper' : (pdict.customer.registeredUser ? 'registered' : 'guest')}" data-checkout-stage="${pdict.currentStage}"
       data-checkout-get-url="${URLUtils.https('CheckoutServices-Get')}">

Shipping

In /templates/default/checkout/shipping/shipmentCard.isml add the following snippets to the file in the places illustrated by the example below:

<div class="card-body shipping-content">
    ...

<form class="shipping-form" autocomplete="on" novalidate
action="$(shipmentLoopState)
? URLUtils.url('CheckoutAddressServices-AddNewAddress')
: URLUtils.url('CheckoutShippingServices-SubmitShipping')}"
data-address-mode="${((pdict.isBoltShopperLoggedIn && pdict.boltAddressId && !pdict.shippingAddressDataMissing) || shippingModel.matchingAddressId) ? 'edit' : 'new'}"  // This line

...

<div class="shipping-address ${pdict.order.usingMulitShipping ? 'd-none' : ''}">
    <fieldset class="shipment-selector-block ${(pdict.order.usingMultiShipping || shipmentLoopState) || (pdict.customer.addresses && pdict.customer

|| (pdict.isBoltShopperLoggedIn && pdict.boltStoredShippingAddress) ? '' : 'd-none'} "> // This line

In /templates/default/checkout/shipping/shipmentSelectorOptions.isml before this line

<iselseif condition="${pdict.customer.addresses && pdict.customer.addresses.length > 0}">

…add the following statement:


<isif condition="${pdict.isBoltShopperLoggedIn && pdict.boltStoredShippingAddress}">
   <option disabled>${Resource.msg('msg.account.addresses', 'checkout', null)}</option>
   <isloop items="${pdict.boltStoredShippingAddress}" var="address">
       <option value="${'ab_'+address.id}" ${address.id==pdict.boltAddressId ? 'selected="selected"' : '' }
       data-first-name="${address.first_name||''}" data-last-name="${address.last_name||''}"
       data-address1="${address.street_address1||''}" data-address2="${address.street_address2||''}"
       data-city="${address.locality||''}" data-state-code="${address.region_code||''}"
       data-country-code="${address.country_code||''}" data-postal-code="${address.postal_code||''}"
       data-phone="${address.phone_number||''}" data-is-gift="${''}" data-gift-message="${''}"
       data-bolt-address-id="${address.id}">
       ${address.first_name || ''} ${address.last_name || ''} ${address.street_address1 || ''} ${address.street_address2 || ''} ${address.locality || ''}${!address.locality || ','} ${address.region_code||''} ${address.postal_code||''}
       </option>
   </isloop>

In /templates/default/checkout/shipping/shippingAddress.isml on line 8, add the following snippet:

<input type="hidden" name="${addressFields.boltAddressId.htmlName}" value="${pdict.boltAddressId}">

Payment

In /templates/default/checkout/billing/paymentOptions/paymentOptionsTabs.isml add the following line of code as illustrated by the example below:


<isloop items="${pdict.order.billing.payment.applicablePaymentMethods}" var="paymentOption">
    <isif condition="${paymentOption.ID === 'BOLT_PAY'}"> // This statement
        <isinclude template="checkout/billing/paymentOptions/bolt/paymentTab" />
    </isif>
</isloop>

In /templates/default/checkout/billing/paymentOptions/paymentOptionsContent.isml add following code snippet as illustrated by the example below:

<isloop items="${pdict.order.billing.payment.applicablePaymentMethods}" var="paymentOption">
    <isif condition="${paymentOption.ID === 'BOLT_PAY'}"> // This statement
        <isinclude template="checkout/billing/paymentOptions/bolt/paymentContent" />
    </isif>
</isloop>

In /templates/default/checkout/billing/paymentOptions/paymentOptionsSummary.isml add following code snippet as illustrated by the example below:

<div class="payment-details">
    <isloop items="${pdict.order.billing.payment.selectedPaymentInstruments}" var="payment">
        <isif condition="${payment.paymentMethod === 'BOLT_PAY'}" /> // this statement
	        <isinclude template="checkout/billing/paymentOptions/bolt/paymentSummary" />    
        </isif>
    </isloop>
</div>

Forms

In /forms/default/address.xml add following code snippet on line 6

<field formid="boltAddressId" label="label.input.boltAddressid" type="string" binding="boltAddressId" mandatory="false" />

In /forms/default/billing.xml add following code snippet within the <form></form> tag at the top of the file:

<include formid="boltCreditCard" name="boltCreditCard"/>

Customize Frontend

You can change the frontend appearance and behavior of the cartridge. See the information below to identify the elements and .js files to update.

The Bolt modal relies on the $('#email-guest') SFCC native front end component to trigger a check for the customer’s email and whether they have an existing account. Change the component ID in eventListenerRegistration.js to apply customizations to this input.
Bolt uses the keyup callback to trigger the API call to render the OTP modal. When the shopper types in a valid email address and stops entering anything for 1 second, Bolt makes a call to check if that email has an associated Bolt account and, if present, pre-fills all shopper information. To create a different user experience, modify eventListenerRegistration.js.

Add Delivery Fee to Checkout

You can add a delivery fee at checkout based on the order’s shipping destination. Use this functionality to comply with local laws such as Colorado’s Delivery Fee.

In SFCC Business Manager, navigate to Merchant Tools > Ordering > Shipping Methods.
For each currently available shipping method, add an exclusion rule to exclude addresses from Colorado from receiving the shipping method.
For each available shipping method, create a corresponding shipment method which includes the $0.27 fee in the shipping value. The Description field can be used to render a new description in Bolt Checkout UI for the shipping method.

Data Storage

This integration requires the following system object extensions.

OrderPaymentInstrument custom attribute:
- • boltCardBin(String): Store the credit card bin
- • boltPaymentMethodId(String): Bolt Payment Method ID
- • boltCreateAccount(Boolean): Indicates whether the user has chosen to create a Bolt account
- • boltTokenType(String): Bolt token type
SitePreferences custom attributes:
- • boltAPIKey(String): Bolt-provided merchant account identifier
- • boltMultiPublishableKey(String): Used to retrieve your Bolt merchant division key
- • boltEnvironment(String): String Enum (Sandbox, Staging, Production); used to switch different Bolt environment endpoint hostnames
- • BoltEnable(Boolean): Indicates whether Bolt is enabled
- • boltMerchantDivisionID(String): Bolt merchant division ID
- • boltEnableAutoCapture(Boolean): Indicate if funds are captured

Logs

Bolt embedded adds several new custom logs.

Bolt Custom Log: Similar to custom-Bolt-blade5-0.mon.demandware.net-0-appserver-20191120.log. This log file contains all logs from the int_bolt_embedded_sfra cartridge.
Service Communication Logs: These logs contain every request and response to the Bolt API endpoint. To enable these logs, navigate to Administration > Operations > Services > bolt.http and check Communication Log Enabled.