Изплащане на паричен превод от търговец към клиент през каса на EasyPay¶

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

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

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

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

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

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

Търговецът изпраща HTTP GET заявка за паричен превод към даденото URL.
В същата HTTP сесия ePay.bg ще върне на търговеца "Системен код".
Паричният превод се изплаща на подадения получател във всяка една от касите на EasyPay.
ePay.bg системата следи за статуса на регистрираните/записаните парични преводи и при изплащането им се изпраща нотификация от ePay.bg на търговеца за тях.
При получаване на нотификация от ePay.bg, търговецът трябва да формира съответен отговор.

Заявка за паричен превод през EasyPay¶

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

moneysend-process

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

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

Демо среда

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

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

Параметри в ENCODED

Параметър	Тип	Описание	Опционалност
MIN	int	Клиентски идентификационен номер (КИН)	Задължителен
INVOICE	int	Идентификатор на заявката; само цифри	Задължителен
AMOUNT	float	Валидна сума > 0.01 (например: 22, 22.8, 22.80)	Задължителен
RCPT_NAME	string	Име на получателя до 100 символа; CP1251 символи, ако не е подаден друг `ENCODING`	Задължителен
RCPT_PID	int	ЕГН на получателя	Задължителен
RCPT_ID_NO	int	Номер на личен документ на получателя (лична карта/шоф.книжка/паспорт)	Задължителен
RCPT_ID_DATE	date	Дата на издаване на личен документ на получателя (лична карта/шоф.книжка/паспорт); формат `DD.MM.YYYY`	Задължителен
RCPT_ADDRESS	string	Адрес на получателя до 256 символа; CP1251 символи, ако не е подаден друг `ENCODING`	Опционален
RCPT_PHONE	int	Телефон на получателя до 16 символа	Опционален
CURRENCY	float	Приемани валути са `BGN`, `USD` или `EUR`; ако не се подаде е `BGN` по подразбиране	Опционален
DESCR	string	Основание за превода до 100 символа; CP1251 символи, ако не е подаден друг `ENCODING`	Опционален
ENCODING	encoding	utf-8 или CP1251; ако не се подаде, по подразбиране се приема CP1251	Опционален

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

INVOICE:

Служи за разграничаване на различните заявки на търговеца. Този идентификатор трябва да е уникален за всяка нова заявка

ENCODING:

Ако не е подаден този параметър, системата по подразбиране очаква CP1251 символи във всички описателни полета (DESCR, RCPT_NAME, RCPT_ADDRESS). За UTF-8 символи в описателните полета се подава ENCODING=utf-8.

Задължително се подават данните на получателя в заявката

В заявката трябва да фигурира ЕГН и/или номер на валиден личен идентификационен документ на получателя. Ако се подава личен документ, се изисква и датата на издаването му.

Отговор¶

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

OKERR

SYS_CODE = 1234567890 (системен код - само цифри, до 64 дължина)

ERR = Описание на грешка

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

Липсата на отговор или такъв с празна стойност не трябва да е флаг, че заявката за генериране на превод не е била или е била успешна.

Търговецът трябва да повтаря заявката със същите данни, до получаване на отговор по спецификация (SYS_CODE=123 или ERR=Описание на грешка). Всяко повторение на заявка с едни и същи данни ще води до един и същ системен код, което означава че повтаряне на заявката няма да доведе до нареждането на още един превод.

Нотификация от ePay.bg¶

При изплащане на превода известието от системата се изпраща на зададено URL като HTTP POST заявка, на която търговецът връща отговор в същата HTTP сесия.

Търговецът задължително трябва да има зададен URL адрес за нотификация от ePay.bg, ако желае да бъде известяван за успешни изплащания. Ако няма зададен URL адрес, то търговецът ще може да вижда единствено статуса на паричните преводи по Миркосметката си - депозити от клиенти по 10-цифрени кодове.

В адреса за нотификации са позволени единствено стандартните портове:

80 за HTTP
443 за HTTPS

Адресът може да изглежда по следният начин:

Отговор от търговеца след нотификация от ePay.bg

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

Схема за изпращане на нотификации по даден INVOICE

5 опита през < 1 минута
4 опита през 15 минути
5 опита през 1 час
6 опита през 3 часа
4 опита през 6 часа
1 опит на ден

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

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

Параметри в ENCODED

Параметър	Описание
INVOICE	Идентификатор на заявката
STATUS	`PAID`
PAY_TIME	Дата на изплащането; формат `YYYYMMDDhhmmss`
STAN	Номер на трансакцията; винаги е `000000`
BCODE	Авторизационен код на БОРИКА; винаги е `000000`

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

encoded=SU5WT0lDRT0xMjM0NTY6U1RBVFVTPVBBSUQ6UEFZX1RJTUU9MjAxNzA3MTUxMzUxMjM6U1RBTj0wMDAwMDA6QkN
PREU9MDAwMDAw&checksum=a2468791e7a999d616f1d92f266346801ed8e82a

Пример за декодирана стойност на encoded

INVOICE=123456:STATUS=PAID:PAY_TIME=20170715135123:STAN=000000:BCODE=000000

Отговор на нотификация¶

В обичайната ситуация се очаква търговецът да върне отговор STATUS=ОК, при което системата преустановява последващото изпращане на съответното известие. С изпращане на този статус търговецът потвърждава на ePay.bg, че нотификацията е била успешно обработена.

Изходящи параметри

