Плащане през EasyPay

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

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

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

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

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

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

1. Клиент на WEB търговец прави поръчка в електронния му магазин.
2. След като е приключил с поръчката, клиентът избира "Плащане в офис на EasyPay".
3. Търговецът изпраща HTTP GET заявка за плащане към URL на ePay.bg (скрито от клиента)
4. ePay.bg връща на търговеца в същата HTTP сесия 10-цифрен код за плащане в EasyPay.
5. Търговецът показва на своя сайт този код. Това е кодът, с който клиентът да отиде на каса на EasyPay и да извърши плащането.
6. ePay.bg следи за статуса на регистрираните/записаните чакащи задължения и при плащане/отказване на плащането, се изпраща известие на търговеца относно статуса на съответната заявка. Известията от системата се изпращат на портове:
   • 80 за HTTP
   • 443 за HTTPS
7. При получаване на известие от ePay.bg, Търговецът трябва да формира съответен отговор. Ако известието се получи повторно, се повтаря първият върнат отговор.

Info

Плащания с 10-цифрен код могат да се извършват и на EasyPay банкомат.

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

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

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

Демо среда

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

Симулиране на извършено плащане с 10-цифрен код в офис на EasyPay

https://demo.epay.bg/ezp/pay_bill.cgi?ACTION=PAY&IDN=1234567890

Параметър	Тип	Описание	Опционалност
ACTION	PAY	Симулиране на плащане	Задължителен
IDN	int	Полученият код за плащане	Задължителен

На зададения от вас URL за известяване следва да получите STATUS=PAID.

Заявка за плащане

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

Параметри в ENCODED

Параметър	Тип	Описание	Опционалност
MIN	int	Клиентски идентификационен номер (КИН)	Задължителен
EMAIL	string	Електронна поща на търговеца в системата	Опционален
INVOICE	int	Номер на фактура; уникален за търговеца	Задължителен
AMOUNT	float	Валидна сума > 0.01 (например: 22, 22.8, 22.80)	Задължителен
CURRENCY	string	Приемани валути са BGN, USD или EUR; ако не се подаде е BGN по подразбиране	Опционален
EXP_TIME	datetime	Крайна дата/час за плащане; формат DD.MM.YYYY[hh:mm[:ss]]	Задължителен
DESCR	string	Описание до 100 символа; CP1251 символи, ако не е подаден друг ENCODING	Опционален
ENCODING	encoding	encoding на DESCR параметъра; приема се само utf-8, може да се подаде и като HTTP параметър	Опционален

Важно

Предвидете достатъчно време на валидност на заявката EXP_TIME, за да има време клиентът да отиде до каса на EasyPay.

Примерна заявка

# '' за EOL (def. е "\n")
DATA = 
    MIN=1000000000
    EMAIL=a@merch.bg
    INVOICE=123456
    AMOUNT=22.80
    CURRENCY=BGN
    EXP_TIME=01.08.2020
    DESCR=Test
    ENCODING=utf-8

$ENCODED  = encode_base64('DATA');

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

<form action="https://www.epay.bg/" method=post>
    <input type=hidden name=LANG value="[LANG]">
    <input type=hidden name=ENCODED value="[$ENCODED]">
    <input type=hidden name=CHECKSUM value="[$CHECKSUM]">
</form>

Промяна на изтичащо време на 10-цифрен код

Може да променяте expiration_time като направите заявка за Промяна на изтичащото време на 10-цифрен код, с която да удължите времето му на изтичане или да инвалидирате кода.

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

За да получавате в реално време нотификации за статуса на плащанията, трябва да разработите Известие за плащане.