Skip to main content

Create a Self-Hosted Checkout Flow

Bold Checkout provides two options for working with checkout flows (Patent Pending): using a standard, Bold-hosted checkout flow, or hosting your own. Self-hosted flows can be anything — you can create any checkout frontend that you want, and power the checkout using Bold's APIs.

To make it easier to build your own self-hosted flow, Bold provides frontend templates as examples of standard Bold Checkout user interfaces. These templates also enable you to access API libraries for easy customization of the user experience.

The following diagram shows how the Open Source Checkout Templates interact with Bold Checkout and your own store:

This guide outlines how to get the templates up and running and how to customize them to your unique business needs.

Architecture requirements

Creating a self-hosted checkout flow with the Bold APIs requires the following technologies:

  • The Bold Checkout app installed on your store, which enables you to use the Checkout Frontend, Checkout Backend, and Checkout Admin APIs.

  • An ecommerce platform, which provides product inventory management, maintains customer records, and hosts site pages.

  • A frontend application, which allows you to customize your users’ checkout experience and align user interface elements with your brand. In this example, this functionality is provided by the Open Source Checkout Templates.

  • A backend application, which provides routing functionality, initializes orders via the Bold Checkout Backend API, and serves the base HTML pages that will host your checkout user interface. The Checkout Experience Backend project provides the basics for self-hosting your checkout flow.

    note

    The backend application is used to call the Checkout Backend API. This API requires tokens with special privileges that are not safe to share publicly, so it is important to make these calls from a controlled environment.

Prerequisites

Before you get started, complete the following steps:

  1. Follow the steps outlined in the Getting Started Guide.
  2. Ensure that you can serve your checkout application a publicly-accessible URL with a unique domain name. Bold requires a publicly-accessible URL to verify the security of customer information when using the Bold APIs.
    1. You can use tools such as NGROK or Cloudflare Tunnels to create a public domain for your local host.
    2. This link is referred to as <YOUR_PUBLIC_SERVER_URL> in the rest of this documentation.
  3. Complete the following steps in the Checkout Getting Started guide:
    1. Install Bold Checkout.
    2. Submit a support request.
  4. Install node and either yarn or npm.

Create a backend application

To self-host your checkout flow, you must provide your own server infrastructure. The Checkout Experience Backend project provides an example of how to connect to Bold Checkout APIs with the checkout frontend. Follow the instructions in this section to create and configure a backend application.

Requirements

In addition to completing the prerequisites listed earlier, you also need the following:

  • PHP 8.1 with Laravel 9
  • Composer
  • A MySQL database server

Clone and set up the project

Complete the following steps to clone and set up the project:

  1. Clone the project and install dependencies:
    git clone [email protected]:bold-commerce/checkout-backend.git
    cd checkout-experience-back-end
    composer install
  2. Create an .env file from the sample file:
    cp .env.example .env
  3. Generate a Laravel key by running the following command:
    ./artisan key:generate
  4. Open your new .env file and replace the following values:
    1. APP_URL = <YOUR_PUBLIC_SERVER_URL>
    2. CHECKOUT_API_PATH = checkout
    3. CHECKOUT_API_ENVIRONMENT = https://api.boldcommerce.com

Create the database

The Checkout Experience Backend project requires a MySQL server for persistence. Complete the following steps to connect the project with your server:

  1. Connect to the MySQL server.
  2. Create a new database.
  3. Open your .env file and replace the following values:
    1. DB_DATABASE = The database name.
    2. DB_USERNAME = The database username.
    3. DB_PASSWORD = The database password.
    4. DB_HOST = The database host name.
    5. DB_PORT = The database port.
  4. Navigate to the root directory of the project. Run ./artisan migrate to configure the newly created database.

Create Developer Dashboard credentials

Complete the following steps to create a set of credentials and add them to your project:

  1. Navigate to the Developer Dashboard.
  2. Sign in or create an account.
  3. Click Create API Credential.
    1. Name the set of credentials.
    2. In the Redirect_uris field, enter <YOUR_PUBLIC_SERVER_URL>/api/authorize.
    3. Click the Create API Credential button.
  4. Open your .env file and replace the following values:
    1. DEVELOPER_CLIENT_ID = The client_id from the Developer Dashboard.
    2. DEVELOPER_CLIENT_SECRET = The client_secret from the Developer Dashboard.
    3. DEVELOPER_REDIRECT_URL = <YOUR_PUBLIC_SERVER_URL>/api/authorize

Start your server

