helcim package

Submodules

helcim.bridge_oscar module

Bridging module between Django Oscar and gateway module.

class helcim.bridge_oscar.BaseCardTransactionBridge(amount, token_id=None, card=None, billing_address=None, save_token=False, django_user=None, customer_code=None)

Bases: object

Base class to bridge Oscar and Helcim transactions.

Parameters:
  • order_number (str) – Order number for the transaction.
  • amount (dec) – The transaction total.
  • card (obj) – Instance of the Oscar bankcard class.
  • billing_address (dict) – The billing address information.
  • save_token (bool) – Whether the card token should be saved in the token vault or not.
  • django_user (obj) – The user to associate with the saved card token.
  • customer_code (str) – The Helcim customer code to associate with the saved card token.
class helcim.bridge_oscar.CaptureBridge(transaction_id)

Bases: object

Class to bridge Oscar and Helcim Capture transactions.

Parameters:transaction_id (int) – the Helcim preauthorization transaction ID to capture.
process()

Attempts to process Capture with transaction details.

Returns the values of gateway.Capture.process.

Raises:
  • GatewayError – An Oscar error raised when there was an error with the payment API.
  • PaymentError – An Oscar error raised when there was an error processing the payment.
class helcim.bridge_oscar.PreauthorizeBridge(amount, token_id=None, card=None, billing_address=None, save_token=False, django_user=None, customer_code=None)

Bases: helcim.bridge_oscar.BaseCardTransactionBridge

Class to bridge Oscar and Helcim preauthorization transactions.

process()

Attempts to process Preauthorize with transaction details.

Returns the values of gateway.Preauthorize.process.

Raises:
  • GatewayError – An Oscar error raised when there was an error with the payment API.
  • PaymentError – An Oscar error raised when there was an error processing the payment.
class helcim.bridge_oscar.PurchaseBridge(amount, token_id=None, card=None, billing_address=None, save_token=False, django_user=None, customer_code=None)

Bases: helcim.bridge_oscar.BaseCardTransactionBridge

Class to bridge Oscar and Helcim purchase transactions.

process()

Attempts to process Purchase with transaction details.

Returns the values of gateway.Purchase.process.

Raises:
  • GatewayError – An Oscar error raised when there was an error with the payment API.
  • PaymentError – An Oscar error raised when there was an error processing the payment.
class helcim.bridge_oscar.RefundBridge(amount, token_id=None, card=None, billing_address=None, save_token=False, django_user=None, customer_code=None)

Bases: helcim.bridge_oscar.BaseCardTransactionBridge

Class to bridge Oscar and Helcim refund transactions.

process()

Attempts to process Refund with transaction details.

Returns the values of gateway.Refund.process.

Raises:
  • GatewayError – An Oscar error raised when there was an error with the payment API.
  • PaymentError – An Oscar error raised when there was an error processing the payment.
class helcim.bridge_oscar.VerificationBridge(amount, token_id=None, card=None, billing_address=None, save_token=False, django_user=None, customer_code=None)

Bases: helcim.bridge_oscar.BaseCardTransactionBridge

Class to bridge Oscar and Helcim Verification transactions.

process()

Attempts to process Verification with transaction details.

Returns the values of gateway.Verification.process.

Raises:
  • GatewayError – An Oscar error raised when there was an error with the payment API.
  • PaymentError – An Oscar error raised when there was an error processing the payment.
helcim.bridge_oscar.remap_oscar_billing_address(address)

Remaps Oscar billing address dictionary to Helcim dictionary.

Parameters:address (dict) – A dictionary of the billing address details provided by Django Oscar.
Returns:
Billing address details formatted for
django-helcim.
Return type:dict
helcim.bridge_oscar.remap_oscar_credit_card(card)

Remaps Oscar credit card object as Helcim dictionary.

Parameters:card (obj) – A credit card object provided by Django Oscar.
Returns:Credit card details formatted for django-helcim.
Return type:dict
helcim.bridge_oscar.retrieve_saved_tokens(django_user=None, customer_code=None)

Shortcut for retrieve_saved_tokens from the Gateway module.

Added as a convenience to allow access to core functions via the bridge module exclusively.

helcim.bridge_oscar.retrieve_token_details(token_id, django_user=None, customer_code=None)

Shortcut for retrieve_token_details from the Gateway module.

Added as a convenience to allow access to core functions via the bridge module exclusively.

helcim.conversions module

Process and validates data to and from the Helcim API.

