Billing gateways

Adding a new gateway to fleio

The following gateways already exist in fleio: paypal, stripe, romcard. Those are located in /var/webapps/fleio/ project/fleio/billing/gateways/ and you can find some inspiration from there when adding your desired gateway. To configure an existing gateway read the gateways configuration documentation

A gateway template exists here https://github.com/fleio/gateway-template, however the following instructions show information about each step required to create a new gateway template. Also, please note that each gateway has it’s own implementation and the following information might not be all that needs to be done so that the new gateway to work properly. For implementing a new gateway we highly recommend to talk to a python developer.

  • In the first place, you will need to create a new folder in the
    /var/webapps/fleio/project/fleio/billing/gateways/ location, e.g.: “newgateway”
cd /var/webapps/fleio/project/fleio/billing/gateways/
mkdir newgateway
  • Enter the directory and add the __init__.py file with the following code, replacing “newgateway” with your gateway name
default_app_config = 'fleio.billing.gateways.newgateway.apps.NewgatewayConfig'
  • Next step would be adding the apps.py file that should look like this:
from django.utils.translation import ugettext_lazy as _
from django.apps import AppConfig


class NewgatewayConfig(AppConfig):
    name = "fleio.billing.gateways.newgateway"
    verbose_name = _("NewGateway")
    fleio_module_type = 'payment_gateway'
    module_settings = {
        'capabilities': {
            'can_process_payments': True,
            'returns_fee_information': False
        }
    }

The returns_fee_information attribute from module_settings specifies if this gateway returns fee information. If so, fees will automatically be added to transactions otherwise they may be added from frontend on the /staff/billing/gateways page.

  • Now add the following files into the directory: models.py, newgateway.py and conf.py.

models.py file will be left empty and newgateway.py (named after the folder it is located in) will actually contain the code for processing payments, refunds, etc. The conf.py will be used for storing gateway credentials and other info that will be used when creating gateway functions in newgateway.py.

  • After adding the above files you will need to add the new app to django installed apps

To do so go to your settings.py file and add the following line of code

INSTALLED_APPS += ('fleio.billing.gateways.newgateway', )

Changing “newgateway” with the name of your gateways’ app.

  • Restart the django server. At this point, the gateway should be visible when going to the staff/billing/gateways page in the frontend dashboard panel.
  • Now add in the conf.py file your settings. It may look like this:
from django.conf import settings


class Conf(object):
    def __init__(self):
        self.newgateway_settings = getattr(settings, 'NEWGATEWAY_SETTINGS', {})
        self.test_mode = self.newgateway_settings.get('test_mode')
        self.secret_key = self.newgateway_settings.get('secret_key')
        self.callback_url = self.newgateway_settings.get('callback_url')

conf = Conf()

As you can see, the first line in the __init__(self) method gets the gateway settings dictionary from the settings.py file. You will need to define a dictionary in settings.py containing all the information and variables required by your gateway. The following lines just retrieve each value from the dictionary and assigns them to variables defined on the Conf class. After this, you’ll import the configuration and use its variables in the newgateway.py file.

The dictionary defined in settings.py may look like this given the above example:

NEWGATEWAY_SETTINGS = {
    'secret_key': 'whatever!@#$',
    'test_mode': True,
    'callback_url': 'https://fleio.com',
}
  • In the next step, we define the main methods used for processing payments. Go and edit the newgateway.py file.

At the top of the file, add the following imports:

from fleio.billing.gateways.decorators import gateway_action, staff_gateway_action

These decorators are used for functions that can be done by end-users or staff users. There is also the callback(request) function. This will be used in case you want to implement callbacks from the gateway (see the example from stripe.py file).

An example of pay_invoice function can be this:

from django.conf import settings
from django.http import HttpResponseRedirect

from .conf import conf

from fleio.billing.gateways.decorators import gateway_action, staff_gateway_action
from fleio.billing.gateways import exceptions as gateway_exceptions

from fleio.core.utils import fleio_join_url


def process_test_payment(test_mode):
    pass


@gateway_action(methods=['GET'])
def pay_invoice(request):
    invoice_id = request.query_params.get('invoice')

    try:
        process_test_payment(test_mode=conf.test_mode)
    except Exception as create_payment_exception:
        # handle possible exception
        raise gateway_exceptions.InvoicePaymentException(
            message=str(create_payment_exception),
            invoice_id=invoice_id
        )
    # redirect to invoice (or maybe render a gateway template)
    relative_url = 'billing/invoices/{}'.format(invoice_id)
    return HttpResponseRedirect(fleio_join_url(settings.FRONTEND_URL, relative_url))

You will now see that when paying an invoice this code gets executed.

Other decorated methods you can use:

  • Using the gateway_action decorator: pay_invoice, confirm_payment, cancel_payment,
  • Using the staff_gateway_action decorator: refund, capture

For rendering custom html pages you may find inspiration in the existing Stripe or Romcard gateways.