fred-pain

https://gitlab.office.nic.cz/fred/pain

Provides payment processor for FRED.

payments-pain

https://gitlab.office.nic.cz/ginger/payments-pain

Provides payment processor for Ginger Payments (and therefore the Academy).

PAIN_PROCESSORS

A required setting containing a dictionary of payment processor names and dotted paths to payment processors classes. The payments are offered to the payment processors in that order.

Example configuration:

PAIN_PROCESSORS = {
    'fred': 'fred_pain.processors.FredPaymentProcessor',
    'payments': 'payments_pain.processors.PaymentsPaymentProcessor',
    'ignore': 'django_pain.processors.IgnorePaymentProcessor',
}

You should not change processor names unless you have a very good reason. In that case, you also need to take care of changing processor names saved in the database.

When you change this setting (including the initial setup), you have to run django-admin migrate. Permissions for manual assignment to individual payment processors are created in this step.

PAIN_PROCESS_PAYMENTS_LOCK_FILE

Path to the lock file for the process_payments command. The default value is /tmp/pain_process_payments.lock.

PAIN_TRIM_VARSYM

Boolean setting. If True, bank statement parser removes leading zeros from the variable symbol. Default is False.

PAIN_DOWNLOADERS

A setting containing dotted paths to payment downloader and parser classes and downloader parameters. There should be a separate entry in the dictionary for each bank from which payments should be downloaded. The downloaders and parsers are provided in teller library.

Example configuration:

DOWNLOADERS = {'test_bank': {'DOWNLOADER': 'teller.downloaders.TestStatementDownloader',
                             'PARSER': 'teller.downloaders.TestStatementParser',
                             'DOWNLOADER_PARAMS': {'base_url': 'https://bank.test', 'password': 'letmein'}}}

PAIN_IMPORT_CALLBACK

List setting containing dotted paths to callables.

Each value of the list should be dotted path refering to callable that takes BankPayment object as its argument and returns (possibly) changed BankPayment. This callable is called right before the payment is saved during the import. Especially, this callable can throw ValidationError in order to avoid saving payment to the database. Default value is empty list.

PAIN_CSOB_CARD

Settings for CSOB card payment handler. API_PUBLIC_KEY, MERCHANT_ID and MERCHANT_PRIVATE_KEY contain parameters provided by CSOB bank. ACCOUNT_NUMBERS is a mapping assigning accounts to curency codes. CSOB payment gateway may accept payments in different currencies. For each currency there has to be an account held in that currency associated with the gateway. The associated accounts have to be specified in ACCOUNT_NUMBERS setting so we are able to choose the correct account when recording the payments in the application. The values of the mapping are account numbers as recorded in the database.

Example configuration:

PAIN_CSOB_CARD = {
    'API_PUBLIC_KEY': 'path_to_public_key.txt'),
    'MERCHANT_ID': 'abc123',
    'MERCHANT_PRIVATE_KEY': 'path_to_private_key.txt'),
    'ACCOUNT_NUMBERS': {
        'CZK': '123456',
        'EUR': '234567',
    },
}

CURRENCIES

A list of currency codes used in the application. The default is the list of all available currencies (which is pretty long).

Example configuration:

CURRENCIES = ['CZK', 'EUR', 'USD']

This setting comes from django-money app. Changing this setting requires generating migrations.

DEFAULT_CURRENCY

The currency code of the default currency. It should be one of the currencies defined in the CURRENCIES setting. The default is XYZ.

Example configuration:

DEFAULT_CURRENCY = 'CZK'

This setting comes from django-money app. Changing this setting requires generating migrations.

LANGUAGES

See Django docs. It is advisable to set this only to languages you intend to support. django-pain natively comes with English and Czech.

Currency formatting

In case Django does not format currencies correctly according to its locale setting it may be necessary to define the formatting rules manually:

from moneyed.localization import _FORMATTER as money_formatter
from decimal import ROUND_HALF_UP
money_formatter.add_formatting_definition(
    'cs', group_size=3, group_separator=' ', decimal_point=',',
    positive_sign='',  trailing_positive_sign='',
    negative_sign='-', trailing_negative_sign='',
    rounding_method=ROUND_HALF_UP
)

First argument of add_formatting_definition should be a properly formatted locale name from the LANGUAGES setting.

This setting comes from py-moneyed library.

import_payments

import_payments --parser PARSER [input file [input file ...]]

Import payments from the bank. A bank statement should be provided on the standard input or in a file as a positional parameter.

The mandatory argument PARSER must be a dotted path to a payment-parser class such as django_pain.parsers.transproc.TransprocXMLParser.

download_payments

download_payments [--start START] [--end END] [--downloader DOWNLOADER]

Download payments from the banks.

There are two optional arguments --start and --end which set the download interval for which the banks will be queried. Both parameters should be entered as date and time in ISO format. Default value for END is today. Default value for START is seven days before END.

Example download_payments --start 2020-09-01T00:00 --end 2020-10-31T23:59