class helcim.conversions.Field(api_name, field_type='s', min_length=None, max_length=None)

Bases: object

A single API field.

Parameters:
  • api_name (str) – The Helcim API field name for the field.
  • field_type (str) – The field type: s (string), c (decimal), i (integer), b (boolean), d (date), or t (time).
  • min (int, optional) – The minimum field length.
  • max (int, optional) – The maximum field length.
helcim.conversions.convert_helcim_response_fields(fields, field_dictionary)

Converts provided Helcim response to Python data types.

Handles both API responses and Helcim.js response.

Parameters:
  • fields (dict) – Helcim response fields.
  • field_dictionary (dict) – dictionary of field references to use for data type conversion.
Returns:

converted fields as Python data types.
Return type:

dictionary
helcim.conversions.create_f4l4(cc_number)

Creates the token_f4l4 value if a CC number is provided.

Parameters
cc_number (str): The Helcim response CC number.
Returns:the token F4L4 value.
Return type:string
helcim.conversions.create_raw_request(data)

Converts the raw request into a POST string.

Parameters:data (dict) – The POST request data dictionary.
Returns:The POST request data as a formatted string.
Return type:str
helcim.conversions.process_api_response(response, raw_request=None, raw_response=None)

Updates API field names/types, and adds additional data.

Parameters:
  • response (str) – The API response (as an OrderedDict).
  • raw_request (str) – Raw request (as string) submitted to API.
  • raw_response (str) – Raw response (as string) returned by API.
Returns:

The validated and converted API response.
Return type:

dict
helcim.conversions.process_helcim_js_response(response)

Processes the Helcim.js response into a Python dictionary.

Parameters:response (dict) – The Helicm.js POST response.
Returns:The validated and converted Helcim.js response.
Return type:dict
helcim.conversions.process_request_fields(api, cleaned, additional=None)

Converts all data to proper Helcim API request fields.

Parameters:
  • api (dict) – The API setting fields.
  • cleaned (dict) – The cleaned POST data.
  • additional – Any additional POST data to directly add (skips any conversion steps).
Returns:

The data ready for a POST request.
Return type:

dict
helcim.conversions.validate_request_fields(details)

Validates and coerces request field data prior to submission.

Uses the TO_API_FIELDS dictionary to determine type and required validation to apply.

Parameters:details (dict) – The values to validated and coerce.
Returns:The cleaned data (with the same keys as details).
Return type:dict
Raises:ValueError – Raised if data fails validation.

helcim.exceptions module

Custom exceptions for django-helcim.

exception helcim.exceptions.DjangoError

Bases: helcim.exceptions.HelcimError

Exception for issues relating to Django interface.

exception helcim.exceptions.HelcimError

Bases: Exception

Base exception for all package exceptions.

exception helcim.exceptions.PaymentError

Bases: helcim.exceptions.HelcimError

Exception to handle payments, pre-auths, and captures.

exception helcim.exceptions.ProcessingError

Bases: helcim.exceptions.HelcimError

Exception to handle system and API connection errors.

exception helcim.exceptions.RefundError

Bases: helcim.exceptions.HelcimError

Exception to handle refund errors.

exception helcim.exceptions.VerificationError

Bases: helcim.exceptions.HelcimError

Exception to handle errors during credit care verification.

helcim.gateway module

Interface functions with the Helcim Commerce API.

These functions provide an agonstic interface with the Helcim Commerce API and should work in any application.

class helcim.gateway.BaseCardTransaction(save_token=False, **kwargs)

Bases: helcim.gateway.BaseRequest

Base class for transactions involving credit card details.

determine_card_details()

Confirms valid payment details and updates self.cleaned.

Cycles through the provided details to determine the most appropriate payment method. If multiple methods provided, only the first match is returned (token > customer code > CC number > encrypted magnetic strip > magnetic strip).

Raises:ValueError – No valid payment details provided.
class helcim.gateway.BaseRequest(api_details=None, django_user=None, **kwargs)

Bases: helcim.mixins.ResponseMixin

Base class to handle validation and submission to Helcim API.

Parameters:
  • api_details (dict) –

    Details to connect to Helcim API:

    • url (str): API URL.
    • account_id (str): Helcim account ID.
    • token (str): Helcim API token.
    • terminal_id (str): Helcim terminal ID.
  • django_user (obj) – The Django model for the requesting user.
  • **kwargs (dict) – Any additional transaction details.
