Buckaroo BPE3.0 Payment Response Reader Engine

Document Logs

Change log:

Date:	Author:	Version:	Changes:	Completed
07 November 2013	Karuna Thulluri	1.0	Doc. created	Yes
	Karuna Thulluri	1.1	Added information about Parameter tree entries	Yes
04 November 2015	Esau Castillo	1.2	Added information about the new sequence check	Yes

Terms and Definitions:

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

Overview

This document describes the integration of the Rator Customer Care and Billing System (Rator) and the Buckaroo BPE 3.0 payment systems. Two engines are used for integrating Rator and the Buckaroo Payment interface version 3.0, i.e. the Buckaroo Request Generator Engine and the 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 reader engine functionality in detail.

The Buckaroo BPE3.0 Payment Response Reader engine handles the processing of payments received by the Rator system in a file (csv-format) from Buckaroo. When the payment response files are sent from Buckaroo, a file processor loader instance picks up these files from the configured folder and loads them into appropriate DB tables (BUCKAROO_RESPONSE_HEADER_BPE3 and BUCKAROO_RESPONSE_RECORD_BPE3). The Payment Response Reader engine then reads the data from these tables and processes it.

Important Note:

The File Processor engine must load the Buckaroo payment response files before they are actually processed by the Buckaroo BPE3.0 Payment Response Reader engine, i.e. handling payment response files is a two-step process:

First run the File Processor Loader engine instance to load the payment response files to the respective DB tables.
Then run the Buckaroo BPE3.0 Payment Response Reader engine.
This engine reads the payment transaction data from the DB tables and processes them.

Production Date

XX November 2013.

Customer Configuration

The Buckaroo Payment Response Reader engine is configurable by editing the engine configuration file.

<base_path>/engines/BuckarooResponseReaderBPE3/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.BuckarooBPE3ResponseReaderEngine
	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: BuckarooBPE3ResponseReaderEngine
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.
wrapper.app.parameter.8 (customer-assigned number)	Additional command line arguments for the above-named Java class.
	Parameter to engine. Specifies the type of the payment responses that the engine should process. This is an optional parameter. Accepts the following values: WEB: The response reader engine will process only the Web based PUSH responses FILE: The response reader engine will process only the File based responses If this argument is not present or has any value other than WEB or FILE: The response reader engine will process the Web based PUSH responses first , followed by the File based responses.

Parameters Required

The following parameter entries are used to specify the capture engine configuration:

PATH/Type	Description	Mandatory	Default value used if the parameter is not present
ENGINE.BUCKAROO_RESPONSE_READER_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 for 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 the following parameter BRAND.ENABLED exists and its value is not 'N'), even if only a single brand exists. 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.PAYMENT_RESPONSE_FILENAME_DATE_FORMAT
String	Date format used in the BPE3 Response file name. This is used to get the Date from the response file name to check the sequence order of the files while processing them. If the file currently being processed is not the next file in sequence, the engine will not process that file and sets it to error status.	NO	yyyy-MM-dd
INTEGRATION.BUCKAROO.BPE3.PAYMENT_RESPONSE_FILENAME_PREFIX
String	File name prefix used for BPE3 response file name. Used to get the last processed response file from the BUCKAROO_RESPONSE_HEADER_BPE3 table by looking for the entries with a file name that starts with this prefix.	NO	<empty string>
INTEGRATION.BUCKAROO.BPE3.PAYMENT_REVERSAL_FILENAME_PREFIX
String	File name prefix used for BPE3 reversal file name (if normal payments and reversals are sent in two separate files by Buckaroo). Used to get the last processed reversal file from the BUCKAROO_RESPONSE_HEADER_BPE3 table by looking for the entries with a file name that starts with this prefix.	NO	<empty string>
INTEGRATION.BUCKAROO.BPE3.PAYMENT_REVERSAL_FILE_GAP_IN_DAYS
Number	Number of days between two consecutive reversal files. Used only if PAYMENT_REVERSAL_FILENAME_PREFIX is defined. The purpose of this parameter is to allow defining different time gaps between the response and reversal files if Buckaroo sends two separate files: Response file containing successful payments and a Reversal file containing reversal transactions.	NO	1
INTEGRATION.BUCKAROO.BPE3.PAYMENT_RESPONSE_FILE_GAP_IN_DAYS
Number	Number of days between two consecutive response files. Used only if PAYMENT_RESPONSE_FILENAME_PREFIX is defined. The purpose of this parameter is to allow defining different time gaps between the response and reversal files if Buckaroo sends two separate files: Response file containing successful payments and a Reversal file containing reversal transactions.	NO	1
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_REVERSAL_NOT_POSSIBLE
String	Status message set by reader engine on the response record, if reversal is not possible	NO	Reverse payment could not be done, newer Buckaroo records exist for invoice number:<InvoiceNumber of corresponding invoice>
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_REVERSAL_ALREADY_DONE
String	Status message set by reader engine on the response record, if the reversal is already done	NO	Account has already been fully reversed for Invoice number:<InvoiceNumber of corresponding invoice>
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_AMOUNT_MISMATCH
String	Status message set by reader engine on the response record, if request and response amounts do not match	NO	Debit amount from the response does not match the amount from accompanying payment request.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_PAY_AFTER_REVERSAL
String	Status message set by reader engine on the response record if successful payment response is received after the payment reversal response	NO	Payment date is older compared to the last successfully processed reversal record.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_CAPTURE_ALREADY_DONE
String	Status message set by reader engine on the response record if the payment capture was already done	NO	Account payment has already been captured.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_CODE_190
String	Status message set by reader engine on the response record with status 190 when they are successfully processed.	NO	Success: The payment is processed successfully.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_CODE_490
String	Status message set by reader engine on the response record in status 490	NO	Failed: The transaction failed.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_CODE_491
String	Status message set by reader engine on the response record with status 491	NO	Validation failed: The transaction request contained errors and could not be processed properly.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_CODE_492
String	Status message set by reader engine on the response record with status 492	NO	Technical error: Due to a technical fault the transaction could not be completed.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_CODE_690
String	Status message set by reader engine on the response record with status 690	NO	Rejected: The transaction is rejected by the (third party) payment provider.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_CODE_790
String	Status message set by reader engine on the response record with status 790	NO	Pending entry: The transaction is on hold while the payment enginge is waiting for input from consumers.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_CODE_791
String	Status message set by reader engine on the response record with status 791	NO	Pending processing: The transaction will be processed.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_CODE_792
String	Status message set by reader engine on the response record with status 792	NO	Awaiting the consumer: the payment Engine waits for consumers to return from a third party website, which is needed to complete the transaction.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_CODE_793
String	Status message set by reader engine on the response record with status 793	NO	The transaction is on hold.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_CODE_890
String	Status message set by reader engine on the response record with status 890	NO	Cancelled by User: The operation was cancelled by the customer.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_CODE_891
String	Status message set by reader engine on the response record with status 891	NO	Cancelled by Merchant: The merchant has cancelled the transaction.

