Page Comparison

{table-plus:width=700}












*Change log:*
|| *Date:* || *Author:* || *Version:* || *Changes:* || *Ext.* || *Int.* || *Is in Core* || Jira Ref. ||
| 18 May 2011 | RS | 0.1 | Doc. created | x | | N/A | \\ |
| 23 June 2011 \\ | SD \\ | 1.0 \\ | Checked \\ | x \\ | | | |
| 7 November 2012 | MZ | 1.1 | Checked | x | | N/A | |

----











h2. Overview

The Rator system offers a fully integrated solution towards PBS (now Nets) which is the primary payment handling company in Denmark. This is done through the PBS Direct Debit setup which consists of several engines that interface to and interact with PBS in various ways.

Interacting with PBS requires signing a subscription agreement on use of PBS Direct Debit.

PBS documentation: [http://www.pbs.dk/DA/PRODUKTER/DATAKOMMUNIKATION/TEKNIK/SFTP-LOESNING/Pages/hent-programmer-og-vejledninger.aspx]


PBS technical specification for xml files: [http://www.pbs.dk/da/produkter/medsend-bilag/Documents/MB_vejledning_XML000_DK.pdf]





PBS more technical specifications: [http://www.pbs.dk/da/produkter/betalingsservice/vejledning-og-regler/vejledninger/Pages/dataleverandoer.aspx]













h2. Getting Started

The following must be done prior to initiating any interaction with PBS:

* Make sure that one DEBTOR_GROUP record exists in the database with *ID=200905051308130059*.
* Make sure that records in the BILLING_CYCLE table point to the correct record in DEBTOR_GROUP table.
* Records must exist in the DEBTOR_GROUP_MEMBER (pointing to BILLING_GROUP.ID).
* Run subversion\dev\integration\PaymentGateways\PBSDirectDebit\database\table_changes.sql file for this project to get needed tables/columns.
* Set up the 4 engines.
* Install/configure an SCP client for file transfer between PBS and local directories.
* Make sure that these entries exist in the Parameter Setup and point correctly:
|| TYPE || NAME || VALUE || DESCRIPTION ||
| String | PBS.DIRECT_DEBIT.AGREEMENT_NUMBER | <000000000> | The PBS agreement number |
| String | PBS.DIRECT_DEBIT.DATA_SUPPLIER_CVR | <123456789> | The CVR number of the setup |
| String | PBS.DIRECT_DEBIT.DATA_SUPPLIER_SYS_CODE | <BS1> | A code used by PBS |
| String | PBS.DIRECT_DEBIT.INCOMING_DIR | <C:\Rator\engines\PBSFileHandlerEngine\incoming_pbs_files> | All files received from PBS should end up here |
| String | PBS.DIRECT_DEBIT.PAYMENT_TYPE | <00> | 07 for paper based payments, 00 for all payment types - default = 00 |
| String | PBS.DIRECT_DEBIT.TEST_MODE | <Y/N> | Parameter indicating whether we are testing or in production |
| String | ENGINE.INVOICE.XML.XML_INVOICE_CLASS | <com.CDRator.billing.invoice.xml.InvoiceXMLObject> | The Java class for handling XML for invoices |
| String | ENGINE.GLOBAL_ALERT_GROUP_NAME | <CDRator> | Reference to ALERT_RECEIPIENT_GROUP.NAME of the group to alert |
| String | INVOICE.DEBUG.SAVE_XML_FILE | <Y/N> | (Optional) - will appear as NO it this is not found |
| String | PBS.DIRECT_DEBIT.XML_ENCODING\\ | ISO8859-1\\ | (Optional) - Default in code is&nbsp;ISO-8859-1\\ |
| String | INVOICE.DEBUG.TMP_FILE_PATH | <C:\Rator\tmp> | Path for saving xml (the directory MUST exist) |
| String | SIGNUP.CONFIG.DEFAULT_DEBTOR_GROUP_ID | 200905051308130059 | ID for the default DebtorGroup (used when creating records in DEBTOR_GROUP_MEMBER |








h3. DebtorGroup info

The DebtorGroup is holding basic info about the setup.
Info about the values can be found in PBS technical specification for xml files.

Sample/info:
|| ID | 200905051308130059 ||
|| DEBTOR_GROUP_NUMBER | 00001 ||
|| CREDITOR_PBS_NUMBER | <THE PBS AGREEMENT NUMBER> ||
|| DATA_SUPPLIER_ID | <CVR NUMBER> ||
|| CREDITOR_BANK_REG_NUMBER | 1234 ||
|| CREDITOR_BANK_ACCOUNT_NUMBER | 12345678 ||
|| HEAD_LINE_TEXT | <CUSTOMER NAME> ||
|| SECTION_NUMBER | <0112/0117/0118> (see spec) ||
|| DEBTOR_GROUP_NAME | <SOMETHING MEANINGFULL> (only used internal) ||








h3. Detail lines pr invoice
The project is made to generate only one detail line.
The default text is: "Se vedlagte faktura", but this can be customized. This is done via the template framework and in the template you can use labels.
For customizing you need this:
* A mailtemplate with the KEY=PBS_XML_HEADER_DESC_TPL
* A simple text (MAX 60 chars) in the template body like: {noformat}Invoice number ***LABEL@INVOICE.InvoiceNumber*** attached{noformat}

You can use methods from INVOICE, ACCOUNT, BILLINGGROUP objects in the template.








h2. The Process

_Prerequisites_
For invoices to be handled, the following must apply:
* print_process_type_id=10
* be closed
* delivery_identifier = null
* ((total_excl_vat + total_vat) - payed_amount) > 0




















h3. Steps

# Run PBS Package Engine to produce putput files.
# Transfer the output file(s) to PBS via SCP tool.
# Run the PBS File Transfer Engine to exchange files with PBS and move incoming to the PBS File Handler Engine.
# Run the PBS File Handler Engine to process the received files from PBS (M602, 0603 and Validation files).
# Run the PBS Invoice Settle Engine to match payments with invoices in the Rator system.




















h3. Engines




















h4. PBS Package Engine

The purpose of this engine is to generate and pack files which can be delivered to PBS. This is done in the following steps:
# Retrieves a list of invoices which are ready for processing.
# Creates a new record in the PBS_DELIVERY table.
# Generates an XML file and performs some validation of syntax and content.
# Looks up/generates PDF files (if found in DOC_ARCHIVE, this is used - otherwise a new one is created and saved there).
# Creates a zip file containing the PDF files.
# Cleans up temporary xml/pdf files created during the process.
# Moves the created files to the outgoing directory.

This engine/class extends EngineCore and requires 3 arguments:
# EngineName
# Engine instance number
# Maximum number of invoices per file.

_Configuration_
{noformat}
wrapper.app.parameter.4=com.CDRator.billing.engine.PBSPackageEngine
wrapper.app.parameter.5=PBSPackageEngine
wrapper.app.parameter.6=1
wrapper.app.parameter.7=5000
{noformat}



















_Working directories_
<EngineDir>/invoices/outgoing

It is recommended to configure this engine to start on demand, as the process should be monitored.















h4. PBS File Transfer Engine

This engine connects to PBS via SFTP and downloads files found.

The engine requires a record in FTP_CONNECTION table (here only the main info listed):
|| KEY || VALUE ||
| FTP_KEY | PBS_DIRECTDEBIT |
| SERVER | 194.239.133.111 |
| PORT | 10022 |
| USERNAME | <defined by PBS> |
| PASSWORD | <defined by PBS> |
| REMOTE_UPLOAD_DIR | <defined by PBS> |
| REMOTE_DOWNLOAD_DIR | <defined by PBS> |
| USE_SECURE | Y |
| CODE | PUBLIC_KEY_SFTP |
| PRIVATE_KEY_FILE | <location of the certificate> |
| PRIVATE_KEY_PHRASE | <the password for the certificate> |

_Steps_
# Establishes the FTP connection.
# Downloads all files from the relevant download directory on the remote SFTP server.
# Places files in the local incoming directory.
# Uploads all files found in the local outgoing directory to the upload directory on the remote server (if an error occurs, the file will be moved to the the local error directory).
# Collects any downloaded files from the incoming directory and moves them to the "incoming_pbs_files" (PBS.DIRECT_DEBIT.INCOMING_DIR) directory of the PBS File Handler Engine so they can be loaded into the system from there.

_Configuration_
{noformat}
wrapper.app.parameter.4=com.CDRator.ftp.PbsFileTransferEngine
wrapper.app.parameter.5=PbsFileTransferEngine
wrapper.app.parameter.6=1
{noformat}




























h4. PBS File Handler Engine

This Engine will process the M602 and 0603 files received from PBS. "M602" is the name given to the file that contains (invoice) payments received from debtors (end users).

The "0603" files contain subscribe/unsubscribe information regarding payment agreements. This engine will assume that the M602 file can contain two different types of payments, "automatic" and "indbetalingskort".

Once the files are processed, their data is saved in OCR_LINE, OCR_HEADER (for M602 files), and PBS_0603_RESULT for 0603 files, respectively.

The most interesting values are probably the received_amount (which is mapped to total_amount on the ocr_line record) and payment_reference (which is the invoice_number).

The payment_reference should be the invoice_number of the corresponding (outstanding) invoice.

_Steps_
# Locates files in incoming directory.
# Handles all found files (in case of error \-> file are moved to error directory)
#* Info from M602 specific files/lines end up as records in DB table: OCR_LINE with status new.
#* Info from 0603 specific files/lines end up as records in DB table: PBS_0603_RESULT.
#* Info from files ending with "T.AB" are validation files and are processed for checking e.g. whether PBS processed the same number of invoices as generated by Rator.
# After successful processing, the files are moved to the processed-directory.
# Last step is to process the pending reocrds in PBS_0603_RESULT, by calling an updatePBSAgreements method.

In case of errors/problems, the engine will attempt to generate an alert email to configured recipients (ENGINE.GLOBAL_ALERT_GROUP_NAME)

The engine also process the BM5 files received from PBS. These files are status files regarding the delivered files to PBS.&nbsp;&nbsp;In case the status is Error an alert with the content of the file will be sent to to&nbsp;configured recipients (ENGINE.GLOBAL_ALERT_GROUP_NAME)&nbsp;and the file will be moved to the processed directory.

_Configuration_
{noformat}
wrapper.app.parameter.4=com.CDRator.billing.pbs.PBSFileHandlerEngine
wrapper.app.parameter.5=PBSFileHandlerEngine
wrapper.app.parameter.6=1
{noformat}



















_Working dirs_
<EngineDir>/incoming_pbs_files
<EngineDir>/processed_pbs_files
<EngineDir>/error_pbs_files




















h4. PBS Invoice Settle Engine

Once all OCR_LINE/PBS_0603_RESULT records have been saved by the PBS File Handler Engine, this engine will attempt to match the records with the corresponding invoices and try to settle them. The invoice will be defined by the invoice number which will be taken from the payment reference of OCR line. 

This engine will just make the initial invoice payment for the full amount.

 
If the received amount is more than the invoice amount (which it can be, especially if the payment came via an indbetalingskort), then we must handle this via the Payment Reallocation Engine.

If