Вносна бележка - заявка за плащане

Обща информация

• Клиент - Краен потребител на услугата
• Търговец - Юридическо лице, сключило договор с ePay.bg
• Файловете, които се цитират в документацията, може да се свалят от линка "Демо пакет" под бутона за вход на https://demo.epay.bg/

Всеки регистриран търговец в системата на ePay.bg има

• Буквено-цифрена секретна дума с дължина 64 (secret)
• Клиентски идентификационен номер (KIN)

Търговецът може да ги открие в профила си в https://epay.bg/, без да може да ги променя.

Плащане в брой през EasyPay

Описание на процеса

Търговецът изпраща HTTP GET заявка за паричен превод към даденото URL.

1. Заявка за плащане към търговец.
2. В сайта на търговеца, клиентът избира желаната услуга и като начин на плащане - EasyPay.
3. Търговецът изготвя заявка за плащане, който изпраща към URL в ePay.bg като HTTP GET заявка. В същата HTTP сесия, ePay.bg връща на търговеца "Код за плащане". Търговецът показва на своя сайт този код, чрез който клиентът може да плати в брой в EasyPay.
4. При плащане, ePay.bg генерира банков превод с данните от заявката.
5. ePay.bg следи за статуса на регистрираните/записаните чакащи задължения и при плащане, отказване или изтичане на времето за плащане, изпраща известие към търговеца за статуса на всяко плащане. Известията от системата се изпращат на портове:
   • 80 за HTTP
   • 443 за HTTPS
6. При получаване на известие от ePay.bg, търговецът трябва да формира съответен отговор.

Комуникационна схема

Продукционна среда

Метод	URL
GET	https://www.epay.bg/ezp/reg_vnbel.cgi

Демо среда

Метод	URL
GET	https://demo.epay.bg/ezp/reg_bill.cgi

Заявка за плащане

Параметър	Тип	Описание	Опционалност
ENCODED	string	Кодирана с base64 (RFC 3548) заявка за плащане, EOL=''.	Задължителен
CHECKSUM	string	Контролна сума върху ENCODED, генерирана като HMAC с алгоритъм SHA-1 и секретната дума на търговеца.	Задължителен

Параметри в ENCODED

Параметър	Тип	Описание	Опционалност
MIN	int	Идентификационен номер на търговеца - Съответства на КИН в профила на търговеца в ePay.bg	Задължителен
INVOICE	int	Номер на фактура; уникален за търговеца	Задължителен
AMOUNT	float	Валидна сума > 0.01 (например: 22, 22.8, 22.80)	Задължителен
EXP_TIME	datetime	Крайна дата/час за плащане, до 30 дни след датата на заявката; формат DD.MM.YYYY [hh:mm [:ss]]	Задължителен
DESCR	string	Описание до 100 символа; encoding CP1251	Опционален
MERCHANT	string	Получател на нареждането	Задължителен
IBAN	string	Валиден IBAN на получателя	Задължителен
BIC	string	BIC на банката получател	Задължителен
STATEMENT	string	Описание на плащането	Задължителен
PSTATEMENT	int	Код на плащането	Задължителен
OBLIG_PERSON	string	Име на задълженото лице; до 26 символа	Задължителен
BULSTAT EGN LNC	int	БУЛСТАТ, ЕГН или ЛЧН Подава се само един от трите параметри!	Задължителен
DOC_NO	int	Вид и номер на документ	Задължителен
DOC_DATE	int	Дата на документ: Параметърът се подава при вид на документ - 2|3|6	Задължителен при: 2|3|6
DATE_BEGIN	int	Начало на период: Параметърът се подава при вид на документ - 1|2|4|5	Задължителен при: 1|2|4|5
DATE_END	int	Край на период: Параметърът се подава при вид на документ - 1|2|4|5	Задължителен при: 1|2|4|5

При подаване на заявката

• Не е задължително параметрите да са подредени в този ред.
• Ако платежното е многоредово, то параметърът AMOUNT се заменя с TOTAL, а за всяко отделно плащане сумата се подава с параметър съответно SUM1, SUM2, SUM3..

