Solidus Bolt

CircleCI codecov

Installation

Add solidus_bolt to your Gemfile:

gem 'solidus_bolt'

Bundle your dependencies and run the installation generator (before running the following command, we recommend setting up the environment variables and seeds as described in the sections below):

bin/rails generate solidus_bolt:install

Usage

Setting up Bolt Configuration

Many of the API calls handled by this gem use the variables set in Bolt Configuration. Since this extension's seeds automatically generate a Bolt Configuration, the easiest and safest way to configure it would be by setting the following environment variables:

BOLT_ENVIRONMENT
BOLT_API_KEY
BOLT_SIGNING_SECRET
BOLT_PUBLISHABLE_KEY

Alternatively you can setup the Bolt Configuration manually by visiting /admin/bolt

Using solidus_bolt Seeds

Provided you setup the environment variables, you can simplify the setup of a Bolt application by running the gem's seeds. This will automatically create the following:

  • BoltConfiguration
  • AuthenticationMethod
  • PaymentMethod

You can run solidus_bolt's seeds either by running

bin/rails db:seed:solidus_bolt

or by adding the following line to your seed file:

SolidusBolt::Engine.load_seed if defined?(SolidusBolt)

Creating a new Payment Method

Assuming you've used environment variables to configure your Bolt Configuration, creating a Bolt payment method is very easy:

  1. Visit /admin/payment_methods/new
  2. Set provider to SolidusBolt::PaymentMethod
  3. Click "Save"
  4. Choose bolt_credentials from the Preference Source select
  5. Click Update to save

If you've instead decided to setup the Bolt Configuration manually, follow the same process mentioned above but at step 4 pick bolt_config_credentials instead of bolt_credentials.

In both cases you can alternatively create a payment method from the Rails console with:

SolidusBolt::PaymentMethod.create(
  name: "Bolt",
  preference_source: "bolt_credentials" # or "bolt_config_credentials"
)

The final (not recommended) option is to not select any Preference Source at step 4 and instead fill up the inputs manually.

How to set the webhooks

(For latest up to date guide check Bolt's Documentation)

  1. Login to your Bolt Merchant Dashboard.

  2. Navigate to Developers.

  3. Scroll to Merchant API.

  4. Add your webhook endpoints (by default it's your store's url plus /webhooks/bolt)

Important use cases include:

  • Notifying your e-commerce store when a transaction has been approved or rejected by Bolt.
  • Sending your e-commerce store with the transaction_id, which is necessary for back-office operations.
  • Sending your e-commerce store more information about a transaction such as credit card details.

Development

Testing the extension

First bundle your dependencies, then run bin/rake. bin/rake will default to building the dummy app if it does not exist, then it will run specs. The dummy app can be regenerated by using bin/rake extension:test_app.

bin/rake

To run Rubocop static code analysis run

bundle exec rubocop

When testing your application's integration with this extension you may use its factories. Simply add this require statement to your spec/spec_helper.rb:

require 'solidus_bolt/testing_support/factories'

Or, if you are using FactoryBot.definition_file_paths, you can load Solidus core factories along with this extension's factories using this statement:

SolidusDevSupport::TestingSupport::Factories.load_for(SolidusBolt::Engine)

Special Tests

A few tests in the test suite require some additional steps to execute successfully when they are modified. These are listed below along with the steps needed to execute these tests.

  • /spec/services/solidus_bolt/accounts/detail_service_spec.rb This test requires a valid bolt_access_token to execute successfully when modified. Follow the steps below to get a bolt_access_token.
    1. Login as a User using a Bolt Account.
    2. Put a binding.pry on any view.
    3. Print session['bolt_access_token'] in the pry console.
    4. Copy the result and set the value of the environment variable BOLT_ACCESS_TOKEN to this result.

Running the sandbox

To run this extension in a sandboxed Solidus application, you can run bin/sandbox. The path for the sandbox app is ./sandbox and bin/rails will forward any Rails commands to sandbox/bin/rails.

Here's an example:

$ bin/rails server
=> Booting Puma
=> Rails 6.0.2.1 application starting in development
* Listening on tcp://127.0.0.1:3000
Use Ctrl-C to stop

Updating the changelog

Before and after releases the changelog should be updated to reflect the up-to-date status of the project:

bin/rake changelog
git add CHANGELOG.md
git commit -m "Update the changelog"

Releasing new versions

Please refer to the dedicated page on Solidus wiki.

License

Copyright (c) 2022 [name of extension author], released under the New BSD License.