¶ Cycle
¶ Running a billing cycle
- under the ‘Billing Cycle’ → ‘Run’ tab you can select the desired month to run a billing cycle for.
- Cycles are going by date-ranges depending on the system configuration field
‘charging day’ in the settings. You can only run a billing cycle after the cycle end-date. - You can choose whether you wish to produce PDF files for the invoices created.
- This process might take some time, depending on the size of your DB - you can view the percentage of the progress while it is running.
- Once the aggregation process is over, you will be able to go over each invoice (in case you chose to produce a PDF for them) and verify charge amount etc.
¶ Transaction request
The Custom Payment Gateway (CPG) module lets BillRun exchange payment files with an external party — a payment gateway, bank, or clearing house. It is built around two separate but complementary features that together form one payment cycle:
¶ Transactions Request (outgoing)
BillRun generates a file containing the payments it wants to charge (or refund), and sends it to the gateway. Each line in the file corresponds to a pending payment created in BillRun. This is the “ask” side of the cycle.
¶ Transactions Response (incoming)
The gateway later returns a file telling BillRun which of those transactions succeeded or failed. BillRun receives and parses that file and updates each payment accordingly — confirming the successful ones and rejecting the failed ones. This is the “answer” side of the cycle.
¶ Transaction request files (outgoing)
The Transactions Request File feature produces a structured payment request file containing outstanding customer debts (or credits), to be sent to an external payment gateway, bank, or clearing house for processing.
For every eligible account, the generator creates a pending payment record in BillRun and writes a corresponding line to the request file. The transactions in the file then wait for the gateway's response file (Transactions Response), which confirms or rejects each payment.
The GUI to manage the transaction request is available on Account Receivables → Transaction Request File
¶ Parameters
| Parameter | Description |
|---|---|
aids |
Include only the listed account IDs. |
invoices |
Include only the listed invoice IDs. |
exclude_accounts |
Exclude the listed account IDs. |
billrun_key |
Limit to bills of a specific billing cycle. |
min_invoice_date |
Include only invoices from this date onward. |
mode |
charge (positive amounts only) or refund (negative amounts only). |
pay_mode |
one_payment (default — one aggregated payment per account) or multiple_payments (payment per invoice). Any other value is rejected. |
Empty system parameters are ignored
¶ How it runs
- A user (via the transaction request files screen) or an external system calls the generation API.
- The request is validated and a background process is started.
- The generator selects the configuration entry whose file_type matches the request, loads eligible bills, and builds the file (header, data lines, trailer).
- For each account it creates a pending payment, locks the account during charging, and writes the configured fields to the line.
- The file is written to the export directory and the run is logged.
¶ The generation API
Endpoint: /custompaymentgateway/generateTransactionsRequestFile — Permission: write-level.
| Parameter | Required | Description |
|---|---|---|
| payment_gateway | Yes | Name of the gateway. Must exist in the payment_gateways configuration. |
| file_type | Yes | The transactions_request file type to generate. |
| parameters | No | JSON object of extra parameters: system filters and/or custom (file-type-defined) parameters. Invalid JSON is rejected. |
| pay_mode | No | one_payment (default — one payment per account) or multiple_payments (one per invoice). |
System filter parameters (inside parameters): aids, invoices, exclude_accounts, billrun_key, min_invoice_date, mode (charge or refund), and pay_mode.
¶ Configurations
The file structure and behavior are defined per gateway/file type under the payment_gateways configuration (transactions_request section). Key options include:
¶ Top-level options
| Option | Required / default | Description |
|---|---|---|
| file_type | Required | Identifier of this definition; matched against the file_type request parameter. |
| generator | Required | Output format and line layouts (see generator block section). |
| filename / filename_params | Optional | Template and parameters used to build the output file name. |
| export | Required to send | Export/connection details. export.export_directory is where the file is written and sent from. |
| backup_path | Optional; falls back to export_directory then a default | Local backup directory for the generated file. |
| parameters | Optional | Declarations of extra input parameters accepted from the API (see field objects section). |
| filtration | Optional | accounts and placeholders conditions controlling which records are included (see parameters section). |
| file_status | Optional; default waiting_for_confirmation | Initial state of the generated payments (see filtration and file_status section). |
| affects_bills | Optional; default true | If true, payment records are created and saved against bills; if false, lines are produced without creating payments. |
¶ The generator block
| Field | Required / default | Description |
|---|---|---|
| type | Required | Output format: fixed or separator (CSV-family) or xml. |
| separator | When type=separator | The delimiter character. |
| row_separator | Optional; default line_break | Delimiter between rows. |
| max_records | Optional | Maximum number of data records per file. |
| header_structure | Optional | Array of field objects describing the header line. |
| data_structure | Required | Array of field objects describing each data line. |
| trailer_structure | Optional | Array of field objects describing the trailer line. |
¶ Field objects (inside the *_structure arrays)
Each field is an object. path is required (the field’s position/key in the output line); the remaining keys define the value source and formatting. A field has exactly one value source.
| Field key | Role | Description |
|---|---|---|
| name | Identity | Logical field name (used in log and error messages). |
| path | Required | Output position/key of the field in the line. |
| hard_coded_value | Value source | A constant value. |
| predefined_values | Value source | A computed value: now (timestamp), transactions_num (count; header/trailer), transactions_amount (sum; header/trailer), log_stamp (generated log stamp). |
| linked_entity | Value source | Pulls a value from another entity: { entity: account | payment_request, field_name: <field> }. When entity is account, the field is treated as mandatory for the account. |
| parameter_name | Value source | Uses the value of a custom input parameter (must be declared under parameters and supplied in the request). |
| type | Value source / format | Special types: autoinc (sequence; requires min_value/max_value, optional date_group), record_autoinc (per-record counter), plus standard formatting types. |
| save_to_bill | Behavior | If true, the generated value is also stored on the bill/payment (under pg_request). |
| attributes | Format | Extra per-line attributes passed to the file writer. |
| padding | Format | Padding definition for fixed-width output. |
| regex | Validation | Validation/extraction pattern for the value. |
¶ Parameters (custom input parameters)
| Field key | Required / default | Description |
|---|---|---|
| name / field_name | Required | Parameter name. field_name takes precedence if both are present. |
| type | Optional; default string | Expected value type. |
| mandatory | Optional; default required | Whether the parameter must be supplied. |
| regex | Optional | Validation pattern for the supplied value. |
¶ Filtration and file_status
filtration.accounts lists conditions an account must meet to be included. filtration.placeholders lists conditions on the payment itself (for example on amount or payment_direction).
| file_status value | Effect on generated payments |
|---|---|
| waiting_for_confirmation | Default. Payments stay pending until a matching Transactions Response file confirms or rejects them. |
| assume_approved | Payments are pre-approved — flagged as approved immediately, without waiting for a response file. |
¶ Transactions Response file (incoming)
BillRun receives a file from the gateway, parses each line, matches each line back to the original pending payment, and updates that payment’s status. Successful transactions are confirmed; failed transactions are rejected and a rejection record is created. Selected fields from the response can be saved back onto the bill/payment.
¶ 3.2 How it runs
The file is collected from the gateway (typically via the configured receiver, e.g. over SSH).
The processor selects the configuration entry whose file_type matches, then validates that the required mapping fields are present (amount field and a transaction identifier).
The parser splits each line according to the parser definition (header, data, trailer).
For each data line, the processor finds the matching payment using the configured identifier, then classifies the line as success or rejection.
The matched payment is confirmed or rejected, response fields are stored, and the run is logged.
¶ Configurations
| Option | Required / default | Description |
|---|---|---|
| file_type | Required | Identifier of this definition; matched against the incoming file’s type. |
| receiver | Optional | How to fetch incoming files. Contains connections (see receiver.connections section). |
| parser | Required | How to read each line into named fields (see parser block section). If missing, processing fails. |
| processor | Required | How to interpret the parsed fields: identify the payment, amount, status, etc. (see processor block section). |
| file_status | Optional | Controls how the whole file is interpreted (see file_status values section). When empty or mixed, each line is classified individually. |
| ignore_duplicates | Optional; default false | If true, lines are not tagged with a per-line record number for de-duplication. |
| correlation | Required for only_* statuses | Links a response file back to its request file (source, field, file_field). |
| response_files_count | Required for only_* statuses | Number of response files expected for one request file. |
¶ receiver.connections
| Field | Description |
|---|---|
| connection_type | Transport, e.g. ssh. |
| host | Server hostname or address. |
| user | Login user. |
| password | Login password (or key, depending on transport). |
| remote_directory | Directory on the server to read from. |
| filename_regex | Pattern selecting which files to pick up. |
¶ The parser block
| Field | Required / default | Description |
|---|---|---|
| type | Required | How lines are split, e.g. separator. |
| separator | When type=separator | The delimiter character. |
| header_structure | Optional | Ordered list of fields in the header line. |
| data_structure | Required | Ordered list of fields in each data line (see data-structure field objects section). |
| trailer_structure | Optional | Ordered list of fields in the trailer line. |
| csv_has_header | Optional | Whether the file includes a header line. |
| csv_has_footer | Optional | Whether the file includes a footer/trailer line. |
| line_types | Optional | Regex map classifying each raw line (e.g. which lines are data lines). |
¶ The processor block
At least amount_field and one of transaction_identifier_field / transaction_identifier_fields are required; without them the file is not processed.
| Field | Required / default | Description |
|---|---|---|
| amount_field | Required | Field holding the transaction amount. |
| transaction_identifier_field | One of these is required | Single field used to match the line to the original payment (its txid). |
| transaction_identifier_fields | Alternative to the above | Multi-field match. Holds conditions (a query) and take_first (default true) to pick one when several match. |
| transaction_status | Required for mixed/default | Defines success and (optional) rejection condition sets. success is required; if rejection is omitted, any non-success line is treated as rejected. |
| response_code_field | Optional | Field carrying the gateway response/result code. Saved onto rejections (rejection_code, vendor_response.code). |
| four_digits_field | Optional | Field with the card’s last four digits (a trailing 4-character substring is taken). Saved to payment_method.last_four_digits. |
| card_expiration_field | Optional | Field with the card expiration. Saved to payment_method.expiration_date. |
| voucher_number_field | Optional | Field with a voucher/payment identifier. Saved to vendor_response.payment_identifier. |
| date_field | Optional | Field providing the transaction time (used as the payment URT). Current time is used if absent. |
| orphan_files_time | Optional | How long a file may wait unmatched before being treated as orphaned. |
| limit | Optional | Processing limit. |
| identifier_field | Optional | When its field is invoice_id and link_to_invoice is set, links the payment to an invoice. |
¶ Data-structure field objects (per column)
Each entry names one column of the incoming line and optionally transforms its value. Transforms are applied only when present.
| Field key | Description |
|---|---|
| name | Column name; the key under which the value is stored and matched. |
| checked | UI flag indicating the column is in use. |
| save_to_bill | If true, this column’s value is written back onto the matched bill/payment (under pg_response). |
| value_mult | Multiplies the numeric value (e.g. 0.01 converts minor units such as cents/agorot to the main currency unit). |
| decimals | Divides the integer value by 10^decimals to place the decimal point. |
| type = date | Parses the column as a date; pair with format. If format is missing, the BillRun default format is used and a warning is logged. |
| substring | Takes part of the value; requires offset and length. |
| replace_regex | Regex replacement; requires regex and replace_with. |
¶ file_status values
| file_status value | Effect |
|---|---|
| (empty) or mixed | Each line is classified individually using transaction_status conditions — some succeed, some are rejected. |
| only_acceptance | The whole file is treated as confirmations; matched payments are approved. Requires correlation and response_files_count. |
| only_rejections | The whole file is treated as rejections; matched payments are rejected. Requires correlation and response_files_count. |