{float:right|width=300px|background=lightgrey|border=solid blue 2px|margin=10px|padding=8px}*Contents*
{toc:all=true|depth=4|excerpt=true|indent=14px}
{float}

Change 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 Two engines are two engines involved: involved, i.e. Buckaroo Request Generator Engine and Buckaroo Payment Capture Response Engine. The Request Generator is responsible for generating generates the payment request csv file that will be sent to Buckaroo. The Capture engine is responsible for processing processes the payment response files received from Buckaroo. 

You can find more detailed information about Buckaroo Request Generator engine here: Please see 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. Buckaroo Response Engine  for more detailed information.

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

...

• 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
• Payment due date
• 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
• Bank account number
• 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 payment type code
  These fields explian explain the reason for receiving this message. It is primarily used to know what for determining the type of payment it is for ex: , e.g. direct debit / reversal / refund / settlement by merchant etc.
• Invoicenumber
  This number should be used to link the response to the original payment request message. Also the brand is detected based on this number when it is received from the Push response.
• 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 File Format

This section describes the Buckaroo file format (both request and response file formats) 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 BPE3.0 payment requests.Record lay-outthe record format of the csv-files sent from Rator to Buckaroo with BPE3.0 payment requests. 

Note: This is just an example record layout. It is possible to configure the record layout in the request file (i.e. which fields should be present in the request record and at which position) by using the File Processor Generator configuration. 

Record layout:
websitekey;amount;culture;currency;description;service;invoicenumber;service_directdebitrecurring_action;service_directdebitrecurring_customeraccountnumber;service_directdebitrecurring_customeraccountname;

...

Field separators : semi-colon (“;” ) or ascii-char(28) FieldSeperatorFieldSeparator

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

...

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 describes the record layout of the payment response file sent by Buckaroo to usCDRator.

Record lay-out:

"Created";"Website";"Payment type";"Account number";"Customer";"Invoice number";"Description";"Amount Debit";"Amount credit";"Currency";"Status";

...

...

Business

...

Rules Payment Response Codes

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

The payments found in the buckaroo Buckaroo response file can be divided into four different categories: payments, refunds, creditnotes and write-offs. The reponses within each category should be processed and booked against certain GL codes in Rator for financial reporting.

Note: When processing the payment response codes from the Buckaroo file are processed, the field “succesvol” must be “True”. If not, process the next record.

Payments 

The payments category consists of:

1. (direct debit) payments,
2. payments done to the collection agency
3. settlements by merchant (external payments done by the customer to Simyo’s the service provider's bank account instead of Buckaroo’s)
4. reversals.

Refunds & Credit

...

Notes

This category consists of:

...

 A credit note is a special kind of transaction within the credit management process. The amount of the credit note will be subtracted from the open (principal) invoice amount, leaving no or a partial amount to be paid by the customer. When Simyo the Service provider refunds (a partial) amount to the customer, the invoice amount will be open again. Therefore, a credit note is usually used to close the invoice amount after a refund. A single refund transaction occurs seldom.

...

Write

...

-Off

Invoices that are not paid for by customers are sent to the collection agency. After a certain period of time, the unpaid invoices are closed by the collection agency and should be closed on the rator Rator platform as a write-off. 

Logging

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

...