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 line6
<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 ineventListenerRegistration.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, modifyeventListenerRegistration.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 theint_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.