Document Logs Change log:

Date:	Author:	Version:	Changes:	Completed	Available in version (tag)
		1.0	Doc. created	Yes
10 May 2014	Karuna Thulluri	1.1	Added Pay per email parameter entry	Yes
15 May 2014	Karuna Thulluri	1.2	Added new parameter tree entries to support the configuration of additional service Notification	Yes
27 May 2014	Karuna Thulluri	1.3	Fix to avoid creating empty files if all of the payments in a invoice batch are rejected	Yes	1.4.2

Terms and Definitions:

Terms/definitions:	Meaning:
TBD	To be defined
N/A	Not applicable

Overview

This document describes the interfacing between the Rator Customer Care and Billing System (Rator) and the Buckaroo BPE 3.0 payment systems. Two engines are involved in integrating Rator with Buckaroo Payment interface version 3.0: Buckaroo Request Generator Engine and Buckaroo Payment Response Reader Engine. The Request Generator handles generation of the payment request csv file that is sent to Buckaroo. The Response Reader engine processes the payment response files received from Buckaroo. This document describes the request generator functionality in detail.

The Request Generator Engine collects all the Buckaroo Direct Debit Payments which are ready for capture in the system and inserts required payment information in Buckaroo payment request tables. The engine handles the Account Payment Request records one by one to create entries in these tables. These records are then processed by a File Processor engine instance which creates the payment request csv file to be sent to Buckaroo.

CDRator integration to Buckaroo BPE3 payment interface supports the following Buckaroo Services:

SimpleSEPADirectDebit service : This is the primary service
CreditManagement service: Additional service. Possible to enable or disable by configuration with the help of parameter tree entry. Please see "Parameter Required" section below.
PayPerEmail service: Additional service. Possible to enable or disable by configuration with the help of parameter tree entry. Please see "Parameter Required" section below.
Notification service: Additional service. Possible to enable or disable by configuration with the help of parameter tree entry. Please see "Parameter Required" section below.

Information on File generation options

It is possible to generate one Direct Debit request file that contains all the Direct debit and/or Credit Management and/or Payperemail and/or Notification fields. But this also depends on which services are configured to be used and on the File processor configuration.

It is also possible to generate separate Direct Debit request file (with direct debit and/or CreditManagement and/or PayperEmail data) and Notification file (with only notification related data) by setting up two different file processor configurations.

Important Note: The Request Generator engine will only load the necessary payment data into DB tables. The file generation is not done by this engine. The File Processor engine creates the payment csv file using the data loaded into these tables, so the payment request file creation is a two-step process and must be done as described below:

First run the Buckaroo Request Generator engine. If all of the payments for a run are rejected and no payments need to be sent to Buckaroo, the corresponding BUCKAROO_REQUEST_HEADER_BPE3 and/or BUCKAROO_NOTIFICTN_HEADER_BPE3 record(s) will be set to STATUS = 3 (STATUS_EMPTY).
Then run the File Processor Generator engine instance. The file processor engine will create a file only if the request engine processed the data successfully, and the BUCKAROO_REQUEST_HEADER_BPE3 and/or BUCKAROO_NOTIFICTN_HEADER_BPE3 tables contain some records in STATUS = 1 (READY_TO_PROCESS) . Please note that it is possible to configure the layout of request file (i.e. which of the fields should be present and at which position in the request record) by using the File processor generator configuration.
For example: It is possible skip adding the PayperEmail fields to the request record in the file even, if they are present in the BUCKAROO_REQUEST_RECORD_BPE3 table.

Production Date

XX November 2013.

Customer Configuration

The Buckaroo request generator engine is configurable by editing the engine configuration file.

<base_path>/engines/BuckarooRequestGeneratorBPE3/conf/engine.conf

The files can be edited in a normal text editor, like Windows Notepad.

Engine Specific Properties

Some properties in the configuration file are specifically for engines, and are shown in the format below:

wrapper.java.mainclass	com.CDRator.billing.engine.GenericEngineStarter
	This property specifies the Java path for CDRator engine starter. Main class property must be specified in order to start the engine framework.

wrapper.app.parameter.1	-S
	The -S property is optional, but it is a parameter for the GenericEngineStarter which enables the engine starter to make a sleep just before it stops. The reason for this is that in cases where the engine has nothing to do, it can complete very quickly. The Windows NT Service environment might see this as a possible failure and will do a failure count. When the count reaches a specific number, it will halt completely and the service has to be restarted manually.

