Change log:

Date:	Author:	Version:	Changes:
03 Oct 2013	KTH	0.1	Doc created.

Reference log:

Document:	Version:	Date:

Introduction

This document describes the interfacing between Rator Customer Care and Billing System (Rator) and the Buckaroo BPE 3.0 payment systems. This interface is file based and will be discussed in detail in this document.

Overview

This document describes the interfacing between the Rator Customer Care and Billing System (Rator) and the Buckaroo BPE 3.0 payment systems . There are two engines involved: Buckaroo Request Generator Engine and Buckaroo Payment Capture Engine. The Request Generator is responsible for generating the payment request csv file that will be sent to Buckaroo. The Capture engine is responsible for processing the payment response files received from Buckaroo.

You can find more detailed information about Buckaroo Request Generator engine here:

You can find more detailed information about Buckaroo Capture engine here:

Document usage

This document is primarily intended for the Rator implementation team and for confirming understanding of 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 detailed description of integration towards the Buckaroo BPE 2.0 interface, please look [here].

Scope

The scope of this document is the interface between the Buckaroo BPE 3.0 and Rator.

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

PATH	Type	description	Mandatory	Default value used if the parameter is not present
INTEGRATION.BUCKAROO.BPE3.WEBSITE_KEY	String	Fixed string from Buckaroo portal	YES
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.	YES
INTEGRATION.BUCKAROO.BPE3.DESCRIPTION_PREFIX	String	Prefix for the description field	YES
INTEGRATION.BUCKAROO.BPE3.VAT_VALUE	String	VAT value	YES
INTEGRATION.BUCKAROO.BPE3.CURRENCY	String	Currency Code	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.CULTURE_CODE	String	ISO culture code	NO	nl-NL
INTEGRATION.BUCKAROO.BPE3.PAYMENT_METHODS_ALLOWED	String	Allowed payment methods	NO	machtiging,ideal
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.COUNTRY	String	Country code value	NO	NL

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
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_REFUND	String	Status message set by capture engine on the response record for refund responses	NO	Refund. No action required.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_REVERSAL_NOT_POSSIBLE	String	Status message set by capture 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 capture 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 capture 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_SETTLED_PAYMENT	String	Status message set by capture engine on the response record for settled payment responses	NO	Payment settled by merchant / External payment. No action required.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_PAY_AFTER_REVERSAL	String	Status message set by capture 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 succesfully processed reversal record.
INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_CAPTURE_ALREADY_DONE	String	Status message set by capture engine on the response record if the payment capture was already done	NO	Account payment has already been captured.

Database Tables

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

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 (not in ERROR status) in this table, there will be a payment file generated and sent to the Buckaroo. Contains 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.

Unknown macro: {table-plus}

Interface

The interface with Buckaroo will be file based. Payment instructions can be sent (by file) to Buckaroo, Buckaroo will then collect the money with our customer, and update us on the payment status via response messages (also in a file).

File format

The format of the request and reaponse files is CSV. This format is described in more detail under the section Payment File Format.

File naming

The names of the files are described in Payment File Format.

Transport

The transport for the files is via SFTP. The SFTP server will be located with Buckaroo;

Frequency

Payment instruction files can be delivered to Buckaroo multiple times a day. Response files will be created by Buckaroo once a day.

Exact times TBD

Payment instruction file: daily at TBD
Response file: daily at TBD

Connection details

Connection details are still TBD

IP address/URL:
Directory:
Username:
Password:
Certificate:

Messages

In this section we will discuss the individual messages and field values to some more detail.

Note that if a field is not mentioned in this chapter this fact does imply that the field should not be used/populated

Payment instruction message

Every scenario that we will discuss in this document will start with a payment instruction. Normally only one payment instruction will be generated per customer per month (i.e. one payment instruction per customer). For the Rator implementation the following fields will be (especially) important:

Invoicenumber
The value of this field should link back to the the invoice in the Rator system. All payment responses can be linked back to the instruction via this number.
Invoicedate
Paymentdatedue
CustomerCode
Internal Rator customer ID (or Billing Group Id?)
Address fields
Address data stored in Rator for this customer.
Needed by Buckaroo for collection purposes
Mail address
Email address stored in Rator for this customer.
This email address will be used by Buckaroo for collection purposes
Phone Number and Mobile number
If a fixed phone is registered in the Rator database we will take this phone number.
This number will be used by Buckaroo for collection purposes.

Payment response message

Every payment instruction will result in one or more payment response messages. Fields that are especially important in this message type are the following:

Payment status code and transaction type
These fields explian the reason for receiving this message. It is primarily used as information. The important fields in this message are the debit/credit amounts
Invoicenumber
This number should be used to relate to the original payment instruction message.
Debit/Credit amount
Debit/credit is from the customer's perspective . For a regular payment the debit field should contain an value matching the amount in the corresponding payment instruction message.

Note that the payment response file will contain the complete set of activity on the accounts (so also not monthly-fee related). Responses that cannot be linked back (via the invoicenumber field) can be ignored by Rator (for the time being).

Payment scenarios

In this section we will discuss the scenarios that are of interest for our interaction with Buckaroo. This is important as the Buckaroo interface is more extensive than required and therefore this interface will contain more fields and field values than actually used. Especially important here is that we will not use credit card payments. Instead, payments will be done via direct debit and via the iDeal interface. In the most common scenario the payment will be done via automatic direct debit in combination with customer-authorization in advance.

Another important note to be made here is that one should not check the response message's field payment code in order to determine whether an payment instruction has been paid. Instead one should maintain a balance per payment instruction that summarizes the debit/credit amounts contained in the response files that relate to the initial payment instruction. (via the Invoicenumber field). We will anyway discuss the possible scenarios however in this section in order to enhance the understanding of the dialogue between the various parties (Buckaroo, Rator).

Regular payment

The most common case will be the case of regular payment depicted in the following diagram.

Figure : Regular payment

Late payment

If the customer has a negative balance (over the limit for this customer) on his bank account the customer's bank will not authorize the automatic direct debit. In that case Buckaroo will ask the customer to pay anyway (via various means, e.g. email) and then the customer might pay anyway (also via various means, e.g. iDeal.

Figure : Late payment

In some case it might happen that the customer might even pay in multiple increments (partial payments):

Figure : Late payment, partial payments

Note:

The above diagram only describes two payments, but in fact there could be more than two. Also note that the case of partial payments also applies for the other non-regular scenarios described in the next sections.
In case of involvement of the collection agency (paymentcode=461) we will not receive the full payment, but at most 90%.

Payment reversal

After an automatic direct debit transfer, the customer might instruct the bank to reverse the money for the initial payment. Buckaroo will then try to get the customer to pay anyway, but this might not always be successful. This scenario is described below:

Figure : Payment reversal, no payment

Notes:

The reversal instruction message can appear sooner that the direct debit message.
A reversal could happen up until 13 months after initial payment.
A reversal can only happen after an automatic direct debit payment. All other payments cannot be reversed.

Payment reversal resulting in payment

After a payment reversal (described in the previous section) the customer might pay after all. This scenario is described below.

Figure : Payment reversal resulting in payment

Note:

In case of involvement of the collection agency (paymentcode=461) we will not receive the full payment, but at most 90%

Refund