Complete the following steps to start your server:

  1. Navigate to the root directory of your project. Run ./artisan serve.
  2. If the project is running locally, you also must expose the server to the public internet using a tunnel tool of your choice (ngrok, Cloudflare Tunnels, etc).

Install Bold Checkout on your server

Complete the following steps to install Bold Checkout on your server:

  1. In a browser, navigate to <YOUR_PUBLIC_SERVER_URL>/install.
  2. Click the Install button. The browser redirects you to Bold Account Center.
  3. Login to your Bold Account Center account.
  4. If the account has multiple stores, select the store you wish to install Bold Checkout on, and click Continue. Otherwise, continue to the next step.
  5. In the prompt that appears, review the permissions and click Approve. If successfully installed, a JSON response appears on your storefront that begins with the following: {"message":"Shop install successful"...}

Create a frontend application

Bold provides two templates in the Open Source Checkout Templates repository:

note

The Open Source Checkout Templates make use of the Checkout Frontend Library to call the Bold Checkout APIs.

The following screenshot shows an example of the one page template:

Screenshot of one page template

Follow the instructions in this section to set up your application to use one of these templates.

Clone and configure the Open Source Checkout Templates

Complete the following steps to clone and configure the Open Source Checkout templates:

  1. Clone the project:
    git clone [email protected]:bold-commerce/checkout-experience-templates.git
    cd checkout-experience-templates
  2. Install the necessary node modules.
    1. If using npm, run npm install.
    2. If using yarn, run yarn install.
  3. Build the code.
    1. If using npm:
      1. Run npm run build-dev for development-mode JavaScript generation, which has debugging features.
      2. Run npm run build for production-mode JavaScript generation, which compresses the compiled JavaScript to reduce load time.
    2. If using yarn:
      1. Run yarn build-dev for development-mode JavaScript generation, which has debugging features.
      2. Run yarn build for production-mode JavaScript generation, which compresses the compiled JavaScript to reduce load time.
  4. The generated files are located in <path-to-project>/build.
  5. Run the project locally using npm run serve or yarn serve. Verify that you can see the built JavaScript file in your browser at localhost:8080/three_page.js or localhost:8080/one_page.js. There will be no user interface visible at this stage.

Define the browser Window object

The Open Source Checkout Templates must also have access to the browser's Window object.

In particular, the template requires the following standard properties and methods for the Window object:

In addition, you must add and define custom properties expected by the template. The following table describes the properties and how they are used:

PropertyTypeDescription
Window.initialTimestampsIFrontEndEvent or string objectTime stamps set to send event information to track speed.
Window.storeLoadTimesLocallybooleanIndicates whether to send event information used to track speed.
Window.environmentIEnvironmentA variable that sets the type of environment the app is running in order to call the correct Bold Checkout APIs. Possible values are 'production' and 'development'. For example:
Window.environment = {type: 'production'}
Window.bugsnagApiKeystring(Optional) An API key used to connect to BugSnag to report errors as they occur.
Window.customDomainstring(Optional) A vanity override for the Window.shopAlias URL. Shown to the customer when they are on the checkout page.
Window.enableConsoleboolean(Optional) Indicates whether to define an extra console.error that is printed to the console as errors happen.
Window.shopIdentifierstringThe identifier of your store, retrieved from the Get Shop Info endpoint.
Window.shopAliasstringUsed to create the URL to access the shop and to compose the URL to access the checkout page.
Window.shopNamestringThe name of the store. You can display this on the checkout page.
Window.headerLogoUrlstring(Optional) The URL of the image of the store's logo. You can display this on the Checkout page.
Window.returnUrlstringThe URL of the cart page. You can display this URL on the checkout page to allow the customer to return to the cart.
Window.loginUrlstringThe URL of the store login page. You can display this URL on the checkout page to allow the customer to log in.
Window.supportEmailstringAn email that a customer can use to contact the store. You can display this on the checkout page to allow the customer to contact support.
Window.platformTypestringThe platform the store uses. You can use this to compose the URL to load or redirect the checkout page.
Window.publicOrderIdstringThe public order ID generated when you initialize an order using the Initialize Order endpoint.
Window.initializedOrderstringThe application state of an order, returned from a call to the Initialize Order endpoint. If the order is for an authenticated customer, you can use the Add Authenticated Customer endpoint to initialize a checkout session with a logged-in order.

Indicate which template you want to use

You can only use one template per checkout flow. Because the Open Source Checkout Templates repository contains two templates, you must tell your backend application which one to display.