Параметър	Описание
INVOICE	Идентификатор на заявката
STATUS	`OK`, `NO` или `ERR`

Възможни стойности на полето STATUS

Параметър	Описание
OK	Съобщението е коректно обработено
ERR	Връща се при грешка от страна на търговеца, поради която не е успял коректно да запише нотификацията
NO	Няма такава заявка, генерирана от търговеца (`INVOICE`)

Допълнителна информация за STATUS стойностите

ERR:

Ако нещо не е коректно в известието, изпратено от ePay.bg, системата на търговеца връща ERR=описание. Например, може да се върне при невалидна чексума - ERR=INVALID CHECKSUM. При получаване на ERR, ePay.bg ще продължи да повтаря нотификацията по описаната схема.

NO:

При получаване на този статус системата на ePay.bg преустановява изпращането на нотификации за този INVOICE.

Примери¶

Кодиране на заявка за превод от търговец към ePay.bg

PerlPHP

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

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

{
    # Кодиране на заявката
    $ENCODED = base64_encode('DATA');

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

Съдържанието на ENCODED, преди да бъде кодирано

MIN=1000000000
INVOICE=123456
AMOUNT=22.80
DESCR=Паричен превод
ENCODING=utf-8
RCPT_NAME=Иван Иванов
RCPT_PID=1111111110
RCPT_ID_NO=1111111111
RCPT_ID_DATE=14.02.2024
RCPT_ADDRESS=София, ул. Иван Вазов 16
RCPT_PHONE=029210850

Известие от ePay.bg за изплатен превод

encoded=SU5WT0lDRT0xMjM0NTY6U1RBVFVTPVBBSUQ6UEFZX1RJTUU9MjAxNzA3MTUxMzUxMjM6U1RBTj0wMDAwMDA6QkN
PREU9MDAwMDAw&checksum=a2468791e7a999d616f1d92f266346801ed8e82a

Отговор на известието от ePay.bg

INVOICE=123456:STATUS=OK

Отмяна на нареден паричен превод¶

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

moneysend_reverse

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

Метод	WEB_ADRESS
GET	https://www.epay.bg/v3main

Демо среда

Метод	WEB_ADDRESS
GET	https://demo.epay.bg/xdev/web

Заявка за отмяна на нареден паричен превод¶

Заявката НЕ отговаря дали е сторнирано успешно, а само че ще направи опит за сторниране. За да разберете дали процесът е преминал успешно, трябва да изпратите заявка за проверка на статуса на отмяната.

Метод	Адрес
GET	WEB_ADDRESS/payment/cancel

Заявката за отмяна се изпраща с параметри ENCODED и CHECKSUM:

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

Параметри в ENCODED

Параметър	Тип	Описание	Опционалност
MIN	int	Клиентски идентификационен номер (КИН)	Задължителен
INVOICE	string	Номер на фактура; уникален за търговеца	Задължителен
AMOUNT	float	Валидна сума > 0.01 (например: 22, 22.8, 22.80)	Задължителен
REV_ID	int	Произволна уникална стойност, служеща за идентификатор	Задължителен

Отговор

OKPROCESSINGERR

STATUS=OK

STATUS=PROCESSING

STATUS=ERR
ERR=съобщение за грешка

До кога трябва да повтарям заявката?

Получаване на коректен статус PROCESSING/OK означава, че заявката е приета и системата ще опита да сторнира плащането.
Получаване на статус ERR означава, че има проблем при подаване на заявката и тя не е приета от системата, което налага повтарянето й отново.

Заявката трябва да се повтаря докато не получите отговор PROCESSING или OK.

Заявка за проверка на статуса на отмяната¶

Задължително е пускането на проверка на статуса на отмяна на паричен превод след отговор OK/PROCESSING на заявка за отмяна на паричен превод.

Метод	Адрес
GET	WEB_ADDRESS/payment/cancel/state

Заявката за проверка на статуса на отмяната се изпраща с параметри ENCODED и CHECKSUM:

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

Параметри в ENCODED

Параметър	Тип	Описание	Опционалност
MIN	int	Клиентски идентификационен номер (КИН)	Задължителен
INVOICE	string	Номер на фактура; уникален за търговеца	Задължителен
AMOUNT	float	Валидна сума > 0.01 (например: 22, 22.8, 22.80)	Задължителен
REV_ID	int	Произволна уникална стойност, служеща за идентификатор	Задължителен

Отговор

OKPROCESSINGDENIEDERR

STATUS=OK

STATUS=PROCESSING

STATUS=DENIED

STATUS=ERR
ERR=съобщение за грешка

Важно

Ако веднъж вече е изпратена заявка за сторниране, която е била успешна и преводът е сторниран, а след това е изпратена нова заявка за сторниране на същия превод, на проверка на статуса ще получите DENIED.

Възможни сценарии¶

На заявка за сторниране на вече изплатен превод в продукционна среда ще получите PROCESSING/OK, а след това на проверката на резултата от сторното ще получите DENIED.

Анулиране на плащания¶

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

Инфо

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

Без значение от подадения период на изтичане на заявката, всеки успешно нареден превод е готов за изплащане на каса до момента, в който бъде анулиран.

Периодите за автоматично анулиране са:

7 дни
14 дни
30 дни

Тестова среда¶

За да симулирате заявки в тестовата среда, е необходимо да се свържете с
отдел Поддръжка Приложения - msupport@datamax.bg.