Change log:

Reference log:

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: [Integration:Buckaroo BPE3 Request Generator Engine]

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.

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:

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:

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:

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

Log file

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