A special case in the in the interface between service provider and Buckaroo is the refund. In this case the service provider personnel refunds some money to the customer. Reasons might be that the service delivered to the customer was not satisfactory. The refund instruction is entered via the GUI of the Buckaroo system and does not originate from the Rator system, so from a Rator system perspective it is out of scope. Therefore if we receive a payment response with paymentcode=071 Rator should ignore this message (otherwise the balance will be debited while there is no associated payment instruction.

Figure : Refund

Payment File Format

This section describes the Buckaroo file format in detail.

Description of payment request csv file format

This section describes the record format for the csv files sent from Rator to Buckaroo with the payment requests.

Record lay-out:

websitekey;amount;culture;currency;description;service;invoicenumber;service_directdebitrecurring_action;service_directdebitrecurring_customeraccountnumber;service_directdebitrecurring_customeraccountname;additional_service;service_creditmanagement_action;phonenumber;customerlastname;service_creditmanagement_customeraccountnumber;customergender;amountvat;service_creditmanagement_maxreminderlevel;invoicedate;service_creditmanagement_customerbirthdate;service_creditmanagement_paymentmethodsallowed;datedue;customertype;faxnumber;customeremail;customerfirstname;mobilephonenumber;customerinitials;customertitle;customercode;customerlastnameprefix;address_street_1;address_housenumber_1;address_housenumbersuffix_1;address_zipcode_1;address_city_1;address_state_1;address_country_1

Field separators : semi-colon (";" ) or ascii-char(28) FieldSeperator

Record separators: "\n" (ascii-char(10) linefeed)
or "\n\c" " (ascii-char(10+13) linefeed+carriage-return)
or ascii-char(30) RecordSeperator

Allowed characters for fields: a-z, A-Z & 1-9, -+.@, <space> Limitation is in the format offered to the bank for the authorized payments.

Note: When the invoice is sent to Buckaroo the accompanying payment is inserted in the table account_payment with a payment_type_id (new payment_type_id) that identifies the "Buckaroo"-payment and this payment is set to "Do capture".

Content fields:

Fieldname	Rator table and field	Example	Format
websitekey	-	FSsfaJKF&6GH	Buckaroo Websitekey. Fixed string from Buckaroo portal
amount	invoice.TOTAL_EXCL_VAT + invoice.TOTAL_VAT – invoice.PAYED_AMOUNT	10.00	REAL, 2 decimals; amount
culture	-	nl-NL	String, ISO culture code
currency	-	EUR	Fixed string for currency code
description	<Description Prefix> + account_payment.REFERENCE	Test Incasso 1	String; description, max length 100 chars
service	-	Directdebitrecurring	String; Buckaroo service name
invoicenumber	invoice.INVOICE_NUMBER	Test01923r4e	String; Invoice number, max length 100 chars
service_directdebitrecurring_action	-	Pay	String; Pay or Refund (See Buckaroo service description)
service_directdebitrecurring_customeraccountnumber	Billing_group_bank_account.BANK_ACCOUNT_NUMBER	123456789	Bank Account; Must be 11 proof. Empty or null value not allowed
service_directdebitrecurring_customeraccountname	users.FIRST_NAME + <space> + users.LAST_NAME	T.Test	String; account name
additional_service	-	Creditmanagement	String; see Buckaroo Service description
service_creditmanagement_action	-	Invoice	Fixed String
phonenumber	users.PHONE1	0201111111	String; Phone number
customerlastname	users.LAST_NAME	Tester	String; customer last name, max 200 chars
service_creditmanagement_customeraccountnumber	Billing_group_bank_account.BANK_ACCOUNT_NUMBER	123456789	Bank account; must be 11-proof. Empty or null value not allowed. Will be same as service_directdebitrecurring_customeraccountnumber, but must be repeated
customergender	users.GENDER	1	Integer, may not be empty 0: Unknown 1: Male 2: Female 9: Irrelevant (currently not used)
amountvat	-	0.00	Real, 2 decimals Example: Value for amount = 1000. Value for invoicevat will be: 1000 * 0.19 = 190 Euro cents
service_creditmanagement_maxreminderlevel	-	1	INTEGER, may not be empty. Choose from (0,1,2,3,4). Default is 4
invoicedate	invoice.CLOSE_DATE	2012-01-10	YYYY-MM-DD; Invoice date
service_creditmanagement_customerbirthdate	users.BIRTHDAY	1970-01-13	YYYY-MM-DD; Birth date
service_creditmanagement_paymentmethodsallowed	-	machtiging,ideal	String; Comma seaparated list of allowed methods of payment as offered by Buckaroo. See Buckaroo Service description for possible values
datedue	invoice.CLOSE_DATE + <due date off set>	2012-01-27	YYYY-MM-DD; due date
customertype	-	1	String; type of customer Currently not used
faxnumber	users.FAX	0309999999	String; Fax number
customeremail	users.EMAIL	support@buckaroo.nl	String; customer email address
customerfirstname	users.FIRST_NAME	Test	String; Customer first name
mobilephonenumber	service.PHONE_NUMBER	0601111111	String; mobile number
customerinitials	-	T.	String; optional , currently not used
customertitle	users.TITLE	2	String; customer title
customercode	account.CUSTOMER_NUMBER	55225522	String; Customer rator account number
customerlastnameprefix	-	de	String; optional , currently not used
address_street_1	users.STREET	Hoofdstraat	String; street name
address_housenumber_1	users.STREET_NUMBER	1	Integer; House number
address_housenumbersuffix_1	users.FLOOR	b	String; House number suffix
address_zipcode_1	users.ZIP	1000 AA	String, Zipcode, always in DDDD<space>CC format
address_city_1	users.CITY	Amsterdam	String; City (in All capital letters)
address_state_1	users.PROVINCE	Noord-Holland	String; province
address_country_1	-	NL	String; country

Example filename: Incasso_25-05-2010_001.CSV Date format 25-05-2010 is DD-MM-YYYY and 001 is batch number for that day. In this respect multiple batches per day can be offered.

Description of payment response csv file

This section described the record layout of the payment response file sent by Buckaroo to us.

Record lay-out::

res_transactiondate;res_transactiontime;res_transactionkey;res_name;res_statuscode;res_status;res_transtype;res_service;res_invoicenumber;res_description;res_currency;res_amount_debit;res_amount_credit;res_amount_payout;res_reversal_reason

Field separators: semi-colon (";" )

Content fields:

Fieldname	Example	Format
res_transactiondate	2012-12-21	Date format: YYYY-MM-DD
res_transactiontime	17:11:35	Time; optional field in timeformat HH:MM:SS
*res_transactionkey*	ABCDEFABCDEF0123...	String; max 32 characters, Bucakroo transaction ID
res_name	T.Test	String; Customer name
res_statuscode	190	String; Status code of the transaction; see service description
res_status	Success	String; referes to res_statuscode
res_transtype	C002	String; transation type (See service description)
res_service	Directdebitrecurring	String; payment method
res_invoicenumber	Test01923r4a112	String; Invoice number
res_description	Test trx01	String; Description
res_currency	EUR	Fixed String "EUR"
res_amount_debit	10.00	REAL; 2 decimals, amount debited from customer account
res_amount_credit	0.00	REAL; 2 decimals, amount credited to customer account
res_amount_payout	10.00	REAL; 2 decimals
res_reversal_reason	ADMINISTRATIEVE REDEN	String; reason for payment reversal

Filename for daily transactions: trx_2010-05-25.csv Date format 2010-05-25 is YYYY-MM-DD

Additional information regarding status codes of transactions:

response field name	Description
res_statuscode	190 – OK, payment received, trx succeeded 490 – NOK, trx failed 491 – NOK, validation failed, syntax error, could not process trx 492 – NOK, technical issues, failed to complete trx 690 – NOK, trx not approved 790 – Pending, trx being processed, waiting for customer input 791 – Pending, trx being processed 792 – Pending, trx being processed, awaiting return of customer from 3^rd party site 793 – Pending, trx is on hold 890 – NOK, trx cancelled by customer 891 – NOK, trx cancelled by merchant
res_transtype	C001 – transfer C002 – first direct debit C003 – recurring direct debit C021 – ideal C121 – refund ideal C102 – refund any direct debit trx C562 – reversal I255 – creditnote V99 – external payment/settlement by merchant 461/462 – payments from collection agency
res_amount_debit	Debit amountIn Euro with 2 decimals
res_amount_credit	Credit amountIn Euro with 2 decimals
res_amount_payout	Sum of debit and credit amount (in Euro with 2 Decimals, can be negative)

Business rules payment response codes

The following table describes the business rules for handling the payment response codes from Buckaroo:

Note: When the invoice is sent to Buckaroo the accompanying payment is inserted in the table account_payment with a payment_type_id (new payment_type_id) that identifies the "Buckaroo"-payment and this payment is set to "Do capture".

Resp. code(s)	Transaction codes	Description	Action CDRator
190	C002/C003	Successful	Capture payment: Search for the corresponding payment using invoice number. If not found write error to log, process next record. Check if the debit amount from the response matches the accompanying payment. If it does not match write error to log, process next record. When payment is found, Capture the payment (if it is not captured yet). Write "successful result" to log file.
190	C562	Reversed	Capture original payment and insert reversed payment: Search for the corresponding payment using invoice number. Not found write error to log, process next record. Capture the original payment if it is not captured yet (reversal came before successful payment response). Insert a new payment with the same reference and a negative amount (negative credit amount of the response). This payment must have a payment_type_id that identifies a "Buckaroo" - reversed payment. Write "successful result" to log file.
190	C001/C021	Non regular payments. It might be a partial payment	Capture original payment or insert partial payment Search for the corresponding payment using invoice number. Not found write error to log, process next record. Capture the payment if the total amount of the original payment is the same as the debit-amount of the payment response and write successful result to log file. Otherwise insert a new payment with the same reference and with payment_type_id "Buckaroo" - partial payment. Write "partial payment" result to log file.
190	C121/C102	Refund	No action required This response code can be ignored by CDRator (only write a record to the log file). Note: action will be defined in future release
190	V99	Settled by merchant or external payment	No action required: This response code can be ignored by CDRator (only write a record to the log file) This code can be used when the customer paid the amount directly. An employee of the customer finance team will capture the payment.
??	I255	CreditNote	Missing in the Buckaroo Interface Description doc
190	461/462	Payments from Collection Agency	Missing in the Buckaroo Interface Description doc

Log file

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 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 if the record is successfully processed.	The table BUCKAROO_RESPONSE_RECORD 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), 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 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.

Buckaroo BPE3.0 Payment interface

Introduction

Overview

Document usage

Production Date

Customer Configuration

Engine Specific Properties

Parameters required

Database Tables

Interface

File format

File naming

Transport

Frequency

Connection details

Messages

Payment instruction message

Payment response message

Payment scenarios

Regular payment

Late payment

Payment reversal

Payment reversal resulting in payment

Refund

Payment File Format

Description of payment request csv file format

Description of payment response csv file

Business rules payment response codes