Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

This document describes the interfacing between the Rator Customer Care and Billing System (Rator) and the Buckaroo BPE 3.0 payment systems. There Two engines are two engines 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 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. 

...

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

...

Info
iconfalse
titleInformation 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 is also dependent 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:

  1. 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). 
  2. 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. 

Document Usage

This document is primarily intended for the Rator implementation team and for understanding the interface with Buckaroo. It will also be used as a basis for acceptance tests.

Note: Please note that we have a separate integration with Buckaroo BPE 2.0 payment interface. This is also file based. For more information on Request Generator engine for integration with Buckaroo BPE 2.0 interface, please look here.


Production Date

XX November 2013.

...

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.ENABLEDString

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 for. Otherwise the engine is disabled for that brand.

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_B2CStringFixed 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_B2BStringFixed 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_PREFIXStringPrefix with which pre-notification file name
will start with, if a separate pre-notification file need 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 need 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_DATEDateThe default mandate date to be used if the Bank account valid_from date is null or valid_from date is before 2013-12-11.YES2013-12-11
INTEGRATION.BUCKAROO.BPE3.SEPA_COLLECT_DATENumberThe collect date offset : number of days from the invoice close date that is used as the Collect date for this invoice.YES7
INTEGRATION.BUCKAROO.BPE3.USE_PAY_PER_EMAILStringIndicates 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.YEStrue
INTEGRATION.BUCKAROO.BPE3.START_RECURRENTString

Value to be put into the 'startrecurrent' field of the Direct Debit request file.

Possible values are: TRUE , FALSE

NOTRUE
INTEGRATION.BUCKAROO.BPE3.USE_ADDITIONAL_SRV_CREDIT_MGMTStringUsed to indicate whether the Creditmanagement service is used. If set to true/yes, creadit managament related fields will be populated with proper data while request generator engine is inserting the buckaroo request data into Buckaroo_Request_Record_Bpe3 table.NOtrue
INTEGRATION.BUCKAROO.BPE3.USE_ADDITIONAL_SRV_NOTIFICATIONStringUsed 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.NOfalse
INTEGRATION.BUCKAROO.BPE3.CREATE_SEPARATE_NOTIFICATION_FILEStringUsed 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.NOfalse
INTEGRATION.BUCKAROO.BPE3.USE_FIXED_SEPA_DD_COLLECT_DATEStringUsed 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.NOfalse
INTEGRATION.BUCKAROO.BPE3.SEPA_FIXED_COLLECT_DATE_DAY_OF_MONTHString

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.

NO26
INTEGRATION.BUCKAROO.BPE3.NOTIFICATION_SEND_DATE_OFFSETNumber

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.

NO14
INTEGRATION.BUCKAROO.BPE3.SET_EMPTY_PRENOTIFCTN_SEND_DATEString

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.

NOfalse
INTEGRATION.BUCKAROO.BPE3.NOTIFICATION_TYPEString

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

NOPreNotification
INTEGRATION.BUCKAROO.BPE3.PRE_NOTIFICATION_COMMUNICATION_METHODString

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


NOEmail

...