Настоящата документация е предназначена за банки и финансови организации, които в съответствие с разширената Директива на Европейския съюз относно платежните услуги 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"}
{ "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" : "Съобщение, което може да покажете на потребителя" }
GET API_BASE_WEB/psd2/start
с параметри APPID, DEVICEID,KEY ( уникален за DEVICEID, с който се проверява резултатът от заявката) , PSD2_ONETIME = 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
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
.
⇡
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
{ "status": "OK", "token": "token_string", "expires":1720188520, "kin":"client uniq number", "username" : "client username", "realname": "client real name" }
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" }
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" }
{ "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, получен от тази заявка служи за последващите действия по обработка и извършване на превода , както и за проверка на статус.
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))" } }⇡
GET API_BASE/psd2/accounts/avail
с параметри APPID,DEVICEID,TOKEN,ACCOUNT,AMOUNT
{ "status":"OK" }