📍 Bolt Help / Developers / Developer Guides / Checkout Setup / Embedded Checkout Setup / Embedded Accounts / Embedded Accounts Checkout Flow Setup

Embedded Accounts Checkout Flow Setup

Use the following guide to set up Bolt’s front-end Embedded Account components for your storefront. There are two main shopper experience flows that need to be built:

  1. Guest Checkout Flow: This flow utilizes Bolt’s embedded payments component and tokenize() function to enable checkout on your storefront for shoppers with no existing Bolt account. During this flow, shoppers opt-in to creating a Bolt account for future purchases.
  2. Logged-in Checkout Flow: This flow utilizes Bolt’s accountExists() function and authorization component to determine whether a shopper has a Bolt account, give them the option to log in via a one-time password, and check out.


These instructions assume that you:

  • Have an active Bolt Merchant Account
  • Have reviewed Bolt’s API collection

Install Script

Add the following script to every page where a shopper can check out from your store to enable the use of Bolt’s embedded components.



Base URL Options:

  • Production: connect.bolt.com/embed.js
  • Sandbox: connect-sandbox.bolt.com/embed.js

1. Set Up Guest Checkout Flow

The following required steps enable guest shoppers to perform the following actions on your storefront:

Insert Payment Component

In order for a guest shopper to check out on your storefront, they must be able to interact with Bolt’s Payment component. The Payment component displays input fields that enable a shopper to securely provide credit card information (card number, expiration, and CVV) as either one seamless input field or several separate input fields.

1. Create an Instance of Bolt

let boltEmbedded = Bolt("<<my_publishable_key>>");

2. Create Payment Component

let paymentComponent = boltEmbedded.create("payment_component");
let el = document.getElementById("div-to-inject-field-into");
// or 

Field Options
Parameter name Type Description
options object Set of options to create the Bolt payment fields.
options.styles partial A set of CSS properties to style the input fields. (fontSize, fontFamily, fontColor, fontWeight, borderColor, borderWidth, borderRadius, backgroundColor, borderColorOnError, fontColorOnError, borderColorOnFocus, fontColorOnFocus)
options.value object Values to prefill. Prefill supported for: card expiration string value in the format YYYY-MM, billing postal code, and string value of ZIP code.
options.disabled boolean Default is false.
options.showBillingZIPField boolean Default is false. Show and require billing zip code field.
options.showErrors boolean Default is false. Display errors and error codes.
options.renderSeparateFields boolean Default is false.

3. Validate Payment Fields

Bolt hosted fields will include in-line validation that appear as the user types. You also can receive error information via listener when a user blurs from the payment field.

paymentField.on("error", function(e) {
  // e instanceof Error === true
  // e.message === "CC Field incomplete"

4. Tokenize Payment Information

Call paymentField.tokenize() when you are ready to retrieve a token for the payment information entered. It contains all information necessary to call the Authorize Payment API as its parameter.

// tokenize is tokenization result or error
const tokenize = await paymentField.tokenize();
	"token": "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0", // token from Bolt tokenizer. Used in authorization or createExternalToken call. 

If you do not authorize payment within 15 minutes of retrieving the token, you must call tokenize() again.

	"type": "tokenization_error", 
	"message": "Tokenizer could not save credit card" 

All of the following is required for Bolt Account creation:

  • Email Address: Used as a unique ID for the Bolt Account.
  • Mobile Phone: Used for, text messages, one-time passwords, and fraud signals.
  • Bolt Account Opt-out: Used by shoppers who wish to opt-out of creating a Bolt Account. Depending on the user type, it display either consent to create an account or consent to link accounts.
  • Bolt T&Cs: Used to link to Bolt’s terms of use and privacy policy.

Bolt provides an embeddable component for automatically collecting consent and displaying T&Cs. This component is built as a web component and does not require an iFrame for rendering. Your team will be given a reference to this container for use.

Create a Bolt Embedded Account Checkbox

Before You Start

You must have already loaded the Bolt /embed.js script and have instantiated an instance of Bolt embedded.

const bolt = window.Bolt(state.keys.publishableKey);

1. Create the Component

Create the checkbox by calling the create method on your instance of Bolt embedded.

const acctCheck = bolt.create("account_checkbox", options); // AccountCheckbox

Options are not required and do not need to be passed. However, in the event that you do want to override the defaults, the options are:

interface Options {
 defaultValue?: boolean; // default false
 version?: "compact" | "expanded"; // default "compact"
 listeners?: { // default undefined
   change?: (value: boolean) => void;

2. Mount the Component

Attach the component to the DOM by calling the mount method on the component with a DOM node or a selector.

acctCheck.mount("#acct-checkbox"); // Promise<void>

3. Listen for Changes

You can do this either through the initialization configuration mentioned above (listeners), or anytime after initialization by using the component’s on method.

acctCheck.on("change", checked => createBoltAccountt = checked); // void

4. Pass the Selected Value

When calling Bolt’s authorization endpoint, pass the value as create_bolt_account as part of the post object.

create_bolt_account: createBoltAccount,

Remove the Component (Optional)

If you want to disable the checkbox, remove the component from the DOM. To do this, call the unmount function on the component instance.

acctCheck.unmount(); // Promise<void>

2. Set Up Logged-in Checkout

The following steps enable you to perform all of the following actions on your storefront:

  • Open Bolt’s Embedded Login UI using a Bolt JS library function
  • Receive an access token, a refresh token, and an ID token used in OAuth flows
  • Login or create a merchant storefront account using the OAuth ID

Sequence Diagram

The following diagram outlines all of the major actions that must occur to detect an account and display a logged-in Checkout flow.

sequenceDiagram participant Shopper participant StoreFrontEnd participant StoreBackEnd participant BoltLoginUI participant BoltBackEnd Shopper->>+StoreFrontEnd: Enters Email StoreFrontEnd->>+BoltBackEnd: Does Account Exist? BoltBackEnd-->>StoreFrontEnd: Yes StoreFrontEnd->>+BoltLoginUI: Open (Passing Email) BoltLoginUI-->>Shopper: Prompt for OTP Shopper->>BoltLoginUI: Input OTP BoltLoginUI-->>StoreFrontEnd: Send Oauth Code StoreFrontEnd->>StoreBackEnd: Forward OAuth Code StoreBackEnd->>BoltBackEnd: OAuth Code + API Key BoltBackEnd-->>StoreBackEnd: OAuth Tokens (Access, Refresh, ID) StoreBackEnd-->>StoreFrontEnd: Session Cookie StoreFrontEnd->>StoreBackEnd: Request Account Details StoreBackEnd->>BoltBackEnd: Fetch Account Details + Access Token BoltBackEnd-->>StoreBackEnd: Send Account Details StoreBackEnd-->>StoreFrontEnd: Send Account Details StoreFrontEnd-->>Shopper: Display Logged-in Checkout

Set Up Account Detection

You must check whether the shopper is already logged in at the beginning of the checkout process.

  • When logged in: Shopper account details are available to fetch.
  • When not logged in: A prompt must be displayed for the shopper to login via email or phone number. If does not have a matching email or phone number, an account is not detected.

1. Add an Email or Phone Input Field

Embedded Checkout displays upon recognizing a shopper that already participates in the Bolt Network. To enable this shopper detection, you must prompt the shopper to provide their email address or phone number. This can either be done at the beginning of the checkout process, or beforehand (outside of checkout).

Embedded Checkout can detect shoppers when they enter an email address or a phone number associated with their account. At minimum, Bolt recommends that you configure an email address input field.

2. Check for a Bolt Account

Send a GET request to https://api.bolt.com/v1/account/exists to check whether a Bolt account exists for a user.

  • On Success + True: Open the Bolt Checkout modal using the embed.js script previously installed.
  • On Success + False: Send the shopper to your guest checkout experience.
  • On Failure: Send the shopper to your guest checkout experience.
async function accountExists(email) {
const response = await fetch("https://api-sandbox.bolt.com/v1/account/exists?email=" +
const responseAsJson = await response.json();
return responseAsJson.has_bolt_account;
Success Response
    "has_bolt_account": true,
Error Response
	"result": { 
    	"success": false 
	"errors": [{ 
      	"code": 1005, 
      	"message": "Authentication error. Invalid merchant key." 

Trigger One-Time Password (OTP)

1. Set Up Authorization Component

The Authorization component displays a modal that enables shoppers to log in to their Bolt account by inputting their one-time Password (OTP) after their account has been detected. The shopper can also opt to have their password resent via SMS or email.

To create and mount an authorization component, do the following:

let authorizationComponent = BoltEmbedded.create("authorization_component", style: "callout");

authorizationComponent.mount(<email_input>); // this will attach the iFrame to the HTML DOM
<div id="email-div">
<input type="email"
await authorizationComponent.mount("#email-div");

The element passed in on mount is the target of the callout if that style is selected. The element ID should be the ID of a container div, not the input field itself. The authorization component iframe cannot properly render when attached to <input> elements.

2. Style the Authorization Component

You can display the authorization component in one of three ways using the position attribute and one of the following values:

  • left-aligned
  • right-aligned
  • center (default)
let authorizationComponent = boltEmbedded.create("authorization_component",  {style: {position: "right"}} );

3. Open the Authorization Component

If a Bolt Account exists for the shopper, display Bolt’s authorizationComponent by calling the following function in Bolt’s Javascript library:

let authorizationResponse = await authorizeComponent.authorize({"email": email});

This sends a One-Time Password (OTP) to the associated email address passed to the authorizationResponse function.

The shopper has the option of either:

  1. Authorizing the Bolt account: Returns a promise that resolves to a JSON object with the keys AuthorizationCode and scope, which can be exchanged for a token.
  2. Exiting the modal: Returns a promise that resolved to an undefined value.


if (authorizationResponse) {
  const authorizationCode = response.authorizationCode;
  const scope = response.scope ;

The Bolt authorization component displays a spinner indefinitely after a shopper completes login; the host must explicitly hide it by calling unmount:


Integrate With Bolt’s OAuth Endpoint

Viewing and managing Bolt Account details requires integrating with Bolt’s OAuth endpoint on your backend to complete the OAuth protocol and retrieve an access token (as well as refresh tokens).

You must store both tokens for future access of the shopper’s Bolt Account information. These tokens should be associated with the merchant storefront account that is either identified or created as described below.

Bolt also sends an ID token which includes the necessary information to perform an SSO login. Once an account is identified or created, your backend should establish a new authenticated session issued to the shopper’s browser.


The following example uses cURL for making network requests and jq for parsing the JSON response. The response from calling https://api-sandbox.bolt.com/v1/oauth/token has a key named access_token, which is used to authorize later requests.

output=$(curl -X POST https://api-sandbox.bolt.com/v1/oauth/token -d $payload)
echo $(jq -r '.access_token' <<< $output)

3. Authorize Payment

Now that shoppers can interact with Bolt checkout and log in to a Bolt account, let’s look at how to send their order to Bolt for payment authorization.

1. Submit a Payment Authorization POST Request

Build a POST request to send to Bolt’s servers at /v1/merchant/transactions/authorize (see Bolt’s Authorize a Card API Reference).

2. Pass Cart Details

Cart details are essential to creating excellent support and post-purchase experiences. Be sure to include as many as possible.

You can pass any additionally required unique IDs using either cart.metadata or cart.order_reference.

4. Sync Transaction Statuses

Transaction statuses must stay in sync bidirectionally for Bolt and your platform. The following sections cover how to send and receive transaction status updates.

From Bolt

Bolt uses a transaction webhooks service to update merchants on when payment status changes have occurred. Within the webhook delivery system, Bolt can directly integrate into APIs set up on your module.

To leverage these webhooks, you must build out a receiving endpoint that maps between Bolt’s transaction statuses and your order statuses.

Bolt Status Definition
pending Payment has been authorized / order created
authorized Payment is ready to capture
completed Payment has been fully captured
cancelled Payment has been voided
rejected_irreversible Payment is fully rejected for suspected fraud
rejected_reversible Payment is conditionally rejected for suspected fraud; you may choose to manually approve

Refunded is not a transaction status but a separate transaction object that shows the completed refund.

To Bolt

You can use Bolt’s Transaction API library to send status updates:

Error Codes

The error codes listed below may be used to affect the behavior of your host page, based on the given state of Bolt’s hosted payment fields. For example, using these error code responses, you may create your own validation errors, disable the pay button, or determine other behaviors.

Code number Cause Description
1000 Credit card number is missing “Card number required”
2000 Invalid credit card number “Invalid card number”
3000 Credit card network is not supported “Unsupported card network”
1001 Card’s expiration date is missing “Expiration required”
2001 Card’s expiration date is invalid “Invalid expiration”
3001 Card’s expiration date is past “Card expired”
1002 CVV is missing “CVV required”
2002 CVV is invalid “Invalid CVV”
1003 Billing ZIP is missing “Billing ZIP required”
2003 Billing ZIP is invalid “Invalid billing ZIP”

Perform Account Actions

To read account details and perform account actions on behalf of a shopper, see the following articles:

📖On This Page