| Wiki Markup |
|---|
{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:*
|| Date: || Author: || Version: || Changes: ||
| 03 Oct 2013 | KTH | 0.1 | Doc created. |
| | | | |
*Reference log:*
|| Document: || Version: || Date: ||
| | | |
h1. 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.
h2. 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:
h2. 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|Integration:Buckaroo].
{color:#003366}{*}Scope{*}{color}
The scope of this document is the interface between the Buckaroo BPE 3.0 and Rator.
h2. Production Date
XX November 2013.
h2. 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).
h2. 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{_}*.
h2. File naming
The names of the files are described in *{_}Payment File Format{_}*.
h2. Transport
The transport for the files is via SFTP. The SFTP server will be located with Buckaroo;
h3. 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
h3. Connection details
Connection details are still TBD
* IP address/URL:
* Directory:
* Username:
* Password:
* Certificate:
h1. 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{+}_
h2. 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.
h2. 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 the reason for receiving this message. It is primarily used to know what type of payment it is for ex: 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).
h1. Payment File Format
This section describes the Buckaroo file format (both request and response file formats) in detail.
h2. 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-out:*
{color:green}websitekey;amount;culture;currency;description;service;invoicenumber;service_directdebitrecurring_action;service_directdebitrecurring_customeraccountnumber;service_directdebitrecurring_customeraccountname;{color}
{color:green}additional_service;service_creditmanagement_action;phonenumber;customerlastname;service_creditmanagement_customeraccountnumber;customergender;amountvat;service_creditmanagement_maxreminderlevel;{color}
{color:green}invoicedate;service_creditmanagement_customerbirthdate;service_creditmanagement_paymentmethodsallowed;datedue;customertype;faxnumber;customeremail;customerfirstname;mobilephonenumber;customerinitials;{color}
{color:green}customertitle;customercode;customerlastnameprefix;address_street_1;address_housenumber_1;address_housenumbersuffix_1;address_zipcode_1;address_city_1;address_state_1;address_country_1{color}
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 (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 |
| 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.
h2. 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:*
{color:green}"Created";"Website";"Payment type";"Account number";"Customer";"Invoice number";"Description";"Amount Debit";"Amount credit";"Currency";"Status";{color}
{color:green}"Status date";"Success";"Reversal reason";"Country";"Transaction key";"IP Address"{color}
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 | Simyo 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 | REAL; 2 decimals, amount debited from customer account |
| *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 enginge is waiting on 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 canceled by the customer.
* 891 - Cancelled by Merchant: The merchant has canceled 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 \**\* |
h2. 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 processing the payment response codes from the Buckaroo file, the field "succesvol" must be "True". If not, process the next record.
h3. {color:#003366}{*}Payments *{color}
The payments category consists of:
# (direct debit) payments,
# payments done to the collection agency
# settlements by merchant (external payments done by the customer to Simyo'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 |
h3. 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 Simyo 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 |
h3. 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 | {color:#ff0000}*\-*{color} 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\\ |
h2. *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. |
\\ |
Page Comparison
General
Content
Integrations