Logic

The Buckaroo BPE3.0 Payment Processor engine reads records from the BUCKAROO_RESPONSE_HEADER_BPE3 that satisfy the following criteria:

Ready to be processed, i.e in STATUS = 0.

and

belong to the given brand, if the engine is set up to use a specific brand.

If more than one header record is ready to be processed, the engine processes one after the other in ascending order of the date in the file name. Each header record represents one response file to be processed. For each header record, the engine performs the following actions:

The engine first makes a sequence check. There are two types of sequence checks depending on whether the file name has a sequence number or not:
- Without a sequence number:
  The check verifies that the date difference between the last processed record (i.e. file) and the current header record is exactly one day.
- With a sequence number:
  The check process considers a set of conditions to validate the sequence:
  1.- In case of processing files for the same day (that is the difference between the last processed file and the current is 0) the sequence must be the correct one: 01, 02, 03
  2.- In case of processing the first file for the day (the last file processed was one day before). It is checked that the sequence is 01 and that all the files from the previous day were successfully processed, i.e. that there is no file in status initial (0) with the date_loaded = date of yesterday.
  Please note that in case a file from the previous day was loaded late and a file from the current day was processed successfully, the old file will remain unprocessed.

If the sequence check fails, the engine stops processing the files and exits with an error message printed in the logs. The file sequence must be verified manually before restarting the engine.

If the sequence check was successful, the engine will query for all the BUCKAROO_RESPONSE_RECORD_BPE3 entries corresponding to this header whose STATUS = 0.
If no payments exist for this header, the engine will process the next header record in the list.
If payments are found for this header, the engine will process them one by one.

For each payment response record picked up the engine will perform the following actions:

First it checks that a Buckaroo BPE3 request exists that matches this response record. This linking is done with invoice_number. If no matching request is found, the response record is set to ERROR status i.e STATUS_ID = 4.
If a matching request is found, then the engine processes the response record based on the Payment Status code and payment type code values. A payment response record cannot be processed, if the value of the field 'Success' is not equal to 'True'. If this field contains any value other than 'True', the corresponding response record is set to error status i.e. STATUS_ID = 4.
If the 'Success' is 'True, then the engine invokes a workflow hookpoint for each payment response record based on the value of the PaymentType code. This workflow processes the payment, i.e. creates Account_Payment, Invoice_Payment etc. Different hookpoints are configured for processing different payment types.
Depending on the outcome of the payment handling workflow, the engine sets the STATUS_ID on the BUCKAROO_RESPONSE_RECORD_BPE3 entries to one of the following values:
- STATUS_NEW : 0
- STATUS_PROCESSED : 1
- STATUS_IGNORE: 2
- STATUS_ERROR : 4

