A gateway-agnostic billing system with a fully-featured API and front-end control panel.
PHP CSS JavaScript
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Volcano Logo

Introduction

Volcano is an API-first billing solution that is capable of interfacing with a variety of payment gateways. Volcano offers both a robust, RESTful API as well as a fully-featured front-end control panel.

Volcano Control Panel

Mission

Volcano is meant to be a flexible, gateway-agnostic billing system. The system can be setup with one or more sellers, each of which has its own set of configurable products and customer base. Volcano's core elements include sellers, customers, products, product options, product fees, orders and transactions. Current goals for the project include additional features for these core elements and new light-weight CRM tools such as customer support ticket management.

Design

Volcano is built on top of the FuelPHP framework. The app is designed with multitenancy in mind and heavily leverages the adapter pattern for multi-gateway support and the service pattern for the core structure that powers both the API and front-end control panel. Additionally, both the API and control panel use the same core validation classes.

Volcano supports event-based callbacks. For example, Volcano can POST data to an external callback URL when a new customer is created. This allows 3rd party apps to handle their own email product messaging and feature ACL. Event callbacks can be setup via the API or the control panel Settings page.

Installation

First, ensure that your system meets FuelPHP's minimum requirements.

Next, clone the repo:

$ git clone -b master https://github.com/volcano/volcano.git volcano

Initialize all submodules:

$ cd volcano && git submodule update --init --recursive

Install Composer.

Install Composer dependencies:

$ php composer.phar install

Configuration

App

Create a new database.

Add these new database credentials to the appropriate database environment config(s) (fuel/app/config/[ENVIRONMENT]/db.php).

Run the setup task (sets file permissions and runs migrations):

$ php oil r setup

Setup the statistics and recurring tasks as crons that run every night. Something like this:

$ 00 00 * * * FUEL_ENV=production /usr/bin/php oil r recurring
$ 00 01 * * * FUEL_ENV=production /usr/bin/php oil r statistics

Optional: Run the simulate task to auto-generate faux seller, product, customer and order data. This will allow you to more easily test out various control panel features. Run the statistics task to compute stats for the simulated data.

$ php oil r simulate
$ php oil r statistics

API

For API development and testing, you'll want to first create a seller (see "Usage" below) and then create an API key via the control panel Settings page.

Next, copy the new seller API key and add it to fuel/app/config/development/api.php so that you don't have to specify the api_key param when testing locally.

##Usage

App

You'll be redirected to [YOUR DOMAIN]/setup the first time you access the Volcano control panel. This will allow you to create your first Seller. You may access [YOUR DOMAIN]/setup at any time to easily create additional sellers.

API

The API documentation contains a full list of available APIs. Here are a few examples:

Create a Product:

$ http -f POST /api/products/71687/options name="Product ABC"

Create a Customer:

$ http -f POST /api/customers contact[first_name]=Scatman contact[last_name]=John contact[email]=imthescatman@scatman.com

Create a Multi-Product Order for a Customer:

$ http -f POST /api/customers/120488428/orders products[4]="myappdomain.com" products[7]="My App Instance"