...
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 |
|
...
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:
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) |
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
- Run PBS Package Engine to produce output 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.
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:
- 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
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):
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
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
- 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 "TAB" 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
...
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':
TYPE | NAME | VALUE | DESCRIPTION |
|---|---|---|---|
String | PBS.DIRECT_DEBIT.FIND_INVOICE_FOR_UNDEFINED_PAYMENT_REFERENCE | <Y/N> | (Optional) - will appear as NO if this is not found |
Steps
- Looks up all records in OCR_LINE with status new or error.
- 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.
- 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. - 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.* - 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> - You're done