Keyword Arguments:
 
  • amount (dec, optional) – The amount for the transaction.
  • currency (str, optional) – The currency for the transaction.
  • cc_name (str, optional) – Name of the credit cardholder.
  • cc_number (str, optional) – 16 digit credit card number.
  • cc_expiry (str, optional) – 4 digit (MMYY) credit card expiry.
  • cc_cvv (str, optional) – 3 or 4 digit credit card CVV.
  • cc_address (str, optional) – Address of the credit cardholder.
  • cc_postal_code (str, optional) – Postal code/zip code of the credit cardholder.
  • customer_code (str, optional) – Helcim customer code.
  • token (str, optional) – 23 digit Helcim card token.
  • token_f4l4 (str, optional) – 8 digit “first four digits and last four digits” of the credit card number
  • token_f4l4_skip (bool, optional) – Whether to skip the F4L4 verification.
  • mag (string, optional) – Non-encrypted credit card magnetic strip data.
  • mag_enc (str, optional) – Encrypted credit card magnestic strip data.
  • mag_enc_serial_number (string, optional) – Terminal serial number.
  • order_number (str, optional) – An assigned order number for the purchase.
  • ecommerce (bool, optional) – Whether this is an e-commerce transaction or not.
  • comments (str, optional) – Any additional comments with this transaction.
  • billing_contact_name (str, optional) – Billing address contact name.
  • billing_business_name (str, optional) – Billing address business name.
  • billing_street_1 (str, optional) – Billing street address (line 1).
  • billing_street_2 (str, optional) – Billing street address (line 2).
  • billing_city (str, optional) – Billing city.
  • billing_province (str, optional) – Billing province.
  • billing_country (str, optional) – Billing country.
  • billing_postal_code (str, optional) – Billing postal code.
  • billing_phone (str, optional) – Billing phone number.
  • billing_fax (str, optional) – Billing fax number
  • billing_email (str, optional) – Billing email.
  • shipping_contact_name (str, optional) – Shipping contact name.
  • shipping_business_name (str, optional) – Shipping business name.
  • shipping_street_1 (str, optional) – Shipping street address (line 1).
  • shipping_street_2 (str, optional) – Shipping street address (line 2).
  • shipping_city (str, optional) – Shipping city.
  • shipping_province (str, optional) – Shipping province.
  • shipping_country (str, optional) – Shipping country.
  • shipping_postal_code (str, optional) – Shipping postal code.
  • shipping_phone (str, optional) – Shipping phone number.
  • shipping_fax (str, optional) – Shipping fax number.
  • shipping_email (str, optional) – Shipping email address.
  • amount_shipping (dec, optional) – Shipping cost.
  • amount_tax (dec, optional) – Tax amount.
  • shipping_method (str, optional) – Method of shipping.
  • tax_details (str, optional) – Name for the tax (e.g. GST).
  • test (bool, optional) – Whether this is a test transaction or not.
configure_test_transaction()

Adds test flag to post data if HELCIM_API_TEST is True.

Method applies to the cleaned data (not the raw POST data). If the test flag is declared in both the POST data and Django settings file, the POST data takes precedence.

post(post_data=None)

Makes POST to Helcim API and updates response attribute.

Parameters:post_data (dict) – The parameters to pass with the POST request.
Raises:ProcessingError – An error occurred connecting or communicating with Helcim API.
process_error_response(response_message)

Returns error response with proper exception type.

Parameters:

response_message (str) – The API error response message.
Raises:
  • PaymentError – Raised for any errors returned during a purchase or refund transaction.
  • HelcimError – Raised for any other unhandled errors.
save_transaction(transaction_type)

Saves provided transaction data as Django model instance.

Parameters:transaction_type (str) – The type of transaction (s for purchase (sale), p for pre-authorization, c for capture, and r for refund).
Returns:A Django model instance of the saved data.
Return type:obj
Raises:DjangoError – Issue when attempting to save transaction to database.
set_api_details(details)

Sets the API details for this transaction.

Will either return a dictionary of the API details from the provided details argument, or will look to the Django settings file.

Parameters:details (dict) – A dictionary of the API details.
Returns:The proper API details from the provided data.
Return type:dict
Raises:ImproperlyConfigured – A required API setting is not found.
validate_fields()

Validates Helcim API request fields and coerces values.

class helcim.gateway.Capture(api_details=None, django_user=None, **kwargs)

Bases: helcim.gateway.BaseRequest