wrapper.app.parameter.2	300
	Number of seconds engine starter must sleep before it stops.

wrapper.app.parameter.3	-P
	Specifies that the next parameter is to start the engine.

wrapper.app.parameter.4	com.CDRator.billing.paymentInterface.engine.BuckarooBPE3RequestGenerator
	Specifies the Java path of the engine class that the generic engine starter must use to start the engine

wrapper.app.parameter.5 (customer-assigned number)	Additional command line arguments for the above-named Java class.
	Parameter to engine. Specifies the engine name and how it will appear in logs and process monitor. This configuration parameter will make it possible to set a different engine name per brand, if multibrand setup is used. Used in the call to the Process Monitor together with the Instance Number. Examples: BuckarooBPE3RequestGenerator
wrapper.app.parameter.6 (customer-assigned number)	Additional command line arguments for the above-named Java class.
	Parameter to engine. Specifies engine's instance number.
wrapper.app.parameter.7 (customer-assigned number)	Additional command line arguments for the above-named Java class.
	Parameter to engine. Specifies the max. number of payments that the engine can handle in each run.

Parameters Required

The following parameter entries are used to specify the request generator configuration. Please note that all of these parameters are brand-enabled. So it is possible to define brand specific values for the same parameter.

PATH	Type	description	Mandatory	Default value used if the parameter is not present
ENGINE.BUCKAROO_REQUEST_GENERATOR_BPE3.ENABLED	String	To enable/disable the engine for the given brand. If set to y/true: the engine will be enabled for the brand to which this parameter is configured. Otherwise the engine is disabled for that brand. Note: If this parameter is not set or changed to something other than 'Y' (case insensitive), then the engine will not run if the general project is set up to be brand enabled (i.e., if there exists the following parameter BRAND.ENABLED and its value is not 'N'), even if there only exists a single brand. If BRAND.ENABLED parameter does not exist or is set to 'N' (case sensitive), then the engine will run in non-branded mode as per standard behaviour of EngineBranded.	YES, if the engine should be enabled for a given brand.
INTEGRATION.BUCKAROO.BPE3.WEBSITE_KEY	String	Fixed string from Buckaroo portal. Used if WEBSITE_KEY_B2C /WEBSITE_KEY_B2B parameters are not defined. This is the case if same websitekey is used regardless of the type of the customer.	YES, if none of the two parameters: WEBSITE_KEY_B2C, WEBSITE_KEY_B2B are defined
INTEGRATION.BUCKAROO.BPE3.WEBSITE_KEY_B2C	String	Fixed websitekey from Buckaroo portal for private customers. If this parameter does not exist, then the website key configured in WEBSITE_KEY parameter is used.	NO	<Value configured in the parameter WEBSITE_KEY>
INTEGRATION.BUCKAROO.BPE3.WEBSITE_KEY_B2B	String	Fixed websitekey from Buckaroo portal for business customers. If this parameter does not exist, then the website key configured in WEBSITE_KEY parameter is used.	NO	<Value configured in the parameter WEBSITE_KEY>
INTEGRATION.BUCKAROO.BPE3.ACCOUNT_PAYMENT_TYPES	String	payment_type_id value of the account_payment entries used to choose what type of account payments are picked up by the request generator engine for creating the payment export file. Ex: 200	YES
INTEGRATION.BUCKAROO.BPE3.DESCRIPTION_PREFIX	String	Prefix for the description field	YES
INTEGRATION.BUCKAROO.BPE3.VAT_VALUE	String	VAT value : 21 for BPE3	YES
INTEGRATION.BUCKAROO.BPE3.CURRENCY	String	Currency Code: EUR	YES
INTEGRATION.BUCKAROO.BPE3.DUE_DATE_OFFSET	String	Payment due date offset	YES
INTEGRATION.BUCKAROO.BPE3.EXPORT_FILE_PREFIX	String	Prefix with which export file name will start with	YES
INTEGRATION.BUCKAROO.BPE3.EXPORT_FILE_EXTENSION	String	Extension used for export file. For ex: .CSV	YES
INTEGRATION.BUCKAROO.BPE3.PRE_NOTIFICATION_FILE_PREFIX	String	Prefix with which pre-notification file name will start with, if a separate pre-notification file needs to be generated	YES, if separate Pre-notification file need to be generated
INTEGRATION.BUCKAROO.BPE3.PRE_NOTIFICATION_FILE_EXTENSION		Extension used for pre-notification file, if a separate pre-notification file needs to be generated For ex: .CSV	YES, if separate Pre-notification file need to be generated
INTEGRATION.BUCKAROO.BPE3.CULTURE_CODE	String	ISO culture code: nl-NL	YES
INTEGRATION.BUCKAROO.BPE3.PAYMENT_METHODS_ALLOWED	String	Allowed payment methods	NO	machtiging
INTEGRATION.BUCKAROO.BPE3.PAYMENT_METHOD_INVALID_BANK_ACC	String	Allowed payment method if the bank account number is null or zero	NO	ideal
INTEGRATION.BUCKAROO.BPE3.DUMMY_BANK_ACC_NUMBER	String	Dummy bank account number used in case the customer bank account number is either null or zero or in anyway invalid.	NO	<Empty String>
INTEGRATION.BUCKAROO.BPE3.COUNTRY	String	Country code value	NO	NL
INTEGRATION.BUCKAROO.BPE3.SEPA_MANDATE_DATE	Date	The default mandate date to be used if the Bank account valid_from date is null or valid_from date is before 2013-12-11.	YES	2013-12-11
INTEGRATION.BUCKAROO.BPE3.SEPA_COLLECT_DATE	Number	The collect date offset : number of days from the invoice close date that is used as the Collect date for this invoice.	YES	7
INTEGRATION.BUCKAROO.BPE3.USE_PAY_PER_EMAIL	String	Indicates whether the PayPerEmail service is used: If value = 'true', then Payperemail service is enabled i.e. PayPerEmail fields will be filled with proper data when the bank account info is invalid.	YES	true
INTEGRATION.BUCKAROO.BPE3.START_RECURRENT	String	Value to be put into the 'startrecurrent' field of the Direct Debit request file. Possible values are: TRUE , FALSE	NO	TRUE
INTEGRATION.BUCKAROO.BPE3.USE_ADDITIONAL_SRV_CREDIT_MGMT	String	Used to indicate whether the Credit management service is used. If set to true/yes, credit management related fields will be populated with proper data while request generator engine is inserting the Buckaroo request data into Buckaroo_Request_Record_Bpe3 table.	NO	true
INTEGRATION.BUCKAROO.BPE3.USE_ADDITIONAL_SRV_NOTIFICATION	String	Used to indicate whether the Buckaroo Notification service is used. Thus it instructs the request generator engine whether or not to populate the Notification service related fields of Buckaroo_Request_Record_Bpe3 table.	NO	false
INTEGRATION.BUCKAROO.BPE3.CREATE_SEPARATE_NOTIFICATION_FILE	String	Used to indicate whether the Pre-Notification fields should be sent to Buckaroo in a separate file. If set to true/yes, then the request generator engine will insert an entry into BUCKAROO_NOTIFICTN_HEADER_BPE3 table so that the FileProcessor engine will create a separate file with notification data. Only header fields added to this new table. The notification data fields will still be in Buckaroo_Request_Record_Bpe3 table. The file processor configuration must be setup properly to generate the separate Pre-Notification file using the BUCKAROO_NOTIFICTN_HEADER_BPE3 record and notification data from corresponding records in Buckaroo_Request_Record_Bpe3 table.	NO	false
INTEGRATION.BUCKAROO.BPE3.USE_FIXED_SEPA_DD_COLLECT_DATE	String	Used to indicate whether a fixed day of the month should be used as the collect date. If set to true/yes, then value of SEPA_FIXED_COLLECT_DATE_DAY_OF_MONTH will be used as fixed collect date of that month.	NO	false
INTEGRATION.BUCKAROO.BPE3.SEPA_FIXED_COLLECT_DATE_DAY_OF_MONTH	String	The day of month to be used as the collect date for all the Direct debit requests in the Buckaroo request file. For ex: If the USE_FIXED_SEPA_DD_COLLECT_DATE is set to 'true' and this parameter has the value '20' and the file was generated for May 2014, then the collect_date for all the Direct debit request records in that file is: 2014-05-20 Please be aware that the value of SEPA_FIXED_COLLECT_DATE_DAY_OF_MONTH must be later than the day of file generation. Also if pre-notification is used, the collect date must be at least <NOTIFICATION_SEND_DATE_OFFSET> days after the file generation date to be able to send pre-notification emails to the customers.	NO	26
INTEGRATION.BUCKAROO.BPE3.NOTIFICATION_SEND_DATE_OFFSET	Number	Used only when Buckaroo Notification service is used. The number of days prior to the collect_date for calculating the pre-notification send-date at which the notification should be sent. If the collect date is 2014-05-20 and the value of NOTIFICATION_SEND_DATE_OFFSET is 14, then the pre-notification send date is 14 days prior to collect date, i.e notification send-date = 2014-05-06.	NO	14
INTEGRATION.BUCKAROO.BPE3.SET_EMPTY_PRENOTIFCTN_SEND_DATE	String	Used only when Buckaroo Notification service is used. Indicates whether the srv_notification_senddatetime field should be set to empty value. In that case Buckaroo will decide when to send pre-notification emails.	NO	false
INTEGRATION.BUCKAROO.BPE3.NOTIFICATION_TYPE	String	Used only when Buckaroo Notification service is used. The type of notification to send. Can be one of the following: PreNotification: A pre-notification that is sent some time before performing a scheduled action. PaymentComplete: A notification that is sent when a transaction has been completed with success. See Buckaroo Notification service description document for more information	NO	PreNotification
INTEGRATION.BUCKAROO.BPE3.PRE_NOTIFICATION_COMMUNICATION_METHOD	String	Used only when Buckaroo Notification service is used. The method used to send the notification. Can be one of the following: Email: The notification is sent by email. Please note: The communication method determines which fields are mandatory. See Buckaroo Notification service description document for more information	NO	Email

