2. Frontend Integration

There are two main components to integrating Bolt checkout.

Inject track.js in all pages.
Configure connect.js.

Inject track.js

Insert track.js in all the pages of your shopping cart. Use the code shown below.

track.js

<script
  id="bolt-track"
  type="text/javascript"
  src="{CDN_URL}/track.js"
  data-publishable-key="{PUBLISHABLE_KEY}">
</script>

Configure connect.js

There are 4 steps involved in this stage:

Insert connect.js in only those pages which have a Bolt checkout button
Add the bolt checkout button
Define an onSuccess JavaScript method
Call BoltCheckout.configure

Insert `connect.js` in pages that will have the Bolt checkout button. Use the code shown below.

connect.js

<script
  id="bolt-connect"
  type="text/javascript"
  src="{CDN_URL}/connect.js"
  data-publishable-key="{PUBLISHABLE_KEY}">
</script>

Add the Bolt Checkout button

Add the Bolt checkout button as shown using the code below.

HTML

<div class="bolt-checkout-button bolt-multi-step-checkout"></div>

This will create a checkout button. The checkout button has a default width of 284px, is not responsive, and does not fill its parent container. For a responsive button, or other formatting options, please see the available styling classes below.

You can also specify with-cards class to show credit card logos below the button.

HTML

<div class="bolt-checkout-button with-cards"></div>

Styling options

To satisfy various design needs there are multiple possible configurations to further customize the Bolt Checkout button.

Large Width
Specifying .large-width will allow the button to fill its parent container up to a maximum width of 600px. This is useful for forms that have a wider profile or take up the whole page. .large-width can be used in conjunction with .with-cards. When used together, the card issuer logos will center themselves relative to the Checkout button.

HTML

<div class="bolt-checkout-button large-width"></div>

Large width button

Responsive
The .responsive option renders the button wider (filling the page) on mobile devices but keeps a fixed size of 264px for desktop browsers.

HTML

<div class="bolt-checkout-button responsive"></div>

Flexible
The .flexible layout makes the checkout button fill its parent container. This layout is fully responsive and will always fill the space available to it. When the .with-cards option is added in tandem with the .flexible option, the issuer logos are fully responsive and centered relative to the checkout button.

HTML

<div class="bolt-checkout-button flexible"></div>

Flexible checkout button option with different size parent containers

Color
If you want to customize the color of the checkout button and the checkout modal there are a few options. Please see the code samples below for examples on how to customize the styles:

The required element is called "--bolt-primary-action-color". This must be followed by a 6 or 8 digit hexadecimal value (note 3, 4 digits are not supported).

You may additionally supply a color to be shown on hover. This optional element is "--bolt-button-hover-color" and must also have a 6 or 8 digit decimal value.

HTML

<div class="bolt-checkout-button" style="--bolt-primary-action-color:#339900;"></div>

<div class="bolt-checkout-button" style="--bolt-primary-action-color:#339900;
--bolt-button-hover-color:#1a9900;"></div>

Bolt offers an additional select set of styling options for a merchant’s Bolt Checkout button. Email Bolt Support to have these custom options applied.

Create an onSuccess javascript method

The onSuccess method will be called when Bolt successfully processes a transaction. This can be used to redirect the user to an order confirmation page.

onSuccess callbacks can fail!

onSuccess can fail and is not guaranteed to be called on a successful payments. This can happen due to a lot of reasons: Internet outage, browser crashes in the middle of processing payments.

You should always rely on API hook notifications to securely create orders in your system.

Call BoltCheckout.configure

Call BoltCheckout.configure in your javascript on pages where we want to enable Bolt checkout. You need to use the token from order creation. We also provide callback hooks during the checkout process, these may be used to trigger analytic events (ex. Google Analytics).

JavaScript

onEmailEnter: function(email) {
    // This function is called after the user enters their email address.
  },

onShippingDetailsComplete: function() {
    // This function is called when the user proceeds to the shipping options page.
    // This is applicable only to multi-step checkout.
  },
  
  onShippingOptionsComplete: function() {
    // This function is called when the user proceeds to the payment details page.
    // This is applicable only to multi-step checkout.
  },
  
  onPaymentSubmit: function() {
    // This function is called after the user clicks the pay button.
  },
  
  success: function(transaction, callback) {
    // This function is called when the Bolt checkout transaction is successful.
    
    // ... Add your code here ...
        
    // **IMPORTANT** callback must be executed at the end of this function if `success`
    // is defined.
    callback();
  },
  
  close: function() {
    // This function is called when the Bolt checkout modal is closed.
    // This will not be called when create_order endpoint returns a valid URL 
    // and authorization is successful 
  }
};
BoltCheckout.configure(cart, hints, callbacks);

