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

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

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

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

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

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

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

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

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

moneysend epay

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

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

Демо среда¶

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

Заявка за паричен превод през ePay.bg¶

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

Параметри в ENCODED

Параметър	Тип	Описание	Опционалност
MIN	int	Клиентски идентификационен номер (КИН) на търговеца	Задължителен
MEMAIL	string	Електронна поща на търговеца в системата	Задължителен
CIN	int	Клиентски идентификационен номер (КИН) на получателя	Задължителен
CEMAIL	string	Електронна поща на получателя в системата	Задължителен
INVOICE	string	Номер на фактура; уникален за търговеца	Задължителен
AMOUNT	float	Валидна сума > 0.01 (например: 22, 22.8, 22.80)	Задължителен
CURRENCY	string	Приемани валути са `BGN`, `USD` или `EUR`; ако не се подаде е `BGN` по подразбиране	Опционален
DESCR	string	Описание на превода до 100 символа	Опционален
ENCODING	encoding	encoding на `DESCR`	Опционален

Важно

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

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

В заявката трябва да фигурира MIN/MEMAIL и CIN/CEMAIL на получателя. Ако се подава личен документ, се изисква и датата на издаването му.

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

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
}

Отговор

OKERR

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

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

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

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

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

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

Грешки¶

Не е намерен валиден клиент получател¶

Ако се прави превод едновременно по два идентификатора, но единият от тях не е верен, ще върне грешка: ERR=EMETHOD: Не е намерен валиден клиент получател!

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

имейлът е валиден, но КИН не е
КИН е валиден, но имейлът не е
имейлът е валиден и КИН е валиден, но са асоциирани с различни акаунти