Database Tables

Following DB tables are used by the Buckaroo BPE3 Request Generator.

Name:	ACCOUNT_PAYMENT_REQUEST
Description:	Each record represents a direct debit payment request. The InvoiceHandlerEngine will create an account payment request record for each invoice that is successfully closed. The Buckaroo Request Generator engine will then read the payment requests in this table that are ready for capture and inserts the required payment data into buckaroo tables mentioned below. NOTE: For BPE2, the ACCOUNT_PAYMENT records are created during the invoice close process i.e. one ACCOUNT_PAYMENT for every closed invoice and the BPE2 request generator reads the data from the ACCOUNT_PAYMENT table. But for BPE3, a new payment solution is implemented to handle various types of payments (like partial payments, creditnotes, write offs etc..). As of this new solution, the invoice-close process will not create ACCOUNT_PAYMENT records. It will create ACCOUNT_PAYMENT_REQUEST records which are used by the Buckaroo BPE3 request generator. The ACCOUNT_PAYMENT records are created by the Buckaroo BPE3 Response reader (Capture) engine when the response file from Buckaroo is processed. For every successfully processed payment response, an ACCOUNT_PAYMENT and an INVOICE_PAYMENT record will be created. So with BPE3 solution, there will be one-to-one relation between InvoicePayments and AccountPayments.

Name:	BUCKAROO_REQUEST_HEADER_BPE3
Description:	Each record represents a header which holds reference to the record data needed to generate a payment request file. Each header entry can have one or more corresponding request records in BUCKAROO_REQUEST_RECORD_BPE3 table. So for each record with STATUS = 1 (i.e. in READY_TO_PROCESS status) in this table, a payment file will be generated and sent to the Buckaroo containing the information like name of the file, status, file generation date, number of records in the file etc.

Name:	BUCKAROO_REQUEST_RECORD_BPE3
Description:	Each record represents a a payment record in the payment request file. Each record in this table contains actual payment information like amount, VAT, user info like name, bank account info, address etc.

Name:	BUCKAROO_NOTIFICTN_HEADER_BPE3
Description:	Each record represents a header which holds reference to the record data needed to generate a seaparte pre-notification file. Each header entry can have one or more corresponding notification records in BUCKAROO_REQUEST_RECORD_BPE3 table. So for each recordw ith STATUS = 1 (i.e. in READY_TO_PROCESS status) in this table, a pre-notification file (containing the information like customer name, email, type of notification used, communication method used and the date of sending the notification) in the file etc.) will be generated and sent to the Buckaroo. Please note that this table will be used only if separate notification files need to be created.

Browser not supported