The table below describes the action taken by the Buckaroo BPE3.0 Payment Response reader engine for each type of the payment:

Payment Status Code(s)	Payment Type code(s)	Action taken	More info	Status_Id on the corresponding BUCKAROO_RESPONSE_RECORD_BPE3 entry after processing
190	All payment type codes except C462	The workflow will process the payment as below: Step 1: Tries to find the matching Account_Payment record in DO_CAPTURE status that has the same invoice_number as this payment response record. Step 2: Tries to find the Invoice that has same invoice_number as this payment response record. If both Invoice and Account_payment are not found, the processing fails and the payment response record will be set to error status. Step 2: If an Account Payment cannot be found in Step 1, a new account payment record will be created and saved to the database. The invoice_number and billing_group_id on this Account payment entry will be taken from the payment response record Step 4: The Account payment will be captured Step 5: If this payment is for a Postpaid billing group, an invoice payment entry is added to INVOICE_PAYMENTS table. For prepaid billing group payments, Invoice payment is not added. The invoice for adding this invoice payment is obtained like this: Use the invoice that has same invoice_number as this payment response record, if any. Otherwise, get the Invoice from the AccountPaymentInvoiceRelation if there any such relation existing for this account payment. Otherwise, get the current open invoice and register this payment. If the processing was successful, the engine sets the corresponding BUCKAROO_RESPONSE_RECORD_BPE3 entry to Processed Status (). If the payment cannot be processed due to some problem (e.g. Invoice cannot be located, an exception occurred while processing), then the corresponding BUCKAROO_RESPONSE_RECORD_BPE3 entry is set to Error Status.		STATUS_ID = 1 if the payment is successfully processed or STATUS_ID = 4 If an error happened while processing the payment
190	C462	Not processed, set to IGNORE status	This payment refers to the Collection Agency fees. So this need not be processed by Rator.	STATUS_ID = 2
790, 791, 792, 793		Not processed, set to IGNORE status	The status codes 790, 791, 792, 793 indicate that the payment transaction is either on hold or still under processing. So these records do not refer to a final transaction status. Hence they need not be processed.	STATUS_ID = 2
490, 491, 492, 690, 890, 891		Set to ERROR status since these refer to a failed/rejected/cancelled payment transaction	490, 491 and 492 status codes indicate that the transaction failed (for ex: validation failed, technical problems etc..). 690: Indicates that the transaction is rejected by a third party payment provider 890, 891: Indicate that the transaction was cancelled by the User or the merchant, respectively.	STATUS_ID = 4

If all the BUCKAROO_RESPONSE_RECORD_BPE3 records are processed successfully, then the corresponding BUCKAROO_RESPONSE_HEADER_BPE3 record is set to PROCESSED status, i.e. STATUS = 1. If some of the response records are successfully processed and some had processing errors/ problems, then the the corresponding BUCKAROO_RESPONSE_HEADER_BPE3 record is set to PROCESSED_WITH_ERRORS status . i.e. STATUS = 2.

Database Tables

The following DB tables are used by the Buckaroo BPE3 Request Generator for saving the payment request information.

Name:	BUCKAROO_RESPONSE_HEADER_BPE3
Description:	Header table to hold the information about Buckaroo payment response files such as File name, date of loading the file, number of payment records in the file etc. Each record in this table represents a payment response file. Each header entry can have one or more corresponding payment records in BUCKAROO_RESPONSE_RECORD_BPE3 table.

Name:	BUCKAROO_RESPONSE_RECORD_BPE3
Description:	Each record represents a a payment transaction from the response file. Each record in this table contains actual payment information like debit amount, credit amount, user name, bank account number, payment status code, payment type code etc. This information is used by the response reader engine to process the payment and update the user balance.

Logging

The following table describes the requirements for logging and how the current implementation achieves it:

Requirement	Implementation
For each response file that is processed, the Rator system has to write a log-record to a table.	The DB table BUCKAROO_RESPONSE_HEADER_BPE3 contains one row for each response file processed. This table has a column called STATUS which contains the current status of the response file. Possible status values are NEW(0), PROCESSED(1), PROCESSED_WITH_ERROR(2), ERROR(4)
For each processed record, a row must be written to the log-file which indicates whether the record is successfully processed.	The table BUCKAROO_RESPONSE_RECORD_BPE3 contains one row for each record in the response file. This table has a column called STATUS which contains the current status of the response record. Possible status values are NEW(0), PROCESSED(1), IGNORE(2), ERROR(4)
In case of an error, a clear description should be written to the log-file and the Rator system should start processing the next (response) record.	The table BUCKAROO_RESPONSE_RECORD_BPE3 contains one row for each record in the response file. This table has a column called STATUS_MESSAGE which contains a message indicating whether or not an error occurred while processing the corresponding response record. These status messages are configurable by defining parameter tree entries for each status message used. Please see *Parameters required* section for more info.