Makes a capture request (to complete a preauthorization).

process()

Completes a capture request.

validate_preauth_transaction()

Confirms that a preauth transaction ID was provided.

Raises:PaymentError – Error when no transaction ID provided.
class helcim.gateway.HelcimJSResponse(response, save_token=False, django_user=None)

Bases: helcim.mixins.ResponseMixin

Class to handle Helcim.js Responses.

This is a helper class that takes a Helcim.js response, handles any errors, converts the response into Python types and applies any redactions.

Handling is more limited since all requests to the API are handled directly by Helcim.js. It is important to note that responses from Helcim.js are similar, but not identical to the basic Helcim API.

Parameters:
  • response (obj) – the Helcim.js response POST data.
  • save_token (bool) – whether to save this to the django-helcim token vault.
  • django_user (obj) – a django user instance to use with django-helcim model instances.
is_valid()

Validates format is correct and notifies of any errors.

Will also generate the redacted response at this point.

Returns:True if valid without errors, otherwise false.
Return type:boolean
record_preauthorization()

Saves validated preauthorization response to database.

Returns:
tuple of the HelcimTransaction and HelcimToken instances.
HelcimToken will be None if token is not saved.
record_purchase()

Saves validated purchase response to database.

Returns:
tuple of HelcimTransaction and HelcimToken instances.
HelcimToken will be None if token is not saved.
Return type:tuple
record_verification()

Saves validated verification response to database.

Returns:
tuple of the HelcimTransaction and HelcimToken instances.
HelcimToken will be None if token is not saved.
class helcim.gateway.Preauthorize(save_token=False, **kwargs)

Bases: helcim.gateway.BaseCardTransaction

Makes a pre-authorization request to Helcim Commerce API.

process()

Makes a pre-authorization request.

class helcim.gateway.Purchase(save_token=False, **kwargs)

Bases: helcim.gateway.BaseCardTransaction

Makes a purchase request to Helcim Commerce API.

process()

Makes a purchase request.

Returns:
The saved HelcimTransaction model
instance and HelcimToken model.
Return type:tuple
class helcim.gateway.Refund(save_token=False, **kwargs)

Bases: helcim.gateway.BaseCardTransaction

Makes a refund request.

process()

Makes a refund request to Helcim Commerce API.

class helcim.gateway.Verification(save_token=False, **kwargs)

Bases: helcim.gateway.BaseCardTransaction

Makes a verification request to Helcim Commerce API.

process()

Makes a verification request to Helcim Commerce API.

helcim.gateway.retrieve_saved_tokens(django_user=None, customer_code=None)

Returns list of tokens for specified customer.

Parameters:
  • django_user (obj) – A Django user model instance.
  • customer_code (str) – A Helcim customer code.
Returns:

A queryset of the retrieved tokens
Return type:

obj
helcim.gateway.retrieve_token_details(token_id, django_user=None, customer_code=None)

Takes a HelcimToken ID and maps details to dictionary.

helcim.mixins module

Mixins to help support Helcim API interactions.

class helcim.mixins.HelcimJSMixin

Bases: object

Provides Helcim.js URL and token details in the view context.

This is a helper mixin that allows you to declare your Helcim.js configuration details within your Django settings. They are then injected into the view context to allow you to easily declare them within a template.

get_context_data(**kwargs)

Overrides the view method to add Helcim.js details.

class helcim.mixins.ResponseMixin

Bases: object

Methods to support handling a Helcim repsonse.

Handles some data manipulations to prepare for saving to a model instance and applies relevant redactions to data.

create_model_arguments(transaction_type)

Creates dictionary for use as transaction model arguments.

Takes the redacted_response data and creates a dictionary that can be used as the keyword argumetns for the HelcimTransaction model.

Parameters:transaction_type (str) – Transaction type for this transaction.
Returns:dictionary of the HelcimTransaction arguments.
Return type:dict
redact_data()

Removes sensitive and identifiable data.

By default will redact API fields and populate redacted_response attribute. Depending on Django settings, may also redact other fields in the formated and raw response.

save_token_to_vault()

Saves Helcim card token.

Returns:
The HelcimToken model instance, or None (if
model not created).
Return type:obj
save_transaction(transaction_type)

Saves HelcimTransaction with redacted response details.

helcim.models module

Models for the django-helcim application.

class helcim.models.HelcimToken(*args, **kwargs)

Bases: django.db.models.base.Model

A Helcim card token.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

cc_expiry

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

