ePay.bg <office@epay.bg>, <epay2_demo@epay.bg> ______________________________________________________________________
Пакетът се състои от следните файлове:
- примерна заявка за плащане написана на Perl
- примерна заявка за плащане написана на PHP
- пример за получаване на известие относно регистрирано искане за плащане (Платено или Отказано) написан на Perl
- пример за получаване на известие относно регистрирано искане за плащане (Платено или Отказано) написан на PHP
- примерна заявка за Свободен превод към регистриран потребител/търговец
- примерна заявка за Вносна бележка
______________________________________________________________________
Схема:
Клиент на WEB търговец прави поръчка в електронния му магазин
След като е готов с поръчката, клиентът формира искане да плати
Търговецът изготвя пакет - заявка за плащане и препраща клиента към ePay.bg системата, като подава по описания по-долу начин заявката за плащане
След успешен вход на клиента в ePay.bg системата, заявката за плащане (ако е коректно подадена) се регистрира/записва като чакащо задължение към дадения търговец. Ако клиентът се откаже без да прави вход или не направи успешен такъв в ePay.bg, заявката за плащане НЕ се записва в системата
Клиентът може да плати задължението или да го остави за по-късно
ePay.bg системата следи за статуса на регистрираните/записаните чакащи задължения и при плащане, отказване или изтичане се изпраща известие на търговеца за тях
При получаване на известие от ePay.bg, търговецът трябва да формира съответен отговор
Търговец --[ЗАЯВКА ЗА ПЛАЩАНЕ]--> ePay.bg Клиент --[ВХОД]--[ЗАПИС НА ЗАЯВКАТА]--> ePay.bg ePay.bg --[ИЗВЕСТИЕ]--> Търговец Търговец --[ОТГОВОР НА ИЗВЕСТИЕ]--> ePay.bg
Всеки регистриран в системата търговец има генерирани буквено-цифрена секретна дума с дължина 64 и идентификационен номер (КИН). Търговецът може да ги види в личните си данни без да може да ги променя.
A. Заявката за плащане се изпраща като HTTP POST заявка към https://www.epay.bg/
Пример:
<form action="https://www.epay.bg/" method=post> <input type=hidden name=PAGE value="paylogin"> <input type=hidden name=ENCODED value="[ENCODED]"> <input type=hidden name=CHECKSUM value="[CHECKSUM]"> <input type=hidden name=URL_OK value="http://..."> <input type=hidden name=URL_CANCEL value="http://..."> <input type=submit> </form>
(*) Ако се използва ePay.bg DEMO системата на адрес: https://demo.epay.bg/, то ТЕСТОВИТЕ заявки за плащане се изпращат към него!!!
Задължителните полета са: PAGE, ENCODED и CHECKSUM, като стойността на PAGE задължително е ``paylogin''.
Полетата URL_OK и URL_CANCEL са опционални:
URL_OK - URL на което клиента да бъде препратен в случай, че потвърди плащането (не гарантира, че плащането е извършено) URL_CANCEL - URL на което клиента да бъде препратен в случай, че откаже плащането за момента (може да го плати или откаже по-късно, но не след указаната дата от търговеца)
Подписване на заявката за плащане
ENCODED - кодирана с base64 (RFC 3548) заявка за плащане, EOL='' CHECKSUM - контролна сума върху ENCODED, генерирана като HMAC с алгоритъм SHA-1 и секретната дума на търговеца.
Perl примерен код: {
# Кодиране на заявката $ENCODED = encode_base64('DATA', ''); # '' за EOL (def. е "\n")
# Генериране на контролна сума $CHECKSUM = hmac_hex($ENCODED, $secret, \&sha1);
}
PHP примерен код: {
# Кодиране на заявката $ENCODED = base64_encode('DATA');
# Генериране на контролна сума $CHECKSUM = hmac('sha1', $ENCODED, $secret); # кода на функцията hmac може да видите в demo.php
}
Примерна заявка за плащане:
MIN=1000000000 (зад. MIN или EMAIL Идентификационен номер на търговеца) EMAIL=a@merch.bg (зад. MIN или EMAIL E-mail на търговеца в системата) INVOICE=123456 (задължително Номер фактура) AMOUNT=22.80 (задължително Сума) CURRENCY=BGN (опционално Валута - BGN, USD или EUR) EXP_TIME=01.08.2020 (задължително Крайна дата/час за плащане) DESCR=Test (опционално Описание до 100 символа) ENCODING=utf-8 (опционално encoding на DESCR параметъра)
(*) в заявката се подава MIN или EMAIL за идентифициране на търговеца
Допълнителни опции: ------------------- a) отстъпки при плащане с определени карти DISCOUNT=cardbin1,cardbin2,cardbin3:amount1 DISCOUNT=cardbin4,cardbin5,cardbin6:amount2
Не е задължитено да са подредени точно в този ред.
MIN - съответсва на КИН в личните данни на търговеца EMAIL - e-mail на търговеца, с който той е регистриран INVOICE - само цифри AMOUNT - валидна сума > 0.01 ( например: 22, 22.8, 22.80 ) CURRENCY - приемани валути са BGN, USD или EUR; ако не бъде подадено е BGN по подразбиране DESCR - CP1251 символи, ако не е подаден друг ENCODING ENCODING - приема се само utf-8; може да се подаде и като HTTP параметър
За полето EXP_TIME е валиден следния формат:
EXP_TIME=DD.MM.YYYY[ hh:mm[:ss]] EXP_TIME=01.08.2020 EXP_TIME=01.08.2020 23:15 (може да се подаде и с час:мин) EXP_TIME=01.08.2020 23:15:30 (може да се подаде и с час:мин:сек)
След като заявката за плащане е регистрирана за клиента, то системата ще извести търговеца за състоянието на плащането: 'Платено', 'Отказано' или 'Изтекло'.Ако клиентът не потвърди или откаже искането преди подадената крайна дата, то ще се маркира като изтекло.
Заявка с даден INVOICE може да влезе в системата ЕДИН единствен път и чака за 'потвърждаване' или 'отказване' от клиента.
B. Известието на системата се изпраща на зададено от търговеца URL като HTTP POST заявка, на която търговеца връща отговор в същата HTTP сесия.
Подписване на известието за плащане
ENCODED - кодирано с base64 (RFC 3548) известие, EOL='' CHECKSUM - контролна сума върху ENCODED, генерирана като HMAC с алгоритъм SHA-1 и секретната дума на търговеца.
Perl примерен код: {
$data = decode_base64($ENCODED); # Калкулиране на контролната сума # Трябва $CHECKSUM_CALC == $CHECKSUM $CHECKSUM_CALC = hmac_hex($ENCODED, $secret, \&sha1);
}
PHP примерен код: {
$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=DENIED INVOICE=123457:STATUS=EXPIRED
(*) ако плащането е с ползване на отстъпка (пимерно с БИН на карта cardbin2 - сума amount1), то известието ще бъде: INVOICE=123456:STATUS=PAID:PAY_TIME=YYYYMMDDhhmmss:STAN=[6 числа]:BCODE=[6 числа/букви]:AMOUNT=amount1:BIN=cardbin2 STATUS=[PAID | DENIED | EXPIRED] - Платено | Отказано | Изтекло PAY_TIME - Дата/час/сек на плащането STAN - Номер транзакция BCODE - Авторизационен код на БОРИКА AMOUNT - Платена сума, подава се САМО при отстъпка BIN - БИН на карта, подава се САМО при отстъпка
За всеки номер на фактура в известието, търговеца трябва да върне статус: OK - ако всичко е наред ERR - за грешка NO - ако не знае за тази фактура При връщане на OK или NO системета спира да изпраща известие за съответната фактура.
Примерен отговор на търговеца:
INVOICE=123456:STATUS=OK INVOICE=123457:STATUS=ERR INVOICE=123458:STATUS=NO
Ако нещо не е коректно в известието изпратено от ePay.bg системата търговецът връща ERR=описание.
Пример:
ERR=описание за глобалната грешка (примерно невярна CHECKSUM)
Ако търговецът не е заявил URL, на което да получава известия за плащанията, не иска или няма възможност да обработва тези известия, то търговецът може да си вижда статуса на исканията за плащане в ePay.bg системата.
Ако ePay.bg не маркира дадена фактура като получена от търговеца (примерно върнат статус ERR или пропаднала комуникация) системата ще се опита да изпрати пропадналите известия отново.
Схема за изпращане на известия по дадена фактура:
1) 5 опита през < 1 минута 2) 4 опита през 15 минути 3) 5 опита през 1 час 4) 6 опита през 3 часа 5) 4 опита през 6 часа 6) 1 опит на ден
Системата спира да изпраща известие за дадена фактура, ако то не бъде получено от търговеца в продължение на 30 дена.
______________________________________________________________________
Схемата е еднаква като при ``(I) Заявка за плащане от WEB търговец, с тази разлика, че PAGE=credit_paydirect.
Пример:
<form action="https://www.epay.bg/" method=post> <input type=hidden name=PAGE value="credit_paydirect"> <input type=hidden name=LANG value="[LANG]"> <input type=hidden name=ENCODED value="[ENCODED]"> <input type=hidden name=CHECKSUM value="[CHECKSUM]"> <input type=hidden name=URL_OK value="http://..."> <input type=hidden name=URL_CANCEL value="http://..."> <input type=submit> </form>
LANG = bg | en
(*) Ако се използва ePay.bg DEMO системата на адрес: https://demo.epay.bg/, то ТЕСТОВИТЕ заявки за плащане се изпращат към него!!!
______________________________________________________________________
Платената сума от клиента постъпва по Микросметка на получателя. Необходимо е клиента и получателя на плащането да са регистрирани в ePay.bg
Заявката за ``Свободен превод'' се изпраща като HTTP POST заявка към https://www.epay.bg/
Пример:
<form action="https://www.epay.bg/" method=post> <input type=hidden name=PAGE value="paylogin"> <input type=hidden name=MIN value="[MIN]"> <input type=hidden name=INVOICE value="[INVOICE]"> <input type=hidden name=TOTAL value="[TOTAL]"> <input type=hidden name=DESCR value="[DESCR]"> <input type=hidden name=ENCODING value="[ENCODING]"> <input type=hidden name=URL_OK value="http://..."> <input type=hidden name=URL_CANCEL value="http://..."> <input type=submit> </form>
Задължително стойността на PAGE е ``paylogin''.
MIN (задължително Идентификационен номер в ePay.bg) INVOICE (опционално Номер фактура) TOTAL (задължително Сума) DESCR (опционално Описание до 100 символа) ENCODING (опционално encoding на DESCR параметъра)
MIN - само цифри ( съответсва на КИН в личните данни на получателя ) INVOICE - само цифри TOTAL - валидна сума > 0.01 ( например: 22, 22.8, 22.80 ) DESCR - CP1251 символи, ако не е подаден друг ENCODING ENCODING - приема се само utf-8
Еквивалентно на TOTAL се приема и AMOUNT.
Схема:
Наредител --[ЗАЯВКА СВОБОДЕН ПРЕВОД]--> ePay.bg Клиент --[ВХОД]--[ЗАПИС НА ЗАЯВКАТА]--> ePay.bg
Полетата URL_OK и URL_CANCEL са опционални:
URL_OK - URL на което клиента да бъде препратен в случай, че потвърди плащането (не гарантира, че плащането е извършено) URL_CANCEL - URL на което клиента да бъде препратен в случай, че откаже плащането
При тази схема на плащане няма подписване на завките и изпращане на известия към търговеца за статуса на плащането.
______________________________________________________________________
Платените суми от клиенти на ePay.bg постъпват по посочена от търговеца банкова сметка
Заявката за ``Вносна бележка'' се изпраща като HTTP POST заявка към https://www.epay.bg/
Пример:
<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=TOTAL value="[TOTAL]"> <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>
Задължително стойността на PAGE е ``paylogin''.
MERCHANT (задължително Получател на превода) IBAN (задължително IBAN на получателя) BIC (задължително BIC на банката получател) TOTAL (задължително Сума) STATEMENT (задължително Основание) PSTATEMENT (ако е нужно Вид плащане)
MERCHANT - кирилица, латиница, цифри, интервали, '-', ',', '.' IBAN - валиден IBAN на получателя BIC - валиден BIC на банката получател TOTAL - валидна сума > 0.01 ( например: 22, 22.8, 22.80 ) STATEMENT - кирилица, латиница, цифри, интервали, '-', ',', '.' PSTATEMENT - 6 цифри, валиден вид плащане
Схема:
Наредител --[ЗАЯВКА ВНОСНА БЕЛЕЖКА]--> ePay.bg Клиент --[ВХОД]--[ЗАПИС НА ЗАЯВКАТА]--> ePay.bg
Полетата URL_OK и URL_CANCEL са опционални:
URL_OK - URL на което клиента да бъде препратен в случай, че потвърди плащането (не гарантира, че плащането е извършено) URL_CANCEL - URL на което клиента да бъде препратен в случай, че откаже плащането
______________________________________________________________________
КРАЙ