EasyPSD Payment Interface

This documentation is intended for banks and financial institutions that, in accordance with the revised European Union Payment Services Directive PSD2 Directive (EU) 2015/2366, wish to offer their clients services related to payment accounts operated by EasyPay AD within their platforms. In this document, such institutions are referred to as "Payment Service Providers" (PSPs).

Any service provider licensed to operate account information services and/or payment initiation services in accordance with Directive (EU) 2015/2366 can access the EasyPay AD Developer Portal and connect to the APIs developed by EasyPay.

When first connecting to the Portal and the EasyPay APIs, the Provider must authenticate using a valid QWAC (PSD2-compliant Qualified Web Authentication Certificate) issued by one of the licensed trust service providers listed in the EU list of trusted providers.

To verify the license and role of the provider—whether as an Account Information Service Provider, Payment Initiation Service Provider, or Card-Based Payment Instrument Issuer—EasyPay checks the unified register of payment institutions and electronic money institutions maintained by the EBA, accessible at https://www.eba.europa.eu/risk-analysis-and-data/register-payment-electronic-money-institutions-under-PSD2.

Upon submission of a valid certificate and request for initial access, the PSP provides EasyPay with a valid contact address—REPLY_URI for web applications and URL Scheme for mobile applications—for communication and information exchange. The PSP that has provided a valid access certificate receives an application secret key and a unique identifier (APPID), which the Provider must include with every request to EasyPay’s servers to access customer accounts, ensuring that EasyPay can identify the Provider associated with the request.

In addition to the APPID, the PSP must include a unique identifier for the user’s device (DEVICEID) with each request. It is recommended to use the Vendor ID in iOS or ANDROID_ID in Android as the device identifier.

The third essential and mandatory parameter that must be included in every request the provider sends to EasyPay for account access is the TOKEN identifying the user. The TOKEN is obtained when the user consents to account access through another PSP, as described in section 3.1.

Communication with EasyPay servers is conducted via JSON REST API. EasyPay provides entry points for communication with its servers in both test and production environments.

With a valid QWAC certificate, a PSP Developer profile can be created, verified, edited, or removed.

View:
GET API_BASE_WEB/psd2/app
The result is a JSON containing application data: 

{"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" : "Message you can display to the user"
        }

Например: 
        {"err":"NOAPP","errm":"Request failed. Please contact support(NOAPP)","status":"ERR","app":null,"certdata":{"subject":"Payments AD","serial":"26924758290291903361252444186158762848","digest":"edPx684vhbWNfStWHPgt0BPn27g=","validto":"1673690219","roles":["PSP_AS","PSP_PI","PSP_AI","PSP_IC"]}}

This indicates that a valid certificate was provided, but no application has been created yet.


Create:
POST API_BASE_WEB/psd2/app/add With the submission of a valid - REPLY_URI за WEB приложение , SCHEME for the mobile application,
the result is a JSON of the following type: 

