Technical requirements for connection to the EasyPay/ePay.bg payment system

Peculiarities when submitting files

The merchant prepares and provides the Operator with a file in text format and .txt or .csv extension. The content carries information about the subscriber number and the amount due. Encoding should be Windows CP-1251.

File Submission

The submitted file can be archived (zip, rar, or tar.gz), but the contents of the archive must be in .csv or .txt format.

Access to the system

URL - https://mrcs.easypay.bg/

The operator provides access to a specialized WEB interface for information management by the merchant - uploading files with customer obligations and receiving a report on paid bills. Access to the WEB interface is achieved with a username, password, and software certificate.

To familiarize yourself with the functionalities of the system click here.

Payments from customers

The identifier by which a customer will be able to pay his debts is a subscriber number. The subscriber number and the name of the merchant are indicated at the EasyPay checkout. When paying online via ePay.bg, the merchant and the customer's corresponding subscriber number are added to his registration.

File structure

Mandatory information

• Subscriber number
• Amount of the obligation

In case of more than one obligation, the amount is charged by the merchant, and a general obligation is submitted to the Operator.

Important

There should be only one entry (line) for each subscriber in the file submitted by the merchant. If a subscriber number is present on more than one line, it is considered a duplicate.

All rows with duplicate numbers will be ignored by the system.

Session (session):

The session is a date, accurate to the second, and its presence is mandatory.

The syntax is:

session=20151109114043 (YYYYMMDDhhmmss)

The rule for the session is that the number that appears in the last report issued by the Operator that the Trader processed must be used. The merchant hereby confirms that it has processed all reports issued at the time of loading.

Ways to bet on a session:

• To appear in the liability file submitted by the Merchant (see sample file).
• To be added when loading the file in the trading system, in the corresponding field.

More information

• Name of the subscriber
• Address
• Payment period
• Obligation type
• Any other information that the merchant needs require

Separators

A symbol may be used for information column separators at the merchant's discretion.

Eligible charactersInvalid characters

Symbol	Description (name)
|	Pipeline
:	Colon
;	Semicolon
⇆	Tab

Symbol	Description (name)
.	Point
,	Comma
␣	Space
"	A quotation mark

An example file with obligations from the merchant, in which Pipeline | is used as a delimiter

ANUM|NAME|ADDRESS|MONTH|YEAR|AMOUNT
202779050|Marin Marinov|city Sofia, gh. Mladost 1, bl. 388, app. 5|05|2015|430.25
131503520|Stefan Petrov Todorov|ul. Angel Kanchev N17, entrance A|06|2015|155.67
182703523|Ralitsa Borisova|6 Lyulin, bl. 513 entrance Ah, app. 24|10|2014|170.01
session=20151109114043

The arrangement of the columns of information is not regulated, but it must be identical every time, according to the template agreed upon between the Merchant and the Operator.

Required columns

Parameter	Description	Addition
ANUM	Subscriber Number	Only numbers are accepted
AMOUNT	Payment amount	Period or comma allowed for decimal separator 155.67 or 155,67

Optional columns

Everything other than subscriber number and amount is optional, but columns bearing name and address information are additional clarification for the payer.

Info

Although these are optional, the availability of additional information is recommended.

The statement of payments made, generated by the Operator (Report)

The operator will generate a report file every day after 11:20 am. even when there are no payments. The period it covers is from 11:20 am. on the current day, until 11:20 am. of the previous one (24 hours). It is the merchant's duty to process the data from all generated reports before loading a new file with obligations.

Sample report generated by the Operator

202779050:20151109151215:430.25:449297449297:700020
131503520:20151109164216:155.67:523619523619:700021
131503523:20151109164216:170.01:523617523617:700011
session: 20151110112034: 3 records: total: 755.93

The column structure is as follows: 1:2:3:4:5

Index	Description
1	Subscriber number
2	Date and time of payment, accurate to the second YYYYMMDDhhmmss
3	Amount
4	Reference in EasyPay/ePay.bg
5	Payment source

On the last line: session/number of payments on file/total amount

Payment Source

It always consists of six digits. Transactions with sources 70002x and 7001xx are considered cash payments via EasyPay, all others can be considered as electronic payments via ePay.bg. Following this logic, we can look at the sources of the sample report:

• 700020 and 700021 belong to EasyPay - payment in cash at the cash register.
• 700011 belongs to electronic payment via ePay.bg.

Frequency of file submission from the merchant to the Operator

The period during which the merchant will submit a file is at his discretion - once a day, weekly, monthly, or whatever time interval is needed. The essential thing here is to observe the rule for processing all reports generated by the Operator until the moment of loading.

Frequency of suspension of the merchant for payment

