| Wiki Markup |
|---|
{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 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. In case the status is Error an alert with the content of the file will be sent to to configured recipients (ENGINE.GLOBAL_ALERT_GROUP_NAME) 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.
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.
_Steps_
# Looks up all records in OCR_LINE with status new or error.
# Loops list of found records and tries to process these as described above.
_Configuration_
{noformat}
wrapper.app.parameter.4=com.CDRator.billing.pbs.PBSInvoiceSettleEngine
wrapper.app.parameter.5=PBSInvoiceSettleEngine
wrapper.app.parameter.6=1
{noformat}
h3. Transferring Files to PBS
The PBS File Transfer Engine can actually move the output files to PBS, but often you need to be in control of this process and monitor it. Then you can use a program called: WINSCP.
# Once all the files have been created, open WINSCP and connect to PBS. When prompted for a pass phrase enter the provided password.
*Note:* When connecting to PBS's FTP server it is VERY important that the "resume" setting is set to "disabled".
This is set under the "Endurance" settings for WINSCP which is found in _Preferences_.
# Transfer all zip files created to the directory that has opened.
{color:red}\*DO NOT under any cirumstance try to open any files on the PBS side - if you do, you will automatically delete them.{color}
{color:red}Once you have transferred the files you will not be able to see them on the PBS side - this is normal.\*{color}
# Once all files have been transferred, you may need to send a mail to PBS with a list of the file names you transfered.
Move the safe copy of the files to a new directory under a main *delivered* folder - name it DELIVERED_<current date>
# You're done :-)
{table-plus} |
Page Comparison
General
Content
Integrations