The Checkout Experience Backend project defaults to using the three-page template. If you want to use the one-page template instead, complete the following steps:

  1. In your database, navigate to the assets table. In the asset_name field, locate the 1 Page template and make note of the id.
  2. Navigate to the shop_assets table. Enter the id in the asset_id field.
  3. Reload the checkout frontend by running npm run build-dev. Your checkout should now display the one page template.

Override your storefront’s default checkout

The steps to override a checkout on your storefront are platform specific, which means that every ecommerce platform has a unique implementation.

The following sections include some general best practices to redirect the store's default checkout to the overriding Bold Checkout, as well as a sample for BigCommerce stores.

General approach

Complete the steps below to create a checkout override script for your platform:

  1. Construct a URL that points to <YOUR_PUBLIC_SERVER_URL>/experience/init/<SHOP_DOMAIN>.
    1. Replace <SHOP_DOMAIN> with the domain used when installing Bold Checkout on your store. For example, if <YOUR_PUBLIC_SERVER_URL> is checkout.examplestore.com, the <SHOP_DOMAIN> is examplestore.com. The resulting URL would be checkout.examplestore.com/experience/init/examplestore.com.
    2. Include the appropriate query parameters (see below).
  2. Update your storefront’s checkout buttons to use this new URL. The method for doing so varies between platforms.

Query Parameters

There are two main variations of query parameters that are supported:

The initialization variant creates a new order for the specified cart. This script is typically best for when the customer clicks the Checkout button for the first time.

ParameterTypeDescription
cart_idstringThe ID of the cart on your commerce platform. The exact structure of this string varies by platform.
return_urlstringConfigures where any “return-to-cart/store” links on the checkout should point to.
Note: If this parameter is excluded, these links will not resolve.
checkout_local_timenumber(Optional) A tool for tracking performance metrics. If included, this value must be the current unix timestamp.
customer_idstring(Optional) The ID of the customer on your commerce platform. Including this parameter causes checkout to be initialized as the user, allowing access to their saved customer information (addresses, payment methods, etc.).
Note: This project does not verify any customer information. All authentication must be done on the platform.
user_access_tokenstring(Optional) The access token for authenticated user. Required if the user is authenticated.

The resume variant resumes an order that is already in progress. This variant is useful for when a user refreshes the page or for custom communication (e.g., a custom abandoned cart email with a link to resume an order).

ParameterTypeDescription
public_order_idstringThe public order ID of the Bold Checkout order you wish to resume.
return_urlstringConfigures where any “return-to-cart/store” links on the checkout should point to.
Note: If this parameter is excluded, these links will not resolve.
checkout_local_timenumber(Optional) A tool for tracking performance metrics. If included, it should be the current unix timestamp.
customer_idstring(Optional) The ID of the customer on your commerce platform. Including this parameter causes checkout to be initialized as the user, allowing access to their saved customer information (addresses, payment methods, etc.).
Note: This project does not verify any customer information. All authentication must be done on the platform.
user_access_tokenstring(Optional) The access token for authenticated user. Required if the user is authenticated.

BigCommerce example

Bold provides a sample script for BigCommerce stores. Complete the steps below to redirect the BigCommerce checkout to the new checkout:

  1. Login to the store's BigCommerce admin portal.
  2. Navigate to Storefront >> Script Manager and create a new script with following values: Screenshot of BigCommerce &quot;Create Script&quot; admin
    1. Name of script: The unique script name.
    2. Description: A brief description.
    3. Location: Select Head option.
    4. Select pages where script will be added: Select Store pages option.
    5. Script category: Select Essential option.
    6. Script Type: Select Script option.
    7. Script Content: An example script can be found at resources/assets/bigcommerce/installation.js. Update CUSTOM_CHECKOUT_INIT_URL to match <YOUR_PUBLIC_SERVER_URL>.
  3. Test the checkout override. Navigate to your storefront, add an item to the cart, and click the checkout button. If working correctly, the site redirects you to Bold Checkout.

Next Steps

(Optional) Add express pay capabilities

The Open Source Checkout Templates include support for the Checkout Express Pay Library, which adds Google Pay, Apple Pay, Link (from Stripe), and PayPal Express options to your checkout.

When alternative payment gateways are enabled, the templates display an Express Checkout section at the top of the standard checkout page, as shown in the following image:

Screenshot of Express Checkout section in templates

Use the following steps to configure express and wallet payment methods on your store:

  1. In the Bold Checkout admin, navigate to Payment options >> Payment Gateways.
  2. In the Connect a payment gateway section, click the Alternative payment gateways drop-down.
  3. Next to each gateway you would like to add, click Connect. Complete the setup steps shown, which differ for each payment gateway.
  4. Once each alternative gateway is connected, it will automatically appear in the checkout.