Обмен на пакетни съобщения чрез HTTP GET

Важно

Задължително е използването на HTTPS и TLS 1.2

Типове методи

Метод	Описание	Примерен URL на заявката
GET /pay/init	Проверка за задължение	https://example.com/pay/init
GET /pay/confirm	Нотификация за плащане	https://example.com/pay/confirm

Бележка

Всички примерни заявки ще бъдат кодирани със SECRET: 3EA1ABD845C3D684

Видове параметри

Параметър	Тип данни	Описание	Допълнение
IDN	varchar(64)n	Идентификатор на клиента	Предоставя се от търговеца
MERCHANTID	varchar(8)n	Идентификатор на търговеца	Предоставя се от Оператора
INVOICE	varchar(64)ans	Номер на фактура	При разделно плащане на задължения
INVOICES	varchar(490)ans	Масив от номера на фактури	При разделно плащане на задължения
SHORTDESC	varchar(40)Ans	Кратко описание на задължението	Един ред, кодирано в UTF-8
LONGDESC	varchar(4000)Ans	Подробно описание на задължението	Повече от един ред, кодирано в UTF-8
AMOUNT	int	Сума в стотинки	Изходящ параметър при проверка
VALIDTO	varchar(8)n	Дата, към която е задължението	YYYYMMDD
STATUS	varchar(3)n	Статус код на задължението	Резултат или код на грешката
TID	varchar(26)n	Идентификатор на трансакцията	DATE(14)n + STAN(6)n + AID(6)n
DATE	varchar(14)n	Дата на изпълнение на заявката	YYYYMMDDhhmmss
TOTAL	int	Сума в стотинки	Входящ параметър при плащане
TYPE	varchar(7)a	CHECK, BILLING, PARTIAL, DEPOSIT	В зависимост от типа заявка
CHECKSUM	HEX	На входящите данни, сортирани по ключ	IDNxxxx\nMERCHANTIDxxxx\n

Допълнителна информация

LONGDESC:

Подробно описание на задължението. Желателно е да се подава релевантна информация за клиента - период на услуга, тип услуга, адрес, име, друго. Подава се на един ред, като пренасянето се кодира с \\n на всеки 110 символа. Може да съдържа следните замествания:

• \\t - осем интервала
• \\$ - осем тирета
• \\n - пренасяне на нов ред

INVOICE:

Фактурите са частен термин за протокола, те не са обвързани с реални юридически данни. Служат за разграничаване на натрупани повече от едно или различни задължения на даден клиент. Всяко отделно задължение на този клиент има уникална за него фактура.

TID:

Уникален за всяка отделна трансакция идентификатор. При проблем с дадена трансакция е възможно Операторът да изпраща повече от едно повторение до получаване на коректен отговор от търговеца. Повторението винаги е със същия. TID се формира от:

• DATE - дата и час, с точност до секунда. Времето може да е от 00:00:00 до 23:59:59;
• STAN - сервизна информация на Оператора - не се обработва;
• AID - източник на плащането. Разделят се на два типа - 70002x и 7001xx са касови плащания от Изипей. Всички останали източници може да се приемат за електронни канали на ePay.bg

CHECKSUM:

hmac_sha1_hex (request_data, SECRET)

• request_data - включва всички входящи данни, конкатенирани с NEWLINE (\\n) редове, съдържащи параметър и съответната му стойност, слепени. Данните се сортират по възходящ ред;
• SECRET - предоставя се от Оператора.

TYPE:

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

• CHECK - само проверка за задължение, плащане няма да последва;
• BILLING - при проверка или плащане на задължение;
• PARTIAL - при нотификация за частично плащане на задължение;
• DEPOSIT - при предплащане на услуга.

Списък STATUS кодове

STATUS	Описание	Метод, при който може да се върне
00	ОК	pay_init и pay_confirm
13	Невалидна сума (при депозит)	pay_init
14	Невалиден абонатен номер (IDN)	pay_init
62	Няма задължение	pay_init
80	Временно не може да бъде изпълнена	pay_init
93	Невалидна чексума (CHECKSUM)	pay_init и pay_confirm
94	Повторение на вече получена нотификация	pay_confirm
96	Обща грешка	pay_init и pay_confirm

При отговор различен от 00 всички параметри освен STATUS се игнорират.

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

Допълнителна информация

96:

