Към съдържанието

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

Известието за плащане трябва да се реализира като последна стъпка към:

След като заявката за плащане е регистрирана за клиента, то системата ще извести търговеца за състоянието на плащането: "Платено" или "Изтекло". Ако Клиентът не потвърди искането преди подадената крайна дата, то ще се маркира като изтекло.

Заявка с даден INVOICE може да влезе в системата само един път и чака за "Потвърждаване" от клиента.

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

Нотификациите се изпращат към адреси с порт 80 (HTTP) или 443 (HTTPS).

Инфо

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

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

За да заявите URL за известяване, изпратете имейл до Търговски отдел - merchant@epay.bg, в който се съдържат вашият КИН и URL за нотификация.

Демо среда

В Демо среда, търговецът сам може да зададе адрес за нотифициране.

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

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

Параметри в ENCODED

Параметър Тип Описание Опционалност
INVOICE string Номер на фактура от заявката за плащане Задължителен
STATUS string Статус на плащането;
PAID, DENIED, EXPIRED		 Задължителен
PAY_TIME datetime Дата/час/сек на плащането;
формат YYYYMMDDhhmmss		 Задължителен
(когато е платена)
STAN int Номер на транзакция; [6 цифри] Задължителен
(когато е платена)
BCODE string Авторизационен код на БОРИКА; [6 цифри/букви] Задължителен
(когато е платена)		 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    $data = decode_base64($ENCODED);

    # Калкулиране на контролната сума
    # Трябва $CHECKSUM_CALC == $CHECKSUM
    $CHECKSUM_CALC = hmac_hex($ENCODED, $secret, \&sha1);

    # Проверка на цифровият подпис
    use Crypt::OpenSSL::RSA;
    $rsa_pub = Crypt::OpenSSL::RSA->new_public_key(EPAY_PUBLIC_KEY_DATA);
    $rsa_pub->verify($ENCODED, $SIGNATURE);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    $data = base64_decode($ENCODED);

    # Калкулиране на контролната сума
    # Трябва $CHECKSUM_CALC == $CHECKSUM
    $CHECKSUM_CALC = hmac('sha1', $ENCODED, $secret);

    # кода на функцията hmac може да видите в demo.php

    # Проверка на цифровия подпис
    $pkey_obj = openssl_get_publickey($EPAY_CERT_DATA);
    openssl_verify($ENCODED, $SIGNATURE, $pkey_obj);
}

Примери

Известие за извършено плащане

Кодирани данни:

  • encoded=SU5WT0lDRT0xNDAyOlNUQVRVUz1QQUlEOlBBWV9USU1FPTIwMjIwNjI5MTQ1MjU3OlNUQU49MDAwMDAwOkJDT0RFPTAwMDAwMAo%3D&checksum=46703be53c26149b0f28bcb1a38d1f8fdbb096de

След декодиране на данните се получава текстът, от който може да се видят параметрите, които пращаме:

  • INVOICE=1402:STATUS=PAID:PAY_TIME=20220629145257:STAN=000000:BCODE=000000

Известие с повече от един INVOICE в една заявка

Има случаи, в които системата изпраща повече от един INVOICE в една заявка:

  • INVOICE=162319945:STATUS=PAID:PAY_TIME=20230626002551:STAN=036221:BCODE=036221 INVOICE=162322355:STATUS=PAID:PAY_TIME=20230626002551:STAN=036227:BCODE=036227

Известие за изтекло време

Кодирани данни:

  • encoded=SU5WT0lDRT02MTY1NjQyOTc2MzpTVEFUVVM9RVhQSVJFRAo%3D&checksum=2cf0b859969c55c1ed2d16fcc4446d7455305010

След декодиране на параметър encoded се вижда текстът, който съдържа тази нотификация:

  • INVOICE=61656429763:STATUS=EXPIRED

Други декодирани стойности на encoded

INVOICE=123456:STATUS=PAID:PAY_TIME=YYYYMMDDhhmmss:STAN=[6 цифри]:BCODE=[6 цифри/букви]

INVOICE=123457:STATUS=DENIED

INVOICE=123457:STATUS=EXPIRED

Отговор на известие за плащане

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

Параметър Тип Описание Опционалност
INVOICE string Номер на фактурата от заявката за плащане Задължителен
STATUS string OK - успешно приета нотификация
ERR - описание на грешката
NO - несъществуващ номер на фактура		 Задължителен

Инфо

При връщане на STATUS = OK или STATUS = NO, системата спира да изпраща известие за съответната фактура.

Системата изпраща известия в продължение на 14 дни.

Примери

INVOICE=123456:STATUS=OK

INVOICE=123457:STATUS=ERR

INVOICE=123458:STATUS=NO

Като отговор на нотификацията, търговеца може да върне отговор STATUS=ERR, ако желае да доведе до повторение на същата нотификация.

ERR=описание за глобалната грешка (например невярна CHECKSUM)

Time-out за известия

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

Схема за изпращане на известия по дадена фактура:

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