The merchant may choose to suspend payment from customers at a regular, pre-specified interval. This is done in order to facilitate the processing of generated reports on payments made, before loading a new file. The period and duration are chosen by the merchant. By default, this option is not active.

Extraordinary addition of subscribers to a file by the merchant

In the event that there are new subscribers in the Trader's database during a time when it is not convenient to load a new file, the system offers an option to add only the new data. This is done with the keyword "mrcsappend", which is placed in the file name.

Important

This functionality is only for adding new subscribers! It does not serve to renew the obligations of current customers.

Sample scenario

The merchant uploaded a file on 03/01/2015, the next scheduled upload will be on 04/01/2015. In the middle of the month, two new clients appear in the Trader's base. Instead of waiting until 01.04, the merchant will prepare a file with an identical structure to the regulated one, but only the new two subscribers will appear as data.

Regular file

The standard file uploaded on 03/01/2015 by the merchant is named "epay_obligations0103.csv"

1001|Ivan Madzharov|Sofia, gh. Ovcha Cupel 3|50|Yoga course
1002|Petya Mihailova|ul. Ivan Vazov 17, Office Building 1|113.50|Yoga course
1003|Andrei Vassilev| Borovo, bl. 40A|17|Yoga course
session=20150301114043

An extraordinary file of new subscribers

These are the new two subscribers that the merchant wishes to add. The structure is identical to that of the regular files, except for the session - it is not submitted. The file name is "epay_obligations1503.mrcsappend.csv" Through the keyword "mrcsappend" the system understands that the merchant only wants to add new entries, not to refresh the file entirely.

1004|Kremena Nikolova|Lyulin 3, bl 212, apartment 61|50|Yoga course
1005 | Magdalena Dimitrova | Lyulin 3, bl 1|25|Yoga course

Addendum for payment of an obligation on invoices

Mandatory information

• Subscriber number
• Amount of the obligation
• Invoice number

In case of more than one obligation of one customer, each amount is submitted on a new line, in combination with the subscriber number and a unique invoice number (uniqueness is monitored only in the specific file).

More information

• Name of the subscriber
• Address
• Payment period
• Obligation type
• Invoice number
• Any other information that the merchant needs require

Important

For each subscriber on file, with more than one obligation, there must always be a unique combination of subscriber number and invoice. If a combination is present on more than one line, it is considered a duplicate.

All duplicate rows will be ignored by the system.

Sample file with obligations from the merchant, in which the semicolon ';' is used as a separator

ANUM;NAME;ADDRESS;INVOICE;PHONE;AMOUNT;TYPE
112233; Zahari Stoyanov; town Pernik, village Byala, bl. 8, apartment 1;0101;0888888888;10.50;Garbage fee
434343; Ivan Petrov; gk. Vitosha, Naroden Buditel 8, Office 1; 0101; 0888888888; 12.99; Garbage fee
434343; Ivan Petrov; gk. Vitosha, Naroden Buditel 8, Office 1; 0102; 0888888888; 12.99; Garbage fee
434343; Ivan Petrov; gk. Vitosha, Naroden Buditel 8, Office 1; 0103; 0888888888; 16.99; Garbage fee
100000; Klara Valkova; Zapaden park, bl. 13 entrance D, app. 6;2211;0888888888;0.99;Rental fee
100000; Klara Valkova; Zapaden park, bl. 13 entrance D, app. 6;2316;0888888888;0.99;Rental fee
100000; Klara Valkova; Zapaden park, bl. 13 entrance D, app. 6;2411;0888888888;0.99;Rental fee
100000; Klara Valkova; Zapaden park, bl. 13 entrance D, app. 6;2515;0888888888;0.99;Rental fee
100000; Klara Valkova; Zapaden park, bl. 13 entrance D, app. 6;2612;0888888888;0.99;Rental fee
session=20151201134042

Required columns

Parameter	Description	Addition
ANUM	Subscriber Number	Only numbers are accepted
AMOUNT	Amount to pay	Period or comma allowed for decimal separator 12.99 or 12,99
INVOICE	Invoice Number	Numbers are accepted, no duplication of one subscriber in one file is allowed

Sample report generated by the Operator

112233:0101:20151204121549:10.50:404487404487:700020
434343:0101:20151104122001:12.99:404489404489:700020
434343:0102:20151104122001:12.99:404490404490:700020
100000:2211:20151104122001:0.99:404491404491:700010
session: 20151205112012: 4 records: total: 37.47

The column structure is as follows: 1:2:3:4:5:6

Index	Description
1	Subscriber number
2	Invoice
3	Date and time of payment, accurate to the second (YYYYMMDDhhmmss)
4	Amount
5	Reference in EasyPay/ePay.bg
6	Payment source

On the last line:

session/number of payments on file/total amount