cc_name

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

cc_type

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

customer_code

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

date_added

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

display_as_card_number

Displays token_f4l4 as a 16 character credit card number.

django_user

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

django_user_id
get_credit_card_png

Returns a path to a credit card .png for this token.

get_credit_card_svg

Returns a path to a credit card .svg for this token.

get_next_by_date_added(*, field=<django.db.models.fields.DateTimeField: date_added>, is_next=True, **kwargs)
get_previous_by_date_added(*, field=<django.db.models.fields.DateTimeField: date_added>, is_next=False, **kwargs)
id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>
token

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

token_f4l4

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

class helcim.models.HelcimTransaction(*args, **kwargs)

Bases: django.db.models.base.Model

Details of a single Helcim transaction.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

TRANSACTION_TYPES = (('s', 'purchase (sale)'), ('p', 'pre-authorization'), ('c', 'capture'), ('r', 'refund'), ('v', 'verify'))
amount

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

approval_code

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

avs_response

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

can_be_captured

Check if this transaction can be captured.

can_be_refunded

Check if this transaction can be refunded.

cc_expiry

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

cc_name

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

cc_number

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

cc_type

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

currency

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

customer_code

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

cvv_response

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

date_created

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

date_response

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

django_user

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

django_user_id
get_next_by_date_created(*, field=<django.db.models.fields.DateTimeField: date_created>, is_next=True, **kwargs)
get_next_by_date_response(*, field=<django.db.models.fields.DateTimeField: date_response>, is_next=True, **kwargs)
get_previous_by_date_created(*, field=<django.db.models.fields.DateTimeField: date_created>, is_next=False, **kwargs)
get_previous_by_date_response(*, field=<django.db.models.fields.DateTimeField: date_response>, is_next=False, **kwargs)
get_transaction_type_display(*, field=<django.db.models.fields.CharField: transaction_type>)
id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

notice

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>
order_number

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

raw_request

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

raw_response

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

response_message

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

token

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

token_f4l4

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

transaction_id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

transaction_success

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

transaction_type

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

helcim.settings module

Determines relevant settings for django-helcim functioning.

helcim.settings.determine_helcim_settings()

Collects all possible django-helcim settings for easy use.

Performs basic validation of required settings and assigns defaults where applicable.

Returns:Summary of all possible django-helcim settings.
Return type:dict

helcim.views module

Views for Helcim Commerce API transactions.

class helcim.views.TokenDeleteView(**kwargs)

Bases: django.contrib.auth.mixins.PermissionRequiredMixin, django.views.generic.edit.DeleteView

Allows deletion of a Helcim API token.

context_object_name = 'token'
delete(request, *args, **kwargs)

Override delete to allow success message to be added.

model

alias of helcim.models.HelcimToken

permission_required = 'helcim.helcim_tokens'
pk_url_kwarg = 'token_id'
raise_exception = True
success_message = 'Token successfully deleted.'
success_url
template_name = 'helcim/token_delete.html'
class helcim.views.TokenListView(**kwargs)

Bases: django.contrib.auth.mixins.PermissionRequiredMixin, django.views.generic.list.ListView

List of all transactions submitted made by django-helcim.

context_object_name = 'tokens'
model

alias of helcim.models.HelcimToken

permission_required = 'helcim.helcim_tokens'
raise_exception = True
template_name = 'helcim/token_list.html'
class helcim.views.TransactionDetailView(**kwargs)

Bases: django.contrib.auth.mixins.PermissionRequiredMixin, django.views.generic.detail.DetailView

Details of a specific transaction made by django-helcim.

capture()

Processes a capture transaction.

context_object_name = 'transaction'
get_context_data(**kwargs)

Insert the single object into the context dict.

model

alias of helcim.models.HelcimTransaction

permission_required = 'helcim.helcim_transactions'
pk_url_kwarg = 'transaction_id'
post(request, *args, **kwargs)

Handles any capture and refund requests.

raise_exception = True
refund()

Processes a refund transaction.

template_name = 'helcim/transaction_detail.html'
class helcim.views.TransactionListView(**kwargs)

Bases: django.contrib.auth.mixins.PermissionRequiredMixin, django.views.generic.list.ListView

List of all transactions submitted made by django-helcim.

context_object_name = 'transactions'
model

alias of helcim.models.HelcimTransaction

permission_required = 'helcim.helcim_transactions'
raise_exception = True
template_name = 'helcim/transaction_list.html'