PBS Direct Debit

Change log:

Overview

The Rator system offers a fully integrated solution towards PBS (now Nets) which is the primary payment handling company in Denmark. Integration 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

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 the 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

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:

Detail lines per 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 mail template with the KEY=PBS_XML_HEADER_DESC_TPL
• A simple text (MAX 60 chars) in the template body like:

  Invoice number ***LABEL@INVOICE.InvoiceNumber*** attached

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

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

Steps

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

Engines

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:

1. Retrieves a list of invoices which are ready for processing.
2. Creates a new record in the PBS_DELIVERY table.
3. Generates an XML file and performs some validation of syntax and content.
4. Looks up/generates PDF files (if found in DOC_ARCHIVE, this is used - otherwise a new one is created and saved there).
5. Creates a zip file containing the PDF files.
6. Cleans up temporary xml/pdf files created during the process.
7. Moves the created files to the outgoing directory.

This engine/class extends EngineCore and requires 3 arguments:

1. EngineName
2. Engine instance number
3. Maximum number of invoices per file.

Configuration

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

Working directories
<EngineDir>/invoices/outgoing

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

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):

Steps

1. Establishes the FTP connection.
2. Downloads all files from the relevant download directory on the remote SFTP server.
3. Places files in the local incoming directory.
4. 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).
5. 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

wrapper.app.parameter.4=com.CDRator.ftp.PbsFileTransferEngine
wrapper.app.parameter.5=PbsFileTransferEngine
wrapper.app.parameter.6=1

PBS File Handler Engine

This engine processes 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. The engine assumes that the M602 file can contain two different types of payments, "automatic" and "indbetalingskort" (printed payment order).

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

1. Locates files in incoming directory.
2. 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 "TAB" are validation files and are processed for checking e.g. whether PBS processed the same number of invoices as generated by Rator.
3. After successful processing, the files are moved to the processed-directory.
4. 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 files delivered 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

wrapper.app.parameter.4=com.CDRator.billing.pbs.PBSFileHandlerEngine
wrapper.app.parameter.5=PBSFileHandlerEngine
wrapper.app.parameter.6=1

Working dirs
<EngineDir>/incoming_pbs_files
<EngineDir>/processed_pbs_files
<EngineDir>/error_pbs_files

PBS Invoice Settle Engine

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

The engine just makes the initial invoice payment for the full amount.
 
If the received amount is higher 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 the payment reference is not provided, then open running invoice will be applied for post-paid payments and captured manual account payment will be created for pre-paid payments. This feature is optional and could be switched on by adding the parameter 'PBS.DIRECT_DEBIT.FIND_INVOICE_FOR_UNDEFINED_PAYMENT_REFERENCE':

Steps

1. Looks up all records in OCR_LINE with status new or error.
2. Loops the list of found records and tries to process these as described above.

Configuration

wrapper.app.parameter.4=com.CDRator.billing.pbs.PBSInvoiceSettleEngine
wrapper.app.parameter.5=PBSInvoiceSettleEngine
wrapper.app.parameter.6=1

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.

1. Once all the files have been created, open WINSCP and connect to PBS. When prompted for a pass phrase enter the provided password.
   Note: It is VERY important when connecting to the PBS FTP server that the "resume" setting is set to "disabled".
   This is set under the "Endurance" settings for WINSCP which is found in Preferences.
2. Transfer all zip files created to the directory that has opened.
   *DO NOT under any cirumstances try to open any files on the PBS side - if you do, you will automatically delete them.
   Once you have transferred the files you will not be able to see them on the PBS side - this is normal.*
3. Once all files have been transferred, you may need to send a mail to PBS with the names of the transferred files.
   Move the safe copy of the files to a new directory under a main delivered folder - name it DELIVERED_<current date>
4. You're done