Технически изисквания за връзка с платежната система EasyPay/ePay.bg

Особености при подаване на файлове

Търговецът подготвя и предоставя на Оператора файл в текстов формат и разширение .txt или .csv. Съдържанието носи информация за абонатния номер и дължимата сума. Енкодингът трябва да бъде Windows CP-1251.

Подаване на файл

Допуска се подаваният файл да е архивиран (zip, rar или tar.gz), но съдържанието на архива трябва да е във формат .csv или .txt.

Достъп до системата

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

Операторът предоставя достъп до специализиран WEB интерфейс за управление на информацията от страна на търговеца - зареждане на файлове със задължения на клиентите и получаване на справка за платените сметки. Достъпът до WEB интерфейса се осъществява с потребителско име, парола и софтуерен сертификат.

За да се запознаете с функционалностите на системата натиснете тук.

Плащания от клиенти

Идентификаторът, по който клиент ще може да разплаща задълженията си, е абонатен номер. На каса на EasyPay се посочва абонатен номер и името на търговеца.
При плащане онлайн чрез ePay.bg се добавят търговецът и съответният абонатен номер на клиента, в неговата регистрация.

Структура на файла

Задължителна информация

• Абонатен номер
• Сума на задължението

При повече от едно задължение сумата се начислява от търговеца и се подава общо задължение към Оператора.

Важно

За всеки абонат във файла, подаван от търговеца, трябва да има само един запис (ред). Ако даден абонатен номер присъства на повече от един ред, той се счита за дублиран.

Всички редове с дублиран номер ще бъдат игнорирани от системата.

Сесия (session):

Сесията представлява дата, с точност до секунда, а присъствието ѝ е задължително.

Синтаксисът е:

session=20151109114043 (ГГГГММДДччммсс)

Правилото за сесията е, че трябва да се ползва числото, което фигурира в последния репорт, издаден от Оператора, който търговеца е обработил. С това търговецът потвърждава, че е обработил всички репорти, издадени към момента на зареждане.

Начини за залагане на сесия:

• Да фигурира във файла със задължения, подаван от търговеца (виж примерния файл).
• Да се добави при зареждането на файла в търговската система, в съответното поле.

Допълнителна информация

• Име на абоната
• Адрес
• Срок за плащане
• Тип задължение
• Всяка друга информация, която нуждите на търговеца изискват

Разделители

За разделители на колоните с информация може да се използва символ според преценка на търговеца.

Подходящи символиНеподходящи символи

Символ	Описание (име)
|	Pipeline
:	Двоеточие
;	Точка и запетая
⇆	Tab

Символ	Описание (име)
.	Точка
,	Запетая
␣	Space
"	Кавичка

Примерен файл със задължения от търговеца, в който за разделител е
ползван Pipeline (|):

ANUM|NAME|ADDRES|MONTH|YEAR|AMOUNT
202779050|Марин Маринов|гр. София,жк. Младост 1, бл. 388, ап. 5|05|2015|430.25
131503520|Стефан Петров Тодоров|ул. Ангел Кънчев N17, вх. А|06|2015|155.67
182703523|Ралица Борисова|Люлин 6, бл. 513 вх. А, ап. 24|10|2014|170.01
session=20151109114043

Подредбата на колоните с информация не е регламентирана, но тя трябва да бъде идентична всеки път, според уговорения между търговеца и Оператора шаблон.

Задължителни колони

Параметър	Описание	Допълнение
ANUM	Абонатен номер	Приемат се единствено цифри
AMOUNT	Сума за плащане	За десетичен разделител са позволени точка или запетая 155.67 или 155,67

Опционални колони

Всичко различно от абонатен номер и сума е опционално, но колони, носещи информация за име и адрес, са допълнително пояснение за платеца.

Инфо

Макар те да са опционални, наличието на допълнителна информация е препоръчително.

Справката за извършени плащания, генерирана от Оператора (Репорт)

Операторът ще генерира репорт файл всеки ден, след 11:20ч. дори когато няма плащания. Периодът, който обхваща е от 11:20ч. на текущия ден, до 11:20ч. на предходния (24 часа). Задължение на търговеца е да обработва данните от всички генерирани репорти преди зареждането на нов файл със задължения.

Примерен репорт, генериран от Оператора

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

Структурата на колоните е следната: 1:2:3:4:5

Индекс	Описание
1	Абонатен номер
2	Дата и час на плащане, с точност до секунда ГГГГММДДччммсс
3	Сума
4	Референция в EasyPay/ePay.bg
5	Източник на плащане

На последен ред:

сесия / брой плащания във файла / обща сума

Източник на плащане

Винаги се състои от шест цифри. Трансакции с източник 70002x и 7001xx се считат за касови плащания през EasyPay, всички останали може да се разглеждат като електронно плащане чрез ePay.bg. Следвайки тази логика, може да разгледаме източниците от примерния репорт:

• 700020 и 700021 спадат към EasyPay - плащане в брой на каса.
• 700011 спада към електронно плащане през ePay.bg.

Периодичност на подаване на файл от търговеца към Оператора

Периодът, през който търговецът ще подава файл, е по негова преценка - веднъж дневно, седмично, месечно или какъвто интервал от време е необходим. Същественото тук е да се спазва правилото за обработка на всички генерирани репорти от Оператора до момента на зареждане.