Грешка от общ характер. Когато Операторът не е получил отговор от търговеца в предвиденото време от 60 сек, също се интерпретира като 96.
Също така, невалидни или липсващи задължителни полета от изходящите данни. Операторът ще изпраща повторение на нотификацията до получаване на коректен статус от търговеца.

94:

Носи значението на 00. Ако системата на търговеца е приела заявката за плащането и е върнала статус 00, но в нашата система не е получен отговор - тогава по правило източникът трябва да продължи да изпраща същото съобщение, докато не получи коректен отговор. При повторно получаване на същото съобщение търговецът може да върне 94, като това има смисъла на статус 00 - заявката е обработена и повтарянето ѝ може да бъде спряно.

80:

Временно не може да бъде изпълнена - търговецът временно не може да обработва плащания. Обичайно се връща, когато търговецът е спрял временно плащанията поради актуализиране на задълженията на своите клиенти, или друга особеност.

Проверка на задължение

Служи за проверка за актуални задължения на даден клиент, плащане няма да последва. Ако търговецът е разработил разделно плащане по фактури, трябва да върне параметър INVOICES със съответните данни, при наличието на повече от едно задължение. При работа по общо задължение този параметър не се подава.

Важно

Ако при заявка за получаване на задължение с TYPE=BILLING, търговецът е върнал STATUS : 00 и сума по-голяма от 0 в изходящите данни, това е сигнал за Оператора, че плащане може да започне и съответно ще бъде обработено. Търговецът би следвало да може да обработи последвала нотификация за плащане тип pay_confirm. Ако плащане няма да може да бъде извършено, търговецът трябва да върне още на pay_init метода STATUS : 96 или друг релевантен за ситуацията.

GET /pay/init

Входящи данни

Параметър	Описание	Опционалност
IDN	Идентификатор на клиента	Задължителен
MERCHANTID	Идентификатор на търговеца	Задължителен
CHECKSUM	HMAC-SHA-1 HEX на входящите данни, сортирани по ключ	Задължителен
TYPE	Може да съдържа CHECK или BILLING	Задължителен
TID	Полето не фигурира при заявка с параметър TYPE=CHECK	Опционален

Изходящи данни

JSON обект	Описание	Опционалност
STATUS	При отговор различен от 00, всички параметри освен STATUS се игнорират	Задължителен
IDN	Идентификатор на клиента	Задължителен
AMOUNT	Сума в стотинки. При плащане по фактури се подава общата им стойност.	Задължителен
VALIDTO	Дата, към която е актуално задължението	Задължителен
SHORTDESC	Подава се на един ред. Кратка информация за клиента - име, адрес, друга информация	Опционален
LONGDESC	При разделяне по фактури, трябва да се подаде синтезирана информация за всички фактури	Опционален
INVOICES	Ако търговецът не позволява плащане по фактури, не подава това поле	Опционален

Изходящи данни на масив INVOICES (подава се при разработени плащания на отделни задължения-фактури)

Данни в INVOICES	Описание	Опционалност
IDN	Абонатен номер и фактура на конкретното задължение, конкатенирани с точка (IDN.INVOICE)	Задължителен
AMOUNT	Сума за конкретната фактура	Задължителен
VALIDTO	Дата, към която е актуална конкретната фактура	Задължителен
SHORTDESC	Кратко описание за конкретната фактура	Опционален
LONGDESC	Пълно описание за конкретната фактура	Опционален

Всяка отделна фактура се подава в масив от обекти INVOICES с параметрите описани по-горе. Фактурата се формира от абонатния номер на клиента, конкатенирано с точка и номер на фактура (IDN.INVOICE) на конкретното задължение.

Бележка

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

Примери

Заявка

Само проверка, плащане няма да последва:

https://example.com/pay/init?IDN=12345&CHECKSUM=702de02734d25c719c6ccc87526478e851f6271d&MERCHANTID=0000334&TYPE=CHECK

Плащане може да последва:

https://example.com/pay/init?IDN=12345&CHECKSUM=2736e17a183ed4b6923f7e0395b6c0523fdf0404&TID=20170317121650591535700020&MERCHANTID=0000334&TYPE=BILLING

Отговор

При общо задължение:

{
    "STATUS" : "00",
    "IDN" : "12345",
    "SHORTDESC" : "Иван Иванов, Интернет услуга",
    "LONGDESC" : ":клиентски номер: 12345\\nИмена: Иван Иванов\\n
        Интернет услуга 01.03.2017 - 31.03.2017",
    "AMOUNT" : "16600",
    "VALIDTO" : "20170317",
}

С две фактури:

{
    "STATUS" : "00",
    "IDN" : "12345",
    "SHORTDESC" : "Иван Иванов, Интернет услуга",
    "LONGDESC" : "клиентски номер: 12345\\nИмена: Иван Иванов\\n 
    Интернет услуга 01.03.2017 - 30.04.2017",
    "AMOUNT" : "16600",
    "VALIDTO" : "20170317",
    "INVOICES" : [
    {
    "IDN" : "12345.001",
    "SHORTDESC" : "Бизнес инт. - 100 mbps 78 лв.",
    "AMOUNT" : "7800",
    "LONGDESC" : "клиентски номер: 12345\\nИмена: Иван Иванов\\n 
    Интернет услуга 01.03.2017 - 31.03.2017",
    "VALIDTO" : "20170331"
    },
    {
    "IDN" : "12345.002",
    "SHORTDESC" : "Бизнес инт. - 150 mbps 88 лв.",
    "AMOUNT" : "8800",
    "LONGDESC" : "клиентски номер: 12345\\nИмена: Иван Иванов\\n 
    Интернет услуга 31.03.2017 - 30.04.2017",
    "VALIDTO" : "20170430"} ] 
}

Нотификация за плащане

Служи да извести търговеца за извършено от клиент плащане. Нотификацията ще бъде получена само след коректен отговор на заявка за извличане на задължение тип pay_init, в която фигурира поле TID.

При плащане по общо задължение:

• Ако търговецът не е разработил разплащане по фактури и подава само общо задължение, ще получава входящи данни без поле INVOICES.

При плащане по фактури:

• При пълно погасяване на всички фактури търговецът ще получи нотификация без параметър INVOICES. Параметърът TOTAL ще съдържа сумата от всички фактури, подадени от търговеца на pay_init.
• При плащане на по-малък брой от подадените от търговеца на pay_init фактури, Операторът ще изпраща в нотификацията и параметър INVOICES. Стойността му се формира от абонатния номер на клиента, конкатенирано с точка и номер на фактура на конкретното задължение (IDN.INVOICE). При повече от една фактура стойностите са разделят със запетая (IDN.INVOICE,IDN.INVOICE,IDN.INVOICE).

При частично плащане:

• В този случай търговецът ще получи стойност TYPE=PARTIAL и избраната от клиента сума. Възможно е тя да е по-малка от подадената от търговеца на pay_init. Поле INVOICES не фигурира в тази нотификация.

Нотификацията за плащане не може да бъде отказана.

Търговецът ще получава това съобщение през определени интервали от време, докато не отговори със STATUS : 00 или STATUS : 94.

Търговецът трябва да може да обработва няколко съобщения за нотификация. Тоест, той може да получи едно съобщение за нотификация няколко пъти поред, или ако се забави с отговора на първото (над 30 сек), да получи второ, докато обработва първото. При всички случаи трябва да бъде отразено само едно съобщение за плащане, като на останалите трябва да се отговори със статус 00 или 94.

GET /pay/confirm

Входящи данни

Параметър	Описание	Опционалност
IDN	Идентификатор на клиента	Задължителен
MERCHANTID	Идентификатор на търговеца	Задължителен
TID	Идентификатор на трансакцията	Задължителен
DATE	Дата на изпълнение на заявката	Задължителен
TOTAL	Сума в стотинки	Задължителен
TYPE	Може да съдържа BILLING или PARTIAL	Задължителен
INVOICES	IDN.INVOICE - при повече от една фактура, стойностите се изброяват със запетая	Опционален
CHECKSUM	HMAC-SHA-1 HEX на входящите данни, сортирани по ключ	Задължителен

Изходящи данни

JSON обект	Описание
STATUS	Всички параметри, освен STATUS и съответното му предефинирано значение, се игнорират.

Важно

При проблем, настъпил при потвърждаване на трансакция, Операторът автоматично я повтаря до получаване на коректен отговор от търговеца. Идентификаторът, чрез който търговецът може да разбере, че това е повторение, а не ново плащане, е TID - той винаги ще е еднакъв при всяко повторение на конкретната трансакция.

Примери

Заявка

Проверка при пълно погасяване:

https://example.com/pay/confirm?DATE=20170316181226&TYPE=BILLING&MERCHANTID=0000334&IDN=12345&CHECKSUM=823383f09ab489fe172762703f8c047ce4428530&TOTAL=16600&TID=20170317121650591535700020

Проверка при плащане на една фактура:

