Getting Started

Note

These instructions make a distinction between making direct calls to the Helcim Commerce API versus using Helcim.js. Within this documentation, “Helcim API” refers to direct calls, where as “Helcim.js” will refere to calls via Helcim.js.

Install django-helcim and its Dependencies

Install django-helcim from PyPI. It is strongly recommended you use a virtual environment for your projects. For example, you can do this easily with Pipenv:

$ pipenv install django-helcim

If you are integrating this package with Django Oscar, you will need to install this package as well:

$ pipenv install django-oscar

Attention

If using Django Oscar, it is assumed you will manage the proper configuration. If needed, you can follow the setup instructions for Django Oscar.

Make sure to add django-helcim to your INSTALLED_APPS:

INSTALLED_APPS = [
   ...
   'helcim',
   ...
]

Edit your Django Settings

Once django-helcim has been installed, you will need to update your Django settings. You will need to specify the required settings depending on the workflow you are using.

For the Helcim API, you will need to specify the following settings (at a minimum): HELCIM_API_URL, HELCIM_ACCOUNT_ID, HELCIM_API_TOKEN, and HELCIM_TERMINAL_ID.

For Helcim.js, you will need to specify the HELCIM_JS_CONFIG setting (at a minimum).

There are several other settings available to configure django-helcim. In most cases, defaults are applied automatically when a setting is not specified. Where possible, the package defaults to the most restrictive value possible (given the security requirements of financial data). A full list of settings you can configure is available on the Settings page.

Add URLs

There are a couple views you can use to review and manage various aspects of the django-helcim models. You can enable these by updating the required settings and adding the package URLs:

from django.urls import path

urlpatterns = [
    path('helcim', include('helcim.urls')),
]

Final Details

Django Helcim also supplies some credit card logos to display with saved credit cards. To make use of these you will need to run collectstatic:

$ pipenv run python manage.py collectstatic

Next Steps

Once django-helcim is installed, you will need to integrate it into your payment workflow. This process will vary significantly between applications, but this application provides some standard objects and methods to streamline the process.

Working examples of integrations can be found in GitHub repo sandbox directory. You will find two working Django applications. The oscar sandbox is a working example of integration with Django Oscar. The scratch sandbox shows a minimal example of integration with a generic service requiring payment processing and demonstrates both the Helcim API and Helcim.js workflows.

See the Sandbox page for additional details on setting up and configuring the sandbox sites.