Периодичност на спиране на търговеца за плащане

Търговецът може да избере възможността за плащане от клиентите да бъде спирана през регулярен, предварително уточнен интервал. Това се прави с цел улесняване на обработката на генерираните репорти за станали плащания, преди зареждането на нов файл. Периодът и времетраенето се избира от търговеца. По подразбиране тази опция не е активна.

Извънредно добавяне на абонати към файл от търговеца

В случай че в базата на търговеца има постъпили нови абонати през време, което не е удобно да се зареди нов файл, системата предлага опция за добавяне само на новите данни. Това става с ключова дума "mrcsappend" , която се залага в името на файла.

Важно

Тази функционалност служи само за добавяне на нови абонати! Tя не служи за обновяване на задължения на текущите клиенти.

Примерен сценарий

Търговецът е заредил файл на 01.03.2015, следващото регламентирано зареждане ще е на 01.04.2015. В средата на месеца се появяват двама нови клиента в базата на търговеца. Вместо да чака до 01.04, търговецът ще изготви файл с идентична на регламентираната структура, но като данни ще фигурират само новите два абоната.

Редовен файл

Стандартният файл, зареден на 01.03.2015, от търговеца е именуван "epay_obligations0103.csv"

1001|Иван Маджаров|София, жк. Овча Купел 3|50|Курс по Йога
1002|Петя Михайлова|ул. Иван Вазов 17, Офис Сграда 1|113.50|Курс по Йога
1003|Андрей Василев|жк. Борово, бл. 40А|17|Курс по Йога
session=20150301114043

Извънреден файл с нови абонати

Това са новите двама абонати, които търговеца желае да добави. Структурата e идентична с тaзи на редовните файлове, с изключение на сесията - такава не се подава. Името на файла е "epay_obligations1503.mrcsappend.csv"
Чрез ключовата дума "mrcsappend" системата разбира, че търговеца желае само да добави нови записи, а не да обнови файла изцяло.

1004|Кремена Николова|Люлин 3, бл 212, ап. 61|50|Курс по Йога
1005|Магдалена Димитрова|жк. Люлин 3, бл 1|25|Курс по Йога

Допълнение за разплащане на задължение по фактури

Задължителна информация

• Абонатен номер
• Сума на задължението
• Номер на фактура

При повече от едно задължение на един клиент, всяка сума се подава на нов ред, в комбинация с абонатния номер и уникален номер на фактура (уникалността се следи само в конкретния файл).

Допълнителна информация

• Име на абоната
• Адрес
• Срок заплащане
• Тип задължение
• Номер на фактура
• Всякаква друга информация, която нуждите на търговеца изискват

Важно

За всеки абонат във файла, с повече от едно задължение, винаги трябва да има уникална комбинация от абонатен номер и фактура. Ако дадена комбинация присъства на повече от един ред, се счита за дублирана.

Всички дублирани редове ще бъдат игнорирани от системата.

Примерен файл със задължения от търговеца, в който за разделител се ползва точка и запетая ';'

ANUM;NAME;ADDRES;INVOICE;PHONE;AMOUNT;TYPE
112233;Захари Стоянов;гр. Перник, жк. Бяла, бл.8, ап. 1;0101;0888888888;10.50;Такса смет
434343;Иван Петров;жк. Витоша, ул, Народен Будител 8, Офис 1;0101;0888888888;12.99;Такса смет
434343;Иван Петров;жк. Витоша, ул, Народен Будител 8, Офис 1;0102;0888888888;12.99;Такса смет
434343;Иван Петров;жк. Витоша, ул, Народен Будител 8, Офис 1;0103;0888888888;16.99;Такса смет
100000;Клара Вълкова;Западен парк, бл. 13 вх. Г, ап. 6;2211;0888888888;0.99;Такса наем
100000;Клара Вълкова;Западен парк, бл. 13 вх. Г, ап. 6;2316;0888888888;0.99;Такса наем
100000;Клара Вълкова;Западен парк, бл. 13 вх. Г, ап. 6;2411;0888888888;0.99;Такса наем
100000;Клара Вълкова;Западен парк, бл. 13 вх. Г, ап. 6;2515;0888888888;0.99;Такса наем
100000;Клара Вълкова;Западен парк, бл. 13 вх. Г, ап. 6;2612;0888888888;0.99;Такса наем
session=20151201134042

Задължителни колони

Параметър	Описание	Допълнение
ANUM	Абонатен номер	Приемат се единствено цифри
AMOUNT	Сума за плащане	За десетичен разделител са позволени точка или запетая 12.99 или 12,99
INVOICE	Номер на Фактура	Приемат се цифри, не е позволено дублиране на един абонат в един файл

Примерен репорт, генериран от Оператора

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

Структурата на колоните е следната: 1:2:3:4:5:6

Индекс	Описание
1	Абонатен номер
2	Фактура
3	Дата и час на плащане, с точност до секунда (ГГГГММДДччммсс)
4	Сума
5	Референция в EasyPay/ePay.bg
6	Източник на плащане

На последен ред:

сесия / брой плащания във файла / обща сума