Платежен интерфейс EasyPSD

Настоящата документация е предназначена за банки и финансови организации, които в съответствие с разширената Директива на Европейския съюз относно платежните услуги PSD 2 Directive (EU) 2015/2366 желаят да предложат на клиентите си в своите платформи услуги, свързани с оперираните от Изипей АД платежни сметки. В документа такива организации са обозначени като "Дружества за платежни услуги"(ДПУ).

Всеки доставчик на услуги, получил лиценз за осъществяване на дейност по предоставяне на информация за сметка и/или за иницииране на плащания съгласно Directive (EU) 2015/2366, може да достъпи Портала на Изипей АД за разработчици и да осъществи връзка с разработените от Изипей API интерфейси.

При първоначалното осъществяване на връзка с Портала и осъществяване на връзка с разработените от Изипей API интерфейси Доставчикът се идентифицира чрез валиден сертификат QWAC (PSD2-compliant Qualified Web Authentication Certificate), който е издаден от някой от лицензирани доставчици на удостоверителни услуги (публикувани на EU list of trusted providers).

За да удостовери правото и ролята, за която съответния доставчик притежава лиценз - като Доставчик на услуги по предоставяне на информация за сметка и/или Доставчик на услуги по иницииране на плащане и/или Доставчик на платежни услуги, издаващи платежни инструменти, свързани с карти, Изипей извършва проверка в единен регистър на ЕБО за платежните институции и институциите за електронни пари, достъпен на https://www.eba.europa.eu/risk-analysis-and-data/register-payment-electronic-money-institutions-under-PSD2.

При предоставен валиден сертификат и изпратена заявка за първоначален достъп, ДПУ предоставя на Изипей валиден адрес за обратна връзка - REPLY_URI за WEB приложение и URL Scheme за мобилно приложение за осъществяване на комуникацията за обмен на информация. ДПУ предоставило валиден сертификат за достъп получава таен ключ на приложение и уникален идентификатор (APPID) - параметър, който Доставчикът изпраща в последствие с всяка заявка към сървърите на Изипей за осъществяване на достъп до сметките на клиентите, които са пожелали да ползват тази услуга чрез приложението на другия ДПУ и който се използва от Изипей за идентифициране на Доставчика във връзка с изпълнението на конкретната заявка.

Освен APPID, с всяка заявка ДПУ следва да изпраща и уникален идентификатор на устройството, използвано от потребителя (DEVICEID). За идентификатор на устройството се препоръчва използването на Vendor ID в iOS или ANDROID_ID в Android.

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

Комуникацията със сървърите на Изипей се извършва посредством JSON REST API. Изипей предоставя на Доставчика входни точки за комуникация със сървърите на Изипей при достъп до сметка – за тестова среда и за продукционна среда.

С валиден сертификат QWAC може да се създаде/провери/редактира или премахне профил на Developer на ДПУ.

Преглед:
GET API_BASE_WEB/psd2/app
В резултат се получава JSON, който съдържа данни за приложението: 

{"certdata":{"serial":"26924758290291903361252444186158762848","subject":"Payments AD","validto":"1673690219","digest":"edPx684vhbWNfStWHPgt0BPn27g=","roles":["PSP_AS","PSP_PI","PSP_AI","PSP_IC"]},"app":{"APP.REPLY_URI":"","APP.SCHEME":"aaaaaaaaaaaaaaa","APP.APPID":"0517814436466328370834363951629359940584980052352957477218124635","APP.SECRET":"IYePSsmSFHXlg97fdMNQG5p2awKOmTKdrd8g3kdfwF87jkEh9ecj85IgtvXwbvLu6btywUiwceeO1hekiBfd3kiKuA93n0JddyCEl2bjZRnlsv4hV3IdMJsqUKcmFQ4n"},"status":"OK"}

или 
            {
            "status" : "ERR", 
            "err" : "SOME_ERROR_CODE", 
            "errm" : "Съобщение, което може да покажете на потребителя"
        }

Например: 
        {"err":"NOAPP","errm":"Неуспешна заявка. Моля, свържете се с поддръжка(NOAPP)","status":"ERR","app":null,"certdata":{"subject":"Payments AD","serial":"26924758290291903361252444186158762848","digest":"edPx684vhbWNfStWHPgt0BPn27g=","validto":"1673690219","roles":["PSP_AS","PSP_PI","PSP_AI","PSP_IC"]}}

който показва, че е предоставен валиден сертификат, но все още няма създадено приложение.


Създаване:
POST API_BASE_WEB/psd2/app/add с подаване на валиден адрес за обратна връзка - REPLY_URI за WEB приложение , SCHEME за мобилно приложение.
В резултат се получава JSON, който съдържа json от вида: 

{"certdata":{"roles":["PSP_AS","PSP_PI","PSP_AI","PSP_IC"],"serial":"26924758290291903361252444186158762848","subject":"Payments AD","validto":"1673690219","digest":"edPx684vhbWNfStWHPgt0BPn27g="},"app":{"appid":"0517814436466328370834363951629359940584980052352957477218124635","secret":"IYePSsmSFHXlg97fdMNQG5p2awKOmTKdrd8g3kdfwF87jkEh9ecj85IgtvXwbvLu6btywUiwceeO1hekiBfd3kiKuA93n0JddyCEl2bjZRnlsv4hV3IdMJsqUKcmFQ4n"},"status":"OK"}

• Таен ключ (SECRET) в app.secret
• Уникален идентификатор (APPID), който се изпраща с всяка заявка към сървърите на ePay.bg/Easypay в app.appid
или 
        {
            "status" : "ERR", 
            "err" : "SOME_ERROR_CODE", 
            "errm" : "Съобщение, което може да покажете на потребителя"
        }


Редакция:
POST API_BASE_WEB/psd2/app/save, която съдържа SCHEME или REPLY_URI
В резултат се получава JSON, който съдържа: 

            {"status":"OK"}

или 
            {
            "status" : "ERR", 
            "err" : "SOME_ERROR_CODE", 
            "errm" : "Съобщение, което може да покажете на потребителя"
        }

Например: 
        {"err":"BADIN","errm":"Please add scheme or reply uri","status":"ERR"}


Премахване:
POST API_BASE_WEB/psd2/app/revoke
В резултат се получава JSON, който съдържа: 

			{"status":"OK"}

или 
			{
            "status" : "ERR", 
            "err" : "SOME_ERROR_CODE", 
            "errm" : "Съобщение, което може да покажете на потребителя"
        }


Освен APPID с всяка заявка ДПУ трябва да изпраща и уникален идентификатор на устройството, използвано от потребителя(DEVICEID), както и TOKEN идентифициращ потребителя, стъпките за чието получаване са описани по-долу.
За идентификатор на устройството се препоръчва използването на Vendor ID в iOS или ANDROID_ID в Android.
Комуникацията със сървърите на ePay.bg се извършва посредством JSON REST API. При успешна заявка се получава отговор, съдържащ:
{ "status": "OK" /*и данни според заявката*/ }
При неуспешна заявка :
{ "status" : "ERR", "err" : "SOME_ERROR_CODE", "errm" : "Съобщение, което може да покажете на потребителя" }
Входните точки за комуникация са:
За тестови цели:
API_BASE : https://demo.epay.bg/xdev/api
API_BASE_WEB : https://demo.epay.bg/xdev/mobile
Продукционна среда:
API_BASE : https://www.epay.bg/v3/api
API_BASE_WEB : https://www.epay.bg/v3/mob
⇡




Оторизация на приложението на ДПУ от потребителя

GET API_BASE_WEB/psd2/start с параметри APPID, DEVICEID,KEY ( уникален за DEVICEID, с който се проверява резултатът от заявката) , PSD2_ONETIME = 0/1 (Генерираният токен се използва за еднократно плащане)
UTYPE=1 , DEVICE_NAME (String Име на устройството) , BRAND ( String Марка на устройството) , OS ( String Операционна система на устройството ) , MODEL ( String Модел на устройството ) ( OS_VERSION String Версия на операционната система ) PHONE = 0/1 Телефонен номер на потребителя
Потребителя се пренасочва в браузър на адрес за автентикация, при успешна автентикация се генерира ключ за издаване на токен.
Примерна заявка за оторизация
https://demo.epay.bg/xdev/mobile/psd2/start?APPID=appid&DEVICEID=deviceid&KEY=uniq_key&DEVICE_NAME=myphone&BRAND=iPhone&OS=iOS&MODEL=iPhone5s&OS_VERSION=8.0&PHONE=1
При получаване на заявката клиентът се насочва за вход в системата на ePay.bg с парола и потребителско име . Според индивидуалните му настройки в системата, ePay.bg изисква SMS код или потвърждение в ePay.bg Mobile : Потребителите, регистрирани за "Временен SMS код" въвеждат SMS код, получен на регистрирания в epay.bg GSM номер. Потребителите, които не са регистрирани за "Временен SMS код" прочитат с ePay.bg Mobile показания на екран QR код и в мобилното приложение се показва информация и бутон за потвърждение на исканото съгласие.
В зависимост от резултата от оторизацията, потребителят ще бъде пренасочен към линкове, които да отворят мобилното приложение или да водят към WEB страницата на ДПУ .
За WEB приложение REPLY_URI/?ret=authok при успех, REPLY_URI/?ret=authagain при неуспех
за Мобилно приложение SCHEME/authok при успех, SCHEME/authagain при неуспех
⇡



Проверка на изхода от оторизациятa

След като потребителят е бил върнат в мобилното приложение на ДПУ или в WEB страницата му в случай на успешна оторизация, ДПУ трябва в рамките на 2 минути да вземе код за издаване на TOKEN с:
GET API_BASE/psd2/code/get с APPID, DEVICEID, KEY - Уникален ключ от предходната заявка GET API_BASE_WEB/psd2/start
Примерна заявка https://demo.epay.bg/xdev/api/psd2/code/get?APPID=appid&DEVICEID=deviceid&KEY=uniq_key
Отговор 
{
    "status":"OK",
    "code":"token_code"
}

Не е нужно да чакате потребителят да се върне в приложението/страницата за изпращане на GET /psd2/code/geti. ⇡



Същинско получаване на TOKEN
GET API_BASE/psd2/token/get с APPID, DEVICEID, CODE ( от отговора на заявката на GET API_BASE/psd2/code/get)
Заявка https://demo.epay.bg/xdev/api/psd2/token/get?APPID=appid&DEVICEID=deviceid&CODE=token_code
Oтговор
{
    "status": "OK",
    "token": "token_string",
    "expires":1720188520,
    "kin":"client uniq number", 
    "username" : "client username",
    "realname": "client real name"
}

Важно! След получаването на TOKEN всички заявки трябва да съдържат APPID, DEVICEID и ТOKEN . Всяка заявка, съдържаща TOKEN, ще връща грешка в случай, че последната аутентикация за този токен е преди повече от 90 дни. Грешката, която се връща в случай, че е необходима допълнителна аутентикация с "Временен SMS код" е EAUTH_REQ_OTP, а в случай на необходимо потрърждение в приложението на ePay.bg - PENDING_APP_CONFIRM . Ако потребителят е регистриран за "Временен SMS код" от него ще се изисква да въведе получения смс код, който да пристигне в параметър "CODE" със следващата заявка или да потвърди действието в приложението на ePay.bg ( със сканиране на QR код или отговаряйки на нотификаця в приложението ) ⇡



Инвалидиране на TOKEN
След тази заявка токенът се деактивира и потребителят няма да може да използва приложението.
GET API_BASE/psd2/token/invalidate APPID,DEVICEID,TOKEN ⇡

Информация за платежни сметки, наличност и движения


Информация за платежни сметки
GET API_BASE/psd2/accounts с параметри APPID,DEVICEID,TOKEN,CODE - SMS код, в случай че действието се нуждае от SCA, може да се пропусне в противен случай.
Примерна заявка: https://demo.epay.bg/xdev/api/psd2/accounts?APPID=appid&DEVICEID=deviceid&TOKEN=token
Отговор: 

{
    "status":"OK",
    "accounts":[
        {
            "name":"Микросметка",
            "id":"UsYGw8-pTlZU4DJOAYT919QVd1EXm2KQ8iD9-2Mr-dQ",
            "currency":"BGN",
            "iban":"BG61ESPY40040014867982"
        }
    ]
}

Или в случай на грешка 
{
    	"status":"ERR",
	"err":"EAUTH_REQ_OTP",
	"errm": "Моля, въведете sms код"
}
, 
{
    	"status":"ERR",
	"err":"PENDING_APP_CONFIRM",
	"errm": "Моля, потвърдете действието в приложението ePay.bg"
}

Описание на параметрите на отговора
ID String, Идентификатор на платежния инструмент (подава се при плащане с него)
IBAN String, IBAN на сметката
NAME, String, Име на платежния инструмент (въведено от потребителя)
⇡



Информация за наличност по платежна сметка
Използва се ID на платежната сметка, което е получено в отговор на заявката за информация за платежни средства.
GET API_BASE/psd2/accounts/balance APPID,DEVICEID,TOKEN,CODE ( при необходимост от SCA ), ACCOUNT
Примерна заявка:
GET API_BASE/psd2/accounts/balance?ACCOUNT=microaccount_id&APPID=appid&DEVICEID=deviceid&TOKEN=token&ACCOUNT=accountid
Отговор: 
{
    "status":"OK",
	"accounts": { "UsYGw8-pTlZU4DJOAYT919QVd1EXm2KQ8iD9-2Mr-dQ" : {
			"status":"OK",
			"id":"UsYGw8-pTlZU4DJOAYT919QVd1EXm2KQ8iD9-2Mr-dQ",
			"balance":"6.68",
			"currency":"BGN",
			"name":"Микросметка"
	}
	}
}

Или в случай на грешка 
{
    	"status":"ERR",
	"err":"EAUTH_REQ_OTP",
	"errm": "Моля, въведете sms код"
}
или 
{
    	"status":"ERR",
	"err":"PENDING_APP_CONFIRM",
	"errm": "Моля, потвърдете действието в приложението ePay.bg"
}

Описание на параметрите на отговора
ID String , Идентификатор на платежния инструмент (подава се при плащане с него)
BALANCE , String , Сума в лв.
NAME String ,Име на платежния инструмент (въведено от потребителя)
⇡



Получаване на информация за движения по платежна сметка
GET API_BASE/psd2/history с APPID,DEVICEID,TOKEN,CODE ( при необходимост от SCA ), ACCOUNT, DATE_FROM (Начална дата unix timestamp, до 90 дни преди настоящия момент), DATE_TO( Крайна дата unix timestamp) , LIMIT ( Int , Брой на движенията в отговора, 20 по подразбиране) , OFFSET ( Int, Брой на движенията, които да бъдат пропуснати.)
Сортирането е по дата в обратен ред, ( Последните по дата се връщат първо)
Отговор: 
{
    "history":[
        {
            "descr":"Вносна бележка: test na vn-bel",
            "account_name":"Микросметка",
            "sum_c":"",
            "longdescr":"ВНОСНА БЕЛЕЖКА\n------------------------------------------------------------\nДата      13.11.2014\nВ полза на           Тестов Потребител\nIBAN                 BG86PRCB03271155173630\nОбщо                 100.80 BGN\n",
            "account":"UsYGw8-pTlZU4DJOAYT919QVd1EXm2KQ8iD9-2Mr-dQ",
            "corr":"Тестов Потребител",
            "sum_d":"119.54",
            "id":"UsYGw8-pTlZU4DJOAYT919upmSriA_z9P8PBePgJ1UI",
            "dat":1415878489,
            "no":"2000000000019592"
        }
    ],
    "status":"OK"
}

ID String ID на операцията
DAT Integer Дата на движението в Unix time
NO String Референция на ePay.bg за движението (такса при плащане има същата референция)
SUM_C String Сума приход в лв
SUM_D String Сума разход в лв
DESCR String Кратко описание
ACCOUNT String ID на платежния инструмент
ACCOUNT_NAME String Име на платежния инструмент
LONGDESCR String Подробно описание на плащането
CORR String Видимо име на кореспондента (може да е e-mail, телефон, КИН, име или комбинация от тях)
⇡



Услуги за иницииране на плащания /PIS, Payment initiation services /

Изпращане на кредитен превод от платежна сметка към IBAN


EasyPSD дава възможност на крайните потребители в интерфейса на ДПУ да наредят кредитен превод от сметката си в ePay.bg към произволен IBAN на физическо или юридическо лице в българска банка. В заявката се подава необхосимата информация за изпълнението на вносна бележка. Таксата за превода се удържа от сметката преди изтеглянето.
Плащането се осъществява на три стъпки:
Резултат от плащането може да се провери с заявка

Получаване на идентификатор за плащането
Идентификаторът ID, получен от тази заявка служи за последващите действия по обработка и извършване на превода , както и за проверка на статус.
POST API_BASE/psd2/send/init с APPID,DEVICEID,TOKEN,CODE ( при необходимост от SCA )
Резултат: 

{
    "payment":{
        "id":"String"
    },
    "status":"String"
}
⇡



Проверка на входящи параметри.
Тази заявка трябва да се направи преди нареждане на превода, когато потребителят е въвел данни за него. В отговора се връщат таксите за плащането, ако са въведени необходимите данни.
POST заявка на API_BASE/psd2/send/check, съдържаща: APPID,DEVICEID,TOKEN,CODE ( при необходимост от SCA ) , ID ( от API_BASE/payment/init ), ACCOUNT ( ID на платежен инструмент от /psd2/accounts ) , IBAN_POL ( IBAN на получателя) , AMOUNT ( сума на превода в лв.) , NAME_POL ( име на получателя) , DESCR ( основание за превода)
Ако плащането е към бюджета се изискват други данни като
NAME_ZL - име на задълженото лице, ZL_ID_DATA - egn or bulstat or lnc, ZL_ID_TYPE = 1 ( EGN) ,2 (BULSTAT) ,3 (LNC) DOC_NO, DOC_DAT, DAT_B, DAT_E, PAY_TYPE_POL
Отговор:

{
    "payment":{
        "id":"String",
        "tax":"String",
        "total":"String"
    },
    "status":"ОК"
}
⇡



Изпълнение на паричен превод по IBAN
Тази заявка трябва да бъде потвърдена с "Временен SMS код" или приложението на ePay.bg
POST API_BASE/psd2/send/pay съдържаща: APPID,DEVICEID,TOKEN,CODE , ID ( от API_BASE/payment/init ), ACCOUNT ( ID на платежен инструмент от /psd2/accounts ) , IBAN_POL ( IBAN на получателя) , AMOUNT ( сума на превода в лв.) , NAME_POL ( име на получателя) , DESCR ( основание за превода)
CODE=се попълва когато потребителят използва "Временен SMS код" и е върната грешка EAUTH_REQ_OTP . Ако потребителят не използва "Временен SMS код" трябва да потвърди това действие с ePay.bg приложението.
Отговор:

{
   "status":"ОК"
}
или 
{
   "status": "ERR", "err" : "EAUTH_REQ_OTP", "errm": "Моля въведете смс код"
}
⇡



Проверка на резултата от заявката превод по IBAN
POST API_BASE/psd2/send/state, съдържаща APPID,DEVICEID,TOKEN,CODE ,ID
В отговора в поле state се съдържа резултата от плащането. Може да бъде 2 -Успешно плащане, всички други - неуспешно или обработващо се . В полето state.name се съдържа информация, която може да бъде показана на потребителя.
Отговор: 

{
    "status":"OK",
    "payment":{
        "state":4,
        "state.name":"Неуспешно плащане(Невалидни данни. (514))"
    }
}
⇡





Потвърждаване на наличност на средства /CF, Confirmation of funds/

GET API_BASE/psd2/accounts/avail с параметри APPID,DEVICEID,TOKEN,ACCOUNT,AMOUNT
Отговор: 
{
	"status":"OK"
}

Актуална версия на документацията е налична на адрес: https://www.easypay.bg/site/?p=psd2_doc

© Изипей АД 2006 - 2023. Всички права запазени.