Change log:

Date:	Author:	Version:	Changes:
03 Oct 2013	KTH	0.1	Doc created.
10 Feb 2014	KTH	0.2	Added PayPerEmail field descriptions

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

Please see Buckaroo BPE3 Request Generator Engine and 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 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.

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
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 explain the reason for receiving this message. It is primarily used for determining the type of payment, 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.
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 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;

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) FieldSeparator

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 (TBD 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
service_payperemail_action	-	Paymentinvitation	String: Paymentinvitation (See Buckaroo PayPerEmail Service Description)
service_payperemail_customeremail	users.EMAIL	support@buckaroo.nl	String; customer email address
service_payperemail_customergender	users.GENDER	1	Integer, may not be empty 0: Unknown 1: Male 2: Female 9: Irrelevant (currently not used)
service_payperemail_customerfirstname	users.FIRST_NAME	Test	String; Customer first name
service_payperemail_customerlastname	users.LAST_NAME	Tester	String; Customer lastname
service_payperemail_paymentmethodsallowed	-	Ideal	String: Ideal, (See Buckaroo PayPerEmail Service Decription)
additional_service	-	Creditmanagement	String; see Buckaroo Service description If more than one additional service is used, this field will contain a comma separated list of names of all the additional services used. For example: Creditmanagement,Notification
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 separated 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 describes the record layout of the payment response file sent by Buckaroo to CDRator.

Record lay-out:

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

"Status date";"Success";"Reversal reason";"Country";"Transaction key";"IP Address"

Field separators: semi-colon (“;” )

Content fields:

Fieldname	Description	Format
Created	Transaction date, i.e. payment date	Date format: YYYY-MM-DD HH:MM:SS Ex: 2013-10-17 16:40:24
Website	Fixed string	String
Payment type	Payment type code and description indicating the type of the payment	4 Character payment type code followed by a payment type string . Ex: C021 - iDeal C561 - Melding Onterechte Incasso C102 - Refund - Machtiging
Account number	Customer bank account number	String; IBAN bank account number
Customer	Customer name	String; customer name
Invoice number	invoice number	Customer invoice number
Description	Description of the payment	String
Amount Debit	Amount debited from customer account	REAL; 2 decimals (amount in EURO)
Amount credit	Amount credited from customer account	REAL; 2 decimals (amount in EURO)
Currency	Currency code	Fixed String "EUR"
Status	Status of the payment transaction	BPE3 status code Ex: 190 490 791 etc.
Status date	Date of the last status update	Date format: YYYY-MM-DD HH:MM:SS Ex: 2013-10-17 16:40:24
Success	String representation of boolean indicating whether the payment is successful or not.	String; true/false
Reversal reason	Reason for the payment reversal	String Ex: ADMINISTRATIEVE REDEN
Country	Country	String
Transaction key	Payment transaction Key	String
IP Address	IP address	String

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

Additional information regarding status codes and payment type codes of transactions:

field

Description

status code

190 - Success: The payment is processed successfully.
490 - Failed: The transaction failed.
491 - Validation failed: The transaction request contained errors and could not be processed properly.
492 - Technical error: Due to a technical fault the transaction could not be completed.
690 - Rejected: The transaction is rejected by the (third party) payment provider.
790 - Pending entry: The transaction is on hold while the payment engine is waiting for input from consumers.
791 - Pending processing: The transaction will be processed.
792 - Awaiting the consumer: the payment Engine waits for consumers to return back from a third-party website, which is needed to complete the transaction.
793 - The transaction is on hold.
890 - Cancelled by User: The operation was cancelled by the customer.
891 - Cancelled by Merchant: The merchant has cancelled the transaction.

payment type code

C001***
C002 – first direct debit
C003 – recurring direct debit
C004 – first direct debit
C005 – recurring direct debit
C008 – SEPA direct debit
C021 – ideal
C101 – refund transfer
C121 – refund ideal
C102 – refund any direct debit trx
C500 – refund any direct debit trx
C565 – refund any Settlement by merchant trx
C501 – reversal
C561 --direct debit has been reversed by the customer (M.O.I)
C562 – reversal
I255 – credit note
I256 – Write-off
C461 – payments from collection agency
C462?***
N800 ***

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 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 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:

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

Resp. status code(s)	Payment type codes	Description	Action CDRator
190	C001/C002/C003 C004/C005 C008/C021	Successful: Payment/Direct debit/ iDEAL	The action required from CDRator for handling *(direct debit) payments* is Capture Payment by: Checking if the status code is 190. Not found -> write error to log, process next record. If status code is 190 and transaction code is C002/C003/C004/C005/C008 or C021, search for invoice number in field “Invoice number” and capture the payment with the debit amount specified in field “Amount Debit”. Write “successful result” to log file
190	C461/C462	Payments to the Collection Agency	The action required from CDRator for handling payments to the collection agency is Capture Payment by: Checking if the status code is 190. Not found -> write error to log, process next record. If status code is 190 and transaction code is C461/C462, search for invoice number in field “Invoice number” and capture the payment with the debit amount specified in field “Amount Debit”. Write “successful result” to log file
190	N800	Settlement by merchant	The action required from CDRator for handling BPE 3.0 settlements by merchant is Capture Payment by: Checking if the status code is 190. Not found -> write error to log, process next record. If status code is 190 and transaction code is N800, search for invoice number in field“Invoice number” and capture the payment with the debit amount specified in field “Amount Debit”. Write “successful result”to log file
190	C561/C562/C501	Reversal	The action required from CDRator for handling reversals is Insert Reversed Payment by: Checking if the status code is 190. Not found -> write error to log, process next record. If status code is 190 and transaction code is C561/C562/C501, search for invoice number in field“Invoice number” and capture the payment with the debit amount specified in field “Amount Credit”. Write “successful result”to log file

Refunds & Credit Notes

This category consists of:

Single refund transaction
Refund followed by a Credit Note
Single Credit Note transaction

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

Note:

A refund is usually followed by a credit note. However, a credit note could also be used as a single transaction, without being prior to a refund. Therefore, the refund should always be processed before the corresponding credit note.

Resp. code(s)

Transaction codes

Description

Action CDRator

190

C101/C102/C121C500/C565

Refund

The action required from CDRator for handling BPE 3.0 (single) refunds is Insert Reversed Payment by:* Checking if the status code is 190. Not found -> write error to log, process next record.

If status code is 190 and transaction code is C101/C102/C121/C500 or C565, search for invoice number in field “Invoice number” and insert a reversed payment with the negative credit amount specified in field “Amount Credit”.
Check if there is a corresponding credit note transaction by searching for status code 190 and transaction code I255, with an invoice number in the “Invoice number” field that has the prefix “CRN” followed by the invoice number of the refund. If so -> Process Credit Note. If not -> this can be seen as a single refund transaction
Write “successful result” to log file

190

I255

Credit Note

The action required from CDRator for handling BPE 3.0 credit notes is Insert positive payment by:

Checking if the status code is 190. Not found -> write error to log, process next record.
If status code is 190 and transaction code is I255 and invoice number in field “Invoice number” has a “CRN” prefix, Search for a refund transaction with status code 190, transaction code C101/C102/C121/C500 or C565 and the same invoicenumber (CRN excluded) in the field “Invoice number”). -> Process refund first if it is not processed yet.
If the invoice number in field “Invoice number” does not have the “CRN” prefix, this is a single credit note transaction. No need to search for a corresponding refund.
Search for amount in field “Amount Credit” and insert a positive debit payment.
Write “successful result” to log file

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 platform as a write-off.

Resp. status code(s)

Payment type codes

Description

Action CDRator

190

I256

Write off

The action required from CDRator for handling reversals is Insert Reversed Payment by:

Checking if the status code is 190. Not found -> write error to log, process next record.
If status code is 190 and transaction code is I256, search for invoice number in field “Invoice number” and insert a reversed payment with the negative credit amount specified in field “Amount Credit”.
Write “successful result” to log file

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 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), 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 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

Production Date

Interface

File Format

File Naming

Transport

Frequency

Connection Details

Messages

Payment Instruction Message

Payment Response Message

Payment File Format

Description of Payment Request csv-File Format

Description of Payment Response csv-File

Business Rules Payment Response Codes

Payments

Refunds & Credit Notes

Write-Off

Logging