https://example.com/pay/confirm?DATE=20170316181226&TYPE=BILLING&MERCHANTID=0000334&IDN=12345&TOTAL=7800&CHECKSUM=06c5786385a673bfcc25a10a6d59722769bca25f&TID=20170317121650591535700020&INVOICES=12345.001

Проверка при частично погасяване:

https://example.com/pay/confirm?DATE=20170316181226&TYPE=PARTIAL&MERCHANTID=0000334&IDN=12345&CHECKSUM=70514b288b2167b5bcf6324eaddc1a8179cebd57&TOTAL=100&TID=20170317121650591535700020

Отговор

{

    "STATUS" : "00"

}

Бележка

Всички параметри освен STATUS и съответното му предефинирано значение се игнорират.

Проверка за депозит

Служи за проверка дали за даден клиент може да се извърши депозитна трансакция (предплащане). В заявката фигурира и сума, която търговецът може да валидира или не. Сумата може да е и на предефинирани номинали.

GET /pay/init

Входящи данни

Параметър	Описание	Опционалност
IDN	Идентификатор на клиента	Задължителен
MERCHANTID	Идентификатор на търговеца	Задължителен
CHECKSUM	HMAC-SHA-1 HEX на входящите данни, сортирани по ключ	Задължителен
TYPE	DEPOSIT	Задължителен
TID	Идентификатор на трансакцията	Задължителен
TOTAL	Сума в стотинки	Задължителен

Изходящи данни

JSON обект	Описание	Опционалност
STATUS	Ако стойността на STATUS не е 00, всички останали полета се игнорират	Задължителен
SHORTDESC	Кратко описание. Име, имейл или друго - релевантен за клиента идентификатор	Опционален
LONGDESC	Подробно описание. Подава се на един ред, като пренасянето се кодира с \\n на всеки 110 символа	Опционален

Важно

Ако на заявка за проверка на депозит търговецът е върнал STATUS : 00, това е сигнал за Оператора, че плащане може да започне и съответно ще бъде обработено. Търговецът би следвало да може да обработи последвала нотификация за плащане (метод pay_confirm). Ако плащане няма да може да бъде извършено, търговецът трябва да върне още на pay_init метода STATUS : 96 или друг релевантен за ситуацията.

Примери

Заявка

Проверка за депозит:

https://example.com/pay/init?IDN=12345&MERCHANTID=0000334&CHECKSUM=123c13322543764d4af33d87a4a8dd0965777ed6&TYPE=DEPOSIT&TID=20170317121650591535700020&TOTAL=2000

Отговор

{
    "STATUS" : "00",
    "SHORTDESC" : "Име на клиент: Иван Иванов",
    "LONGDESC" : "Предплащане на услуга за 1 месец\\nИме на клиент: Иван Иванов"
}

Нотификация за извършен депозит

Служи да извести търговеца за извършено депозитно плащане.

Нотификацията за плащане не може да бъде отказана.

Търговецът ще получава това съобщение през определени интервали от време, докато не отговори със STATUS : 00 или STATUS : 94.

GET /pay/confirm

Входящи данни

Параметър	Описание	Опционалност
IDN	Идентификатор на клиента	Задължителен
MERCHANTID	Идентификатор на търговеца	Задължителен
TID	Идентификатор на трансакцията	Задължителен
DATE	Дата на изпълнение на заявката	Задължителен
CHECKSUM	HMAC-SHA-1 HEX на входящите данни, сортирани по ключ	Задължителен
TYPE	DEPOSIT	Задължителен
TOTAL	Сума в стотинки	Задължителен

Изходящи данни

JSON обект	Описание
STATUS	Всички параметри, освен STATUS и съответното му предефинирано значение, се игнорират.

Примери

Заявка

Плащане на депозит:

https://example.com/pay/confirm?DATE=20170317121950&IDN=12345&MERCHANTID=0000334&CHECKSUM=123c13322543764d4af33d87a4a8dd0965777ed6&TYPE=DEPOSIT&TID=20170317121850591535700020&TOTAL=2000

Отговор

{
    "STATUS" : "00"
}

Генериране на CHECKSUM

CHECKSUM = hmac_sha1_hex (request_data, SECRET)

Бележка

request_data трябва да включва всички входящи данни.

Пример за стойността на request_data, сортирана по възходящ ред, преди да бъде кодирана. На последния ред също фигурира символ newline \\n:

IDN12345  
MERCHANTID0000334  
TID20170317121650591535700020  
TYPEBILLING