Примерна заявка

PerlPHP

{
    # Кодиране на заявката
    $ENCODED = encode_base64('DATA', ''); # '' за EOL (def. е "\n")

    # Генериране на контролна сума
    $CHECKSUM = hmac_hex($ENCODED, $secret, \&sha1);
}

{
    $data = base64_decode($ENCODED);

    # Калкулиране на контролната сума
    # Трябва $CHECKSUM_CALC == $CHECKSUM
    $CHECKSUM_CALC = hmac('sha1', $ENCODED, $secret);
    # кода на функцията hmac може да видите в demo.php   
}

Примерно известие от ePay.bg

ПлатеноИзтеклоОтказано

INVOICE=123456:STATUS=PAID:PAY_TIME=YYYYMMDDhhmmss:STAN=[6 числа]:BCODE=[6 числа/букви]

INVOICE=123457:STATUS=EXPIRED

INVOICE=123457:STATUS=DENIED

Параметър	Описание
STAN	Номер транзакция, само при плащане с карта
BCODE	Авторизационен код на БОРИКА, само при плащане с карта

Известие за плащане

STAN и BCODE са със стойност 000000, когато плащането не е извършено от карта.

Плащане през ePay.bg

Платените от клиенти суми постъпват по посочена от търговеца банкова сметка в българска банка. Плащането се извършва през ePay.bg.

Описание на процеса

1. Заявка за плащане към търговец.
2. В сайта на търговеца, клиентът избира желаната услуга и като начин на плащане - онлайн чрез ePay.bg.
3. Търговецът изготвя заявка за плащане, който изпраща към URL в ePay.bg като HTTP POST заявка.
4. Клиентът се пренасочва към платежна страница на ePay.bg, като трябва да избере платежно средство и да потвърди плащането със своята парола и друга информация, ако се изисква.
5. При плащане, ePay.bg изпраща нотификация до клиента и генерира банков превод с данните от заявката.
6. ePay.bg следи за статуса на регистрираните/записаните чакащи задължения и при плащане, отказване или изтичане на времето за плащане, изпраща известие към търговеца за статуса на всяко плащане. Известията от системата се изпращат на портове:
   • 80 за HTTP
   • 443 за HTTPS
7. При получаване на известие от ePay.bg, търговецът трябва да формира съответен отговор.

Комуникационна схема

Продукционна среда

Метод	URL
POST	https://www.epay.bg/

Заявка за плащане

Параметър	Тип	Описание	Опционалност
PAGE	string	paylogin	Задължителен
MERCHANT	string	Получател на превода Приемат се: кирилица, латиница, цифри, интервали, тирета, запетаи, точки	Задължителен
IBAN	string	Валиден IBAN на получателя	Задължителен
BIC	string	BIC на банката получател	Задължителен
TOTAL	float	Валидна сума > 0.01 (например: 22, 22.8, 22.80)	Задължителен
STATEMENT	string	Основание Приемат се: кирилица, латиница, цифри, интервали, тирета, запетаи, точки	Задължителен
PSTATEMENT	int	Валиден вид плащане - 6 цифри	Опционален
URL_OK	url	URL, на който клиента да бъде препратен в случай, че потвърди плащането. Не гарантира, че плащането е извършено.	Опционален
URL_CANCEL	url	URL, на който клиента да бъде препратен в случай, че откаже плащането.	Опционален

Примерна заявка

<form action="https://www.epay.bg/" method=post>
<input type=hidden name=PAGE value="paylogin">
<input type=hidden name=MERCHANT value="[MERCHANT]">
<input type=hidden name=IBAN value="[IBAN]">
<input type=hidden name=BIC value="[BIC]">
<input type=hidden name=AMOUNT value="[AMOUNT]">
<input type=hidden name=STATEMENT value="[STATEMENT]">
<input type=hidden name=PSTATEMENT value="[PSTATEMENT]">
<input type=hidden name=URL_OK value="http://...">
<input type=hidden name=URL_CANCEL value="http://...">
<input type=submit>
</form>

Известие за плащане

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