Optional repeatable parameter --downloader selects which downloaders defined in the PAIN_DOWNLOADERS settings will be used. If the parameter is omitted all defined downloaders will be used.

Example download_payments --downloader somebank --downloader someotherbank

list_payments

list_payments [--exclude-accounts ACCOUNTS]
              [--include-accounts ACCOUNTS]
              [--limit LIMIT] [--state STATE]

List bank payments.

The options --exclude-accounts and --include-accounts are mutually exclusive and expect a comma-separated list of bank account numbers.

Option --state can be either ready_to_process, processed, deferred or exported.

If --limit LIMIT is set, the command will list at most LIMIT payments. If there are any non-listed payments, the command will announce their count.

process_payments

process_payments [--from TIME_FROM] [--to TIME_TO]

Process unprocessed payments with predefined payment processors.

The command takes all payments in the states ready_to_process or deferred and offers them to the individual payment processors. If any processor accepts the payment, then payment’s state is switched to processed. Otherwise, its state is switched to deferred.

The options --from and --to limit payments to be processed by their creation date. They expect an ISO-formatted datetime value.

2.4.0 (2023-01-11)

• Upgrade to CSOB eAPI 1.9

• Upgrade to Node.js 18

2.3.0 (2022-01-26)

• Add help text to enforce currency field

• Use account number instead of name in csob handler

• Select account by currency in csob handler

2.2.1 (2021-10-12)

• Skip to next processor after one fails

• Use teller 0.4

• Evaluate processor result inside try blok

2.2.0 (2021-08-13)

• Upgrade django-money

• Add type stubs

• Skip bank fees callback

• Fix requirements and tests for Django 3.0

• Test with Django up to version 3.2

• Fix default auto field warnings

• Convert amount to type Money and handle it correctly

• Convert currency to str for csob client

• Update test settings and fix licence check

• Do not run in parallel

• Allow empty counter account

2.1.1 (2021-05-20)

• Allow callback to cancel saving of a payment

2.1.0 (2021-04-29)

• Rise exception on invalid datetime

• Set default currency and allowed currencies

• Round money amounts to two decimal places

• Add README entry on currency formatting

• Add select for update to admin

• Fix thread synchronisation

• Use teller to download statements

• Allow to select subset of downloaders

• Add downloader cli param to README

• Add mixin for commands which save payments

• Do not check downloaders when not required and raw is missing

• Skip empty account with callback

• Pin teller version

• Add PaymentImportHistory

• Wrap admin views in a transaction

• Catch the OSError during import

• Use datetime as download_payments parameters

• Do not raise invalid account number for empty statements

• Lock the DB only when request is POST

2.0.0 (2020-10-06)

• Add support for Python 3.8

• Drop support for Django 2.1

• Add models for card payments

• Add Card payment handler and REST API

• Add get_card_payments_states mangagemend command

• Command process_payments now process also card payments.

• Add payment filtering by realized paymnets

• Add processing newly paid payments after status update by REST API

• Fix coverage of generators from payments processors

• Add transaction to retrieve() in REST API

• Allow only needed methods in BankPayment REST API

• Update state of only initialized card payments

• Return 503 while connection error during creating new card payment on gateway

• Fix FileSettings for Python 3.5

• Make PROCESSORS OrderedDict for tests to pass in Python 3.5

1.3.0 (2019-11-22)

• Update setup.py and requirements

• Return accidentally removed language switch

• Use constraints in tox

• Replace concurrent process_payments command info with warning

1.2.0 (2019-08-29)

• Including accounts in payment processing

• Add check for non-existing accounts

• Generate migration for django-money 0.15

• Update settings to allow multiple import callbacks

• Add skip_credit_card_transaction_summary import callback

• Move ignore_negative_payments callback to import_callbacks module

• Add favicon

1.1.0 (2019-04-29)

• Add separate permissions for manual assignment to individual payment processors

• Expand payment processors API to allow sending processing error codes. * Admissible processing error codes are defined in django_pain.constants.PaymentProcessingError enum. * This change is backward compatible.

• Add tax date to manual assignment of payment processor * If processor accepts a tax date, it has to have manual_tax_date set to True.

1.0.1 (2019-01-22)

• Added PAIN_TRIM_VARSYM setting.

• Fix czech translation of account invoice

0.3.0 (2018-07-24)

• Remove view PaymentListView

• Add django admin interface for accounts and payments [#21]

• Payment processors now must return payment objective [#21]

• Payment processors now must implement assign_payment method [#21]

• Use modeltranslation on BankPayment model

0.2.0 (2018-06-25)

• Change payment processors API to allow bulk processing [#19]

0.1.1 (2018-06-12)

• Add uuid field to BankPayment

0.1.0 (2018-06-11)

• Add bank statement parsers

• Add command import_payments

• Add bank payment processors

• Add command process_payments

• Add simple list view for payments

0.0.2 (2018-04-26)

• Add models BankAccount and BankPayment

• Update setup.py for PyPI release

0.0.1 (2018-04-17)

• Initial version