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

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

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

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

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

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

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

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

  1. Търговецът изпраща HTTP GET заявка за паричен превод към даденото URL.
  2. ePay.bg получава, изпълнява заявката и в същата HTTP сесия връща към търговеца "Системен код", с който преводът е постъпил в регистрацията на получателя в 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 на получателя. Ако се подава личен документ, се изисква и датата на издаването му.

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

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

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

1
2
3
4
5
6
7
8
{
    # Кодиране на заявката
    $ENCODED  = base64_encode('DATA');

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

Отговор

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

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

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

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

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

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

Грешки

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

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

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

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