var cart = {
  "orderToken": "<token>"
};
var hints = {};
var callbacks = {
  check: function() {
    // This function is called just before the checkout form loads.
    // This is a hook to determine whether Bolt can actually proceed
    // with checkout at this point. This function MUST return a boolean.
    return true;
  },
  
  onCheckoutStart: function() {
    // This function is called after the checkout form is presented to the user.
  },

  onEmailEnter: function(email) {
    // This function is called after the user enters their email address.
  },

  onShippingDetailsComplete: function() {
    // This function is called when the user proceeds to the shipping options page.
    // This is applicable only to multi-step checkout.
  },
  
  onShippingOptionsComplete: function() {
    // This function is called when the user proceeds to the payment details page.
    // This is applicable only to multi-step checkout.
  },
  
  onPaymentSubmit: function() {
    // This function is called after the user clicks the pay button.
  },
  
  success: function(transaction, callback) {
    // This function is called when the Bolt checkout transaction is successful.
    
    // ... Add your code here ...
        
    // **IMPORTANT** callback must be executed at the end of this function if `success`
    // is defined.
    callback();
  },
  
  close: function() {
    // This function is called when the Bolt checkout modal is closed.
    // This will not be called when create_order endpoint returns a valid URL 
    // and authorization is successful 
  }
};
BoltCheckout.configure(cart, hints, callbacks);

Cart object can be a Promise. In this case Bolt checkout will wait for the promise to be fulfilled before opening Bolt checkout modal.

Checkpoint

Ensure that all the following are true

track.js is present in all pages of your store.
On pages where Bolt checkout is enabled
- Ensure that the Bolt checkout button is visible
- Upon clicking it, it should load the Bolt checkout modal
- The total shown at the top of the modal should match the actual cart total
Completing the checkout must take you to the order confirmation page. You can use the following test credit card number
- Card number: 4111 1111 1111 3000
- Expiration: Any future month/year
- CVV: Any 3 digits

Prefilling user information

If you have access to user data, it is possible to prefill their information in the checkout form. This is done through the hints parameter when you call BoltCheckout.configure:

Text

var cart = {};
var callbacks = {};

var hints = {
  "prefill": {
    "firstName": "Bolt",
    "lastName": "User",
    "email": "email@example.com",
    "phone": "1112223333",
    "addressLine1": "1235 Howard St",
    "addressLine2": "Unit D",
    "city": "San Francisco",
    "state": "California",
    "zip": "94103",
    "country": "US" // ISO Alpha-2 format expected
  }
};

BoltCheckout.configure(cart, hints, callbacks);

Notes:

It's not required to provide all fields shown above, any subset will be accepted
Merchant scoped accounts and local accounts will take priority in prefilling form fields if present
like cart, hints object can be a Promise

Debugging

No Bolt checkout button
Verify the following

The page has the checkout button <div>
The page has connect.js

Infinite spinner when I click the checkout button
Verify the following

You are using the PUBLISHABLE_KEY in the connect.js <script> tag
The domain you are working on has been whitelisted. Contact Bolt to verify this information
There are no javascript errors or console errors when you load your ecommerce page hosting the checkout button
There are no javascript errors or console errors when you click the button

FAQ: I see CDN_URL?

Sandbox: https://connect-sandbox.bolt.com
Production: https://connect.bolt.com

FAQ: What is hints? Why is it empty?

hints are special values sent to checkout. Generally its an empty map and there is no need to send anything through hints. The only time hints is used is in Merchant Scoped Accounts

FAQ: What CDN_URL value should I use?

If you are still developing and testing, you would need to connect to our sandbox URL. If you are using this for production and real order processing, use our production URLs given below.

Refer to Integration Checklist in "Getting Started" for the actual URLs

What's Next

3. Shipping and Tax API

Bolt

Bolt Developer

Search results for "{{ search.query }}"

2. Frontend Integration

Inject track.js

Configure connect.js

Insert `connect.js` in pages that will have the Bolt checkout button. Use the code shown below.

Add the Bolt Checkout button

Styling options

Create an onSuccess javascript method

onSuccess callbacks can fail!

Call BoltCheckout.configure

Checkpoint

Prefilling user information

Debugging

FAQ: I see CDN_URL?

FAQ: What is hints? Why is it empty?

FAQ: What CDN_URL value should I use?

What's Next

2. Frontend Integration

Suggested Edits are limited on API Reference Pages

Inject track.js

Configure connect.js

Insert connect.js in pages that will have the Bolt checkout button. Use the code shown below.

Add the Bolt Checkout button

Styling options

Create an onSuccess javascript method

onSuccess callbacks can fail!

Call BoltCheckout.configure

Checkpoint

Prefilling user information

Debugging

FAQ: I see CDN_URL?

FAQ: What is hints? Why is it empty?

FAQ: What CDN_URL value should I use?

What's Next

Insert `connect.js` in pages that will have the Bolt checkout button. Use the code shown below.