| 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}
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. Summary
This document describes the interfacing between the Rator Customer Care and Billing System (Rator) and the Buckaroo BPE 3.0 payment systems .
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.
h1. 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.COUNTRY \\ | String \\ | Country code value | NO \\ | _NL_ |
| INTEGRATION.BUCKAROO.BPE3.STATUS_MSG_REFUND\\ | String\\ | Status message set byThe following parameter entries are used to specify the capture engine onconfiguration:
the
response
record || 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 \\ | _Acccount payment has already been captured._ \\ |
| | | | | |
| INTEGRATION.BUCKAROO.BPE3.PAYMENT_METHOD_INVALID_BANK_ACC\\ | String\\ | Simyo Specific ?? | | |
| INTEGRATION.BUCKAROO.BPE3.DECEASED_CUST_EMAIL_ADDR\\ | String\\ | Simyo Specific ??\\ | | |
| INTEGRATION.BUCKAROO.BPE3.PLACE_HOLDER_EMAIL_ADDR\\ | String\\ | Simyo Specific ??\\ | | |
| INTEGRATION.BUCKAROO.BPE3.TEST_ACCOUNT_EMAIL_ADDR\\ | String\\ | Simyo Specific ??\\ | | |
| | | | | |
h1. 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 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
* 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
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 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).
h1. 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).
h2. Regular payment
The most common case will be the case of regular payment depicted in the following diagram.
*Figure : Regular payment*
h2. 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%.
h2. 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
h1. 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
* 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.
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 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).
h1. 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).
h2. Regular payment
The most common case will be the case of regular payment depicted in the following diagram.
*Figure : Regular payment*
h2. 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%.
h2. 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.
h2. 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 noin payment*
NotesNote:
* TheIn reversalcase instructionof messageinvolvement canof appearthe soonercollection 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.
h2. 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%
h2. 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*
h1. Payment format
This section describes the Bucakaroo file format 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 the payment requests.
Record lay-out:
_Merchantkey,accountnumber,invoicenumber,invoicedate,customeraccountnumber,customeraccountname,paymentdatedue,collectdate,currency,amount,invoicevat,description,reference,language,paymentmethodsallowed,maxreminderlevel,customerid,initials,firstname,lastname,gender,address1,address2,zipcode,city,state,country,mail,phone,gsm,fax,icq,skype,msn_agency (paymentcode=461) we will not receive the full payment, but at most 90%
h2. 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*
h1. Payment File format
This section describes the Buckaroo file format 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 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 ||
| *merchantkey*websitekey\\ | \- | XyzTBD | Buckaroo Merchant key. \\
Final merchantkey will be available on the Buckaroo Plaza when contracts are in place. |
| *accountnumber* | \- | 777000000TBDFSsfaJKF&6GH\\
\\ | Buckaroo internal accountnumberWebsitekey. \\
Fixed string Finalfrom accountBuckaroo numberportal\\ will|
be available on the Buckaroo Plaza when contracts are in place.| amount \\ | \- | 10.00 \\ | REAL, 2 decimals; amount\\ |
| *invoicenumber*culture \\ | invoice.INVOICE_NUMBER | 21698937nl-NL | Invoice - Alpha numeric max. field Length 255String, ISO culture code |
| *invoicedate*currency \\ | invoice.CLOSE_DATE | 2009-11-26EUR | YYYY-MM-DD Fixed string for currency code |
| *customeraccountnumber*description \\ | Billing_group_bank_account.BANK_ACCOUNT_NUMBERACCOUNT_NUMBER | Test Incasso 1 | String; description, max length 100 chars |
| service \\ | users.FIRST_NAME + users.LAST_NAME | 1234567Directdebitrecurring | String; CustomerBuckaroo Bankservice accountname |
| *customeraccountname*invoicenumber \\ | usersinvoice.FIRSTDUE_NAMEDATE + users.LAST_NAME| Test01923r4e | M.String; BergInvoice |number, Fullmax customerlength name100 max.chars 32|
characters| service_directdebitrecurring_action\\ Concatenate FIRST_NAME and LAST_NAME and take the first 32 characters from the left. |
| *paymentdatedue* | invoice.DUE_DATE | 2009-12-22 | YYYY-MM-DD |
| *collectdate* | \- | 2009-12-15 | YYYY-MM-DD \\
Is set with the generation date of the batch file. |
| *currency*| \- | Pay | String; Pay or Refund (See Buckaroo service description) |
| service_directdebitrecurring_customeraccountnumber\\ | \- | 123456789 | Bank Account; Must be 11 proof. Empty or null value not allowed |
| service_directdebitrecurring_customeraccountname \\ | invoice.TOTAL_EXCL_VAT + invoice.TOTAL_VAT -- invoice.PAYED_AMOUNT | T.Test | String; account name |
| additional_service \\ | \- | EURCreditmanagement | currency code for payments String; see *Buckaroo Service description * \\
\\ |
| *amount*service_creditmanagement_action \\ | invoice.TOTAL_EXCL_VAT <Description Prefix> + invoice.TOTAL_VAT -- invoice.PAYED_AMOUNTaccount_payment.REFERENCE | 1000Invoice | Fixed TotalString invoice|
amount in *eurocents* incl. VAT \\
Example value for 10 Euro: 1000 |
| *invoicevat*| phonenumber \\ | account_payment.REFERENCE | 0201111111 | String; Phone number |
| customerlastname \\ | \- | 190Tester | 19%String; VATcustomer overlast thename, valuemax in export field "amount" in *eurocents* \\
Example: \\
Value for amount = 1000. \\
Value for invoicevat will be: \\
1000 * 0.19 = 190 Euro cents |
| *description* | <Description Prefix> + account_payment.REFERENCE | <COnfigurable prefix text> P32842343S4KSD6 | Max. 32 characters \\
Example: \\
DescPrefixP32842343S4KSD6 |
| *reference* | account_payment.REFERENCE | P32842343S4KSD6 | Max. 32 characters |
| *language* | \- | NL | Options: NL, EN, DE, FR \\
Example value: NL |
| *paymentmethodsallowed* | \- | machtiging | Example value: machtiging |
| *maxreminderlevel*200 chars |
| service_creditmanagement_customeraccountnumber \\ | \- | 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 \\ | \- | 1 | Integer, may not be empty \\
0: Unknown \\
1: Male \\
2: Female \\
9: Irrelevant (currently not used) |
| amountvat \\ | account.CUSTOMER_NUMBER | 0.00 | Real, 2 decimals\\
Example: \\
Value for amount = 1000. \\
Value for invoicevat will be: \\
1000 * 0.19 = 190 Euro cents\\ |
| service_creditmanagement_maxreminderlevel \\ | \- | 4 | 0: No reminders \\
1: only 1st reminder \\
2: till 2nd reminder \\
3: till last reminder \\
4: including hand-over to collection agency \\
Example value: 4 |
| *customerid* | account.CUSTOMER_NUMBER | 21698937 | Unique customer number |
| *initials* | \- | | Max. 8 characters. This field is not used. |
| *firstname* | users.FIRST_NAME | | Max. 32 characters |
| *lastname* | users.LAST_NAME | Berg | Max. 32 characters |
| *gender* | users.GENDER | 2 | "0" = Unknown \\
"1" of "M" = Male \\
"2" of "F" = Female |
| *address1* | users.STREET + users.STREET_NUMBER + users.FLOOR | Zonnebaan 9 | First address |
| *address2* | \- | | Second address (optional field) |
| *zipcode* | users.ZIP | 3542 EA | |
| *city* | users.CITY | Utrecht | |
| *state* | \- | | (Optional field) |
| *country* | \- | NL | NL, BE, DE, FR, EN |
| *mail* | users.EMAIL | arnoud@xs4all.nl | e-mail address format |
| *phone* | service.PHONE_NUMBER | \+31613245760 | Number based on country code \+31xxxxxxxxxx |
| *gsm*1 | INTEGER, may not be emptyChoose from {0,1,2,3,4}. Default is 4\\ |
| invoicedate \\ | users.FIRST_NAME | 2012-01-10 | YYYY-MM-DD; Invoice date |
| service_creditmanagement_customerbirthdate \\ | users.LAST_NAME | 1970-01-13 | YYYY-MM-DD; Birth date\\ |
| service_creditmanagement_paymentmethodsallowed \\ | users.GENDER | machtiging,ideal | String; Comma seaparated list of allowed methods of payment as offered by Buckaroo. See Buckaroo Service description for possible values |
| datedue \\ | users.STREET + users.STREET_NUMBER + users.FLOOR | 2012-01-27 | YYYY-MM-DD; due date |
| customertype \\ | \- | 1 | String; type of customer\\
Currently not used |
| faxnumber \\ | users.ZIP | 0309999999 | String; Fax number |
| customeremail \\ | users.CITY | support@buckaroo.nl | String; customer email address |
| customerfirstname \\ | \- | Test | String; Customer first name |
| mobilephonenumber \\ | \- | 0601111111 | String; mobile number |
| customerinitials \\ | users.EMAIL | arnoud@xs4all.nl | e-mail address format |
| customertitle \\ | service.PHONE_NUMBER | \+31613245760 | Number based on country code \+31xxxxxxxxxx |
| customercode \\ | \- | | (Optional field) |
| customerlastnameprefix \\ | \- | | (Optional field) |
| address_street_1 \\ | \- | | (Optional field) |
| address_housenumber_1 \\ | \- | | (Optional field) |
| *fax*address_housenumbersuffix_1 \\ | \- | | (Optional field) |
| *icq*address_zipcode_1 \\ | | \-| |
| (Optional field)address_city_1 \\ | | | *skype*|
| \-address_state_1 \\ | | (Optional field) | | *msn*
| \-address_country_1 \\ | | (Optional field)| |
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::
_Date,Time,Date received,Name;Payment code,Card,Invoice,Description,Currency,Debit,Credit,Fees,VAT_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
_New format:_
_Date,Time,Name;Payment code,Card,Invoice,Description,Currency,Debit,Credit,_ *{_}Amount Payout{_}*
Field separators: semi-colon (";" )
*Content fields:*
| *date (datum)* | Date format: YYYY-MM-DD |
| *time (tijd)* | Time optional field in timeformat HH : MM : SS |
| *{_}name(naam)_* | Name\- Alpha numeric max. field Length 255 |
| *payment code* | Payment codes with financial impact: \\
*071;This refund has been successfully processed.* \\
100;This transaction has been approved by the credit card issuer. \\
121;Transaction status: authorisation successful. \\
151;Transaction status: authorisation successful. \\
171;Transaction status: authorisation successful \\
301;The transfer has been received. \\
*390;The transaction has been settled with the customer without the interference of Buckaroo.* \\
401;Successful gift card payment. \\
461;Payment received from collection agency \\
462;Payment received from collection agency. 10% bonus for the agency. \\
601;This direct debit has been processed successfully. \\
*605;This direct debit has been reversed by the bank.* \\
*612;Direct Debit has been reversed by the customer (M.O.I.)* \\
801;This iDEAL transaction has been successfully processed. \\
821;This Giropay transaction has been successfully processed \\
The codes *{_}marked{_}* could contain credit transaction on an invoice. \\
In due time new codes will be added when additional payment methods become available. |
| *card* | Payment type: \\
Result in Debit transaction: \\
overschrijving : transfer \\
iDeal - <xxxxx> : IDeal transaction for <xxxxx> bank \\
giropay - <xxxxx>: : Giropay transaction for <xxxxx> bank \\
paypermail \\
machtiging \\
paysafecard \\
cashticket \\
correctiebetaling \\
verrekening negatief saldo \\
Result in Credit transaction \\
Refund - <yyyyy> : Refund of amount with paymount method <yyyyy> \\
stornering : reversal \\
incassobureau : Feedback from collection agency |
| *invoicenumber (Factuur)* | Invoice - Alpha numeric max. field Length 255 |
| *description (omschrijving)* | Description - Alpha numeric max. field Length 100 |
| *currency (Valuta)* | Value: "EUR" |
| *debit* | Debit amounts euro cents |
| *Credit* | Credit amounts euro cents |
| *Amount Payout* | Sum of credit and debit amount (in cents, can be negative) |
Filename for daily transactions: trx_2010-05-25.csv Date format 2010-05-25 is YYYY-MM-DD
h2. Business rules payment response codes
*Log file*
For each response file that is processed, the Rator system has to generate a log file. For each processed record a row must be written to the log file which indicates if the record is successfully processed. 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 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) || Description || Action CDRator ||
| 601 | Successful | *Capture payment:*
* Search for the payment on Reference (last 15 characters of the description of the response). 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. |
| 605 or 612 | Reversed | *Capture original payment and insert reversed payment:*
* Search for the payment on Reference (last 15 characters of the description of the response). 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. |
| 301 or 461 or 801 | Non regular payments. | *It might be a partial payment:*
* Capture original payment or insert partial payment.
* Search for the payment on Reference. 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. |
| 462 \\ | Bonus for IMN \\ | *10% amount of the invoice for IMN*
* Insert absolute value of the payment amount. This is the payment for IMN agency. The value comes as negative amount, but it needs to be converted to absolute value, so the invoice can be closed properly. |
| 071 | Refund | *Insert refund to the invoice:*
* Search the invoice on the invoice number of the payment response. Not found write "invoice not found" error to log, process next record.
* Insert the refund as a new negative payment with payment_type_id "Buckaroo" - refund payment. Write log record. |
| 390 | Settled by merchant | *No action required* \\
This response code can be ignored by CDRator (only write a record to the log file). This code is used when the customer paid the amount directly to Service provider. An employee of Service providerfinance will capture the payment. Note: maybe log it for reporting (low priority - future release). | |
Page Comparison
General
Content
Integrations