{"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 key (SECRET) in app.secret
• Unique identifier (APPID), which is sent with every request to the ePay.bg/Easypay servers in app.appid
или 
        {
            "status" : "ERR", 
            "err" : "SOME_ERROR_CODE", 
            "errm" : "Message you can display to the user"
        }


Edit:
POST API_BASE_WEB/psd2/app/save, This contains SCHEME or REPLY_URI
, and the result is a JSON containing: 

            {"status":"OK"}

Or: 
            {
            "status" : "ERR", 
            "err" : "SOME_ERROR_CODE", 
            "errm" : "Message you can display to the user"
        }

For example: 
        {"err":"BADIN","errm":"Please add scheme or reply uri","status":"ERR"}


Remove:
POST API_BASE_WEB/psd2/app/revoke
The result is a JSON containing: 

			{"status":"OK"}

или 
			{
            "status" : "ERR", 
            "err" : "SOME_ERROR_CODE", 
            "errm" : "Message you can display to the user"
        }


In addition to the APPID, every request from the PSP must include the unique device identifier (DEVICEID) used by the user and the TOKEN identifying the user, as described below.
It is recommended to use the Vendor ID in iOS or ANDROID_ID in Android as the device identifier.
Communication with the ePay.bg servers is carried out via JSON REST API. A successful request returns a response containing:
{ "status": "OK" /*and data according to the request*/ }
For an unsuccessful request:
{ "status" : "ERR", "err" : "SOME_ERROR_CODE", "errm" : "Message you can display to the user" }
The entry points for communication are:
For testing purposes:
API_BASE : https://demo.epay.bg/xdev/api
API_BASE_WEB : https://demo.epay.bg/xdev/mobile
Production environment:
API_BASE : https://www.epay.bg/v3/api
API_BASE_WEB : https://www.epay.bg/v3/mob
⇡




Authorization of the PSCs application by the user

GET API_BASE_WEB/psd2/start with parameters: APPID, DEVICEID,KEY ( unique for DEVICEID, with which the result of the request is checked) , PSD2_ONETIME = 0/1 (The generated token is used for one-time payment)
UTYPE=1 , DEVICE_NAME (String: Device Name) , BRAND ( String: Device Brand) , OS ( String: Device Operating System ) , MODEL ( String: Device Model ) ( OS_VERSION String: Operating System Version ) PHONE = 0/1 Telephone number of the user
The user is redirected in a browser to an authentication address. Upon successful authentication, a key is generated to issue a token.
Sample authorization request:
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
Upon receipt of the request, the client is directed to log in to the ePay.bg system with a password and username. According to their individual settings in the system, ePay.bg requires an SMS code or confirmation via ePay.bg Mobile.
  • Users registered for "Temporary SMS Code" enter the SMS code received on the GSM number registered in ePay.bg.
  • Users who are not registered for "Temporary SMS Code" scan a QR code displayed on the screen using ePay.bg Mobile, and the mobile application displays information and a button to confirm the requested consent.

Depending on the result of the authorization, the user will be redirected to links that open the mobile application or lead to the web page of the PSCs.
  • For the web application: REPLY_URI/?ret=authok при успех, REPLY_URI/?ret=authagain on failure.
  • For the mobile app: SCHEME/authok при успех, SCHEME/authagain on failure.
⇡



Checking the Authorization Output

After the user has been returned to the PSCs mobile application or to its web page in case of successful authorization, the PSCs must, within 2 minutes, take a TOKEN issue code with:
GET API_BASE/psd2/code/get с APPID, DEVICEID, KEY - unique key from previous request GET API_BASE_WEB/psd2/start
Sample request: https://demo.epay.bg/xdev/api/psd2/code/get?APPID=appid&DEVICEID=deviceid&KEY=uniq_key
Response: 
{
    "status":"OK",
    "code":"token_code"
}

It is not necessary to wait for the user to return to the application/page before sending GET /psd2/code/geti. ⇡



Actual Receipt of TOKEN
GET API_BASE/psd2/token/get с APPID, DEVICEID, CODE ( from the GET API_BASE/psd2/code/get)
Request: https://demo.epay.bg/xdev/api/psd2/token/get?APPID=appid&DEVICEID=deviceid&CODE=token_code
Response:
{
    "status": "OK",
    "token": "token_string",
    "expires":1720188520,
    "kin":"client uniq number", 
    "username" : "client username",
    "realname": "client real name"
}

Important: After receiving the TOKEN, all requests must contain APPID, DEVICEID, and TOKEN. Any request containing a TOKEN will return an error if the last authentication for that token was more than 90 (180 for information services) days ago. The error returned in the case where additional authentication with "Temporary SMS Code" is required is EAUTH_REQ_OTP, and if confirmation is required in the ePay.bg application - PENDING_APP_CONFIRM. If the user is registered for "Temporary SMS Code," they will be required to enter the received SMS code, which will arrive in the "CODE" parameter with the next request, or confirm the action in the ePay.bg application (by scanning a QR code or responding to the notification in the application). ⇡



TOKEN Invalidation
After this request, the token is disabled, and the user will not be able to use the application.
GET API_BASE/psd2/token/invalidate APPID,DEVICEID,TOKEN ⇡

Information About Payment Accounts, Availability, and Transactions


Information About Payment Accounts
GET API_BASE/psd2/accounts with parameters: APPID,DEVICEID,TOKEN,CODE - SMS code in case the action requires SCA, can be omitted otherwise.
Sample request: https://demo.epay.bg/xdev/api/psd2/accounts?APPID=appid&DEVICEID=deviceid&TOKEN=token
Response: 

{
    "status":"OK",
    "accounts":[
        {
            "name":"Microaccount",
            "id":"UsYGw8-pTlZU4DJOAYT919QVd1EXm2KQ8iD9-2Mr-dQ",
            "currency":"BGN",
            "iban":"BG61ESPY40040014867982"
        }
    ]
}

Or in case of an error: 
{
    	"status":"ERR",
	"err":"EAUTH_REQ_OTP",
	"errm": "Please enter SMS code"
}
, 
{
    	"status":"ERR",
	"err":"PENDING_APP_CONFIRM",
	"errm": "Please confirm the action in the ePay.bg application"
}

Description of Response Parameters
  • ID: String, Identifier of the payment instrument (provided when paying with it).
  • IBAN: String, IBAN of the account.
  • NAME: String, Name of the payment instrument (entered by the user).
⇡



Payment Account Availability Information
The payment account ID received in response to the payment information request is used.
GET API_BASE/psd2/accounts/balance APPID,DEVICEID,TOKEN,CODE ( in case the action requires SCA ), ACCOUNT
Sample request:
GET API_BASE/psd2/accounts/balance?ACCOUNT=microaccount_id&APPID=appid&DEVICEID=deviceid&TOKEN=token&ACCOUNT=accountid
Response: 
{
    "status":"OK",
	"accounts": { "UsYGw8-pTlZU4DJOAYT919QVd1EXm2KQ8iD9-2Mr-dQ" : {
			"status":"OK",
			"id":"UsYGw8-pTlZU4DJOAYT919QVd1EXm2KQ8iD9-2Mr-dQ",
			"balance":"6.68",
			"currency":"BGN",
			"name":"Microaccount",
            "balanceType": "interimAvailable"
	    }
	}
}

Or in case of an error: 
{
    	"status":"ERR",
	"err":"EAUTH_REQ_OTP",
	"errm": "Please enter SMS cod"
}
или 
{
    	"status":"ERR",
	"err":"PENDING_APP_CONFIRM",
	"errm": "Please confirm the action in the ePay.bg application"
}

Description of Response Parameters
  • balancetype: String, type.
  • amount: String, Amount.
  • currency: String, Currency.
⇡



Payment Account Availability Information
The payment account ID received in response to the payment information request is used.
GET API_BASE/psd2/accounts/balances APPID,DEVICEID,TOKEN,CODE ( in case the action requires SCA ), ACCOUNT
Sample request:
GET API_BASE/psd2/accounts/balances?ACCOUNT=microaccount_id&APPID=appid&DEVICEID=deviceid&TOKEN=token&ACCOUNT=accountid
Response: 
{
    "status":"OK",
	"balances": [ 
        {   
            "balancetype": "interimAvailable",
			"balanceamount": {
                "amount":"6.68",
                "currency":"BGN"
            }
	    }
	]
}

Или в случай на грешка 
{
    	"status":"ERR",
	"err":"EAUTH_REQ_OTP",
	"errm": "Please enter SMS code"
}
или 
{
    	"status":"ERR",
	"err":"PENDING_APP_CONFIRM",
	"errm": "Please confirm the action in the ePay.bg application"
}

Description of Response Parameters
balancetype: String , type
amount: String , Amount
currency: String ,Currency
⇡



Receiving Information About Transactions on a Payment Account
GET API_BASE/psd2/history with parameters: APPID, DEVICEID, TOKEN, CODE (in case the action requires SCA), ACCOUNT, DATE_FROM (Start date Unix timestamp, up to 90 days before the current moment), DATE_TO (End date Unix timestamp), LIMIT (Int, Number of transactions in response, 20 by default), OFFSET (Int, Number of transactions to be skipped).
Sorting is by date in reverse order (the most recent by date is returned first).
Response: 
{
    "history":[
        {
            "status":"booked",
            "descr":"Deposit slip: test na vn-bel",
            "account_name":"MicroAccount",
            "sum_c":"",
            "longdescr":"DEPOSIT SLIP\n------------------------------------------------------------\nДата      13.11.2014\nВ полза на           Тестов Потребител\nIBAN                 BG86PRCB03271155173630\nОбщо                 100.80 BGN\n",
            "account":"UsYGw8-pTlZU4DJOAYT919QVd1EXm2KQ8iD9-2Mr-dQ",
            "corr":"Test User",
            "sum_d":"119.54",
            "id":"UsYGw8-pTlZU4DJOAYT919upmSriA_z9P8PBePgJ1UI",
            "dat":1415878489,
            "no":"2000000000019592",
            "corr_account_type": "cin",
            "corr_account": "3394619971"
        }
    ],
    "status":"OK"
}

ID: String, ID of the operation.
DAT: Integer, Date of transaction in Unix time.
NO: String, Reference of ePay.bg for the transaction (payment fee has the same reference).
SUM_C: String, Amount of income in BGN.
SUM_D: tring, Amount of expenditure in BGN.
DESCR: String, Short description.
ACCOUNT: String, ID of the payment instrument.
ACCOUNT_NAME: String, Name of the payment instrument.
LONGDESCR: String, Detailed description of the payment.
CORR: String, Visible name of the correspondent (can be an email, phone, Personal Identification Code (EGN - for Bulgarian citizens), name, or a combination of them).
CORR_ACCOUNT: String, Identifier of the correspondent.
CORR_ACCOUNT_TYPE: String, Type of the correspondent's identifier - cin (customer number), iban (account number), pos (terminal identifier), uic (TIN or customer ID card number).
STATUS: String, "booked" for finalized or "pending"
⇡



PIS, Payment Initiation Services

Send credit transfer from a payment account to IBAN.


EasyPSD enables end users in the DPU interface to order a credit transfer from their ePay.bg account to any IBAN of an individual or legal entity in a Bulgarian bank. In the request, the necessary information for the execution of an deposit slip is submitted. The transfer fee is deducted from the account before withdrawal.
Payment is made in three steps:
The payment result can be checked by request

Get a Payment ID
The identifier ID obtained from this request serves for the subsequent actions of processing and carrying out the transaction, as well as for checking the status.
POST API_BASE/psd2/send/init с APPID,DEVICEID,TOKEN,CODE ( in case the action needs SCA )
Резултат: 

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



Checking Parameters
This request must be made before ordering the transaction, when the user has entered data for it. The response returns the payment fees if the required data is entered.
POST request to API_BASE/psd2/send/check, containing: APPID,DEVICEID,TOKEN,CODE ( in case the action needs SCA ) , ID ( от API_BASE/payment/init ), ACCOUNT ( ID of payment instrument from /psd2/accounts ) , IBAN_POL ( IBAN of the recipient ) , AMOUNT ( amount of the transfer in BGN ) , NAME_POL ( name of the recipient ) , DESCR ( reason for the transfer )
If the payment is to the state budget, other data is required such as:
NAME_ZL - name of the obligee, 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
Answer:

{
    "payment":{
        "id":"String",
        "tax":"String",
        "total":"String"
    },
    "status":"ОК"
}
In case a declaration of the origin of the funds is required, the response contains an element declaration_required with a value of 1, which indicates that the user must specify the origin of the funds - for example, "commercial activity," "labor activity," "savings," "other." This is done directly in the "Execute Money Transfer" request, sending the funds origin data as text with the "DECLARATION" parameter: 
{
    "payment":{
        "id":"String",
        "tax":"String",
        "total":"String"
    },
    "declaraion_required": 1,
    "status":"ОК"
}

Or in case of an error: 
{
    	"status":"ERR",
	"err":"EAUTH_REQ_OTP",
	"errm": "Please enter SMS code"
}
, 
{
    	"status":"ERR",
	"err":"PENDING_APP_CONFIRM",
	"errm": "Please confirm the action in the ePay.bg application"
}
In this case, confirmation is required from the application, which must be done before performing a money transfer with  POST на API_BASE/psd2/send/pay. This can be verified by resubmitting a verification request.

⇡



Execution of Money Transfer by IBAN
This request must be confirmed with "Temporary SMS Code" or via the ePay.bg application.
POST API_BASE/psd2/send/pay containing: APPID,DEVICEID,TOKEN,CODE , ID ( от API_BASE/psd2/send/init ), ACCOUNT ( payment instrument ID from /psd2/accounts ) , IBAN_POL ( recipient's IBAN) , AMOUNT ( amount of the transfer in BGN) , NAME_POL ( name of the recipient) , DESCR ( reason for the transfer)
CODE is filled in when the user uses "Temporary SMS Code," and an EAUTH_REQ_OTP error is returned. If the user does not use "Temporary SMS Code," they must confirm this action through the ePay.bg application.
DECLARATION="string" is filled with text clarifying the origin of the funds when declaration_required: 1 is returned during verification or when performing an IBAN money transfer when a DECLARATION_REQUIRED error is returned.
Отговор:

{
   "status":"ОК"
}
или 
{
   "status": "ERR", "err" : "EAUTH_REQ_OTP", "errm": "Please enter SMS code"
}

In case confirmation is required in the application: 
{
    	"status":"ERR",
	"err":"PENDING_APP_CONFIRM",
	"errm": "Please confirm the action in the ePay.bg application"
}
If you receive the above error on a transfer request to API_BASE/psd2/send/pay, then the action has not yet been confirmed in the app and the same request should be rerun until you receive an OK or another error other than PENDING_APP_CONFIRM. If you want to know if there is already confirmation in the app, you can run a check request on /API_BASE/psd2/send/check; if it’s already confirmed, you won't receive a "PENDING_APP_CONFIRM" error.



In case that a declaration of the origin of the funds is required, the following response is returned:


{
 "status"   : "ERR', "err"  : "DECLARATION_REQUIRED" 
}


The user must specify the origin of the funds, and this should be sent in the "DECLARATION" parameter - for example, "commercial activity," "labor activity," "savings," "other."  


⇡












Checking the Result of the IBAN Transfer Request


POST API_BASE/psd2/send/state, containing:  APPID,DEVICEID,TOKEN,CODE ,ID

 
The response in the state field contains the result of the payment. It can be 2 - Successful payment; all others indicate failed or processing. The state.name field contains information that can be displayed to the user. 


Response:

{
    "status":"OK",
    "payment":{
        "state":4,
        "state.name":"Payment failed (Invalid data. (514))"
    }
}


⇡






                            
 
                            

                            








                            

                            

                            CF, Confirmation of Funds
                            
                            

                            

                            
							GET API_BASE/psd2/accounts/avail with parameters: APPID,DEVICEID,TOKEN,ACCOUNT,AMOUNT
                            

                            Response:
                            


							
{
	"status":"OK"
}
The latest version of the documentation is available at: https://www.easypay.bg/site/?p=psd2_doc

© EasyPay Ltd 2006 - 2026. All rights reserved.