Payments BG API

The Payments API allows third party applications to perform money transfers from a bank client's account on his behalf, including the following operations:

  • Single Domestic (BGN) Credit Transfer
  • Single Domestic Budgetary (BGN) Credit Transfer
  • Single SEPA Credit Transfer
  • Single Foreign (cross-border) Credit Transfer
  • In Real API available currencies will be: BGN, USD, EUR, JPY, CHF, AUD, CAD, DKK, HUF, JPY, NOK, SEK, PLN, RON 
  • The currency available in Sandbox and real APIs for initiating periodic payments is BGN. 
  • Single payments can be instructed as immediate or future dated. Execution date in the past is not allowed. Future dated payments that involves FX rate are not allowed 
  • Debtor account should be in IBAN format
  • Creditor account should be in IBAN format; otherwise, if non-IBAN format is used then Creditor agent is mandatory and should contain BIC. For Raiffeisen Bank  accounts only IBAN format is  accepted
  • Payments between different currencies on the same account (currency conversions) are not supported.
  • Bulk payments, recurring payments, signing basket and application of multilevel SCA will be available as services only in our Sandbox. The functionalities will cover the Berlin Group Standard. Currently we are expecting our National API Developer to provide a new version of our National API Standards called “BISTRA” which to include the above functionalities.

Clients

Payment initiation through API open banking channel can be used by Raiffeisenbank Bulgaria EAD’s clients who have access to an open current account via Internet banking.

Type of payments

Payment type is decided automatically by Raiffeisenbank Bulgaria EAD depending on the payment details of initiated payment. Available options and conditions are listed below:

  1. Domestic payment (standard credit transfer in BGN): transaction currency is „BGN“ and IBAN starts with „BG*“
  2. SEPA payment: transaction currency is „EUR“, destination bank is SEPA reachable, all mandatory fields for SEPA payment are filled
  3. Foreign payment: any other payment not meeting conditions of above payments
  4. Periodic payments – can be only in BGN and initiated as standard credit transfer. Periodic budgetary payments will be available in the next Sandbox release.

 

Time schedule for execution of payment transactions

Remember to check periods for payment order submitting in order to have payments processed at the time you request.

Cut of time periods for payments initiated via the current internet banking are available on our web: https://www.rbb.bg/bg/individualni-klienti/#

Payment fees

Payments placed via the open banking are charged to clients of Raiffeisenbank Bulgaria EAD same as the payments initiated via the current internet banking according to your pricing plan. 

Exchange rates

Exchange rates are the same as used on the current internet banking. All current exchange rates can be checked on this https://www.rbb.bg/en/individual-clients/#

 

Balance types during the payment flow:

  • expected - optional
  • interimAvailable – optional

When, you as TPP’s developer initiates a payment, the expected balance type should be updated and must be used during transaction is in pending status (ACTC). When reaching the final status (ACSC) interimAvailable is updated too.

Thus, after payment is fully processed, if there are no other pending transactions, both expected and interimAvailable balance will have the same value.

Domestic Payment Definitions

The Bulgarian standard BISTRA (version 1.2) supporting the XS2A interface, based on the document NextGenPSD2 XS2A framework extend the acceptable data elements for the specific local transfers BGN Budget Credit Transfer, BGN Credit Transfer. Moreover, Bulgaria is non-Euro country and there are specifics in SCT EU Core to the following extended format. 

JSON based Domestic Payment Products

National standard Single Payments

The following table gives an overview on the Bulgarian National standard generic defined JSON structures of standard payment products for single payments.

Data Element

Type

domestic-budget- transfer-BGN

domestic-credit-transfer-BGN

SEPA-Credit-Transfer

 Cross-border CT

 (non SEPA)

endToEndIdentification

Max35Text

optional

optional

optional

optional

debtorAccount (incl. type)

Account Reference

mandatory

mandatory

mandatory

mandatory

debtorId *

Max35Text

n.a.

n.a.

n.a.

n.a.

ultimateDebtor

Max70Text

mandatory

n.a.

n.a.

n.a.

instructedAmount (inc. Curr.)

Amount

mandatory

mandatory

mandatory

mandatory

transactionCurrency *

Currency Code

n.a.

n.a.

n.a.

n.a.

creditorAccount

Account Reference

mandatory

mandatory

mandatory

mandatory

creditorAgent

BICFI

optional

optional

optional

optional

creditorAgentName **

Max70Text

n.a.

n.a.

n.a.

optional

creditorAgentAddress **

Address

n.a.

n.a.

n.a.

optional

creditorName

Max70Text

mandatory

mandatory

mandatory

mandatory

creditorId *

Max35Text

n.a.

n.a.

n.a.

n.a.

creditorAddress

Address

optional

optional

optional

mandatory

ultimateCreditor *

Max70Text

n.a.

n.a.

n.a.

n.a.

purposeCode

Purpose Code

mandatory

n.a.

n.a.

n.a.

chargeBearer

Charge Bearer Code

n.a.

n.a.

optional

conditional

remittanceInformationUnstructured

Max140Text

mandatory

mandatory

mandatory

mandatory

remittanceInformation UnstructuredArray *

Array of Max140Text

n.a.

n.a.

n.a.

n.a.

remittanceInformationStructured *

Remittance

n.a.

n.a.

n.a.

n.a.

requestedExecutionDate *

ISODate

n.a.

n.a.

n.a.

n.a.

requestedExecutionTime *

ISODateTime

n.a.

n.a.

n.a.

n.a.

service Level

Service Level Code

mandatory

mandatory

mandatory

mandatory

budgetPaymentDetails

Budget Payment Details

mandatory

n.a.

n.a.

n.a.

 

* Marked fields are not applicable to BISTRA version 1.2, but may be used in later versions.

 

** The attributes should present only in the case when the beneficiary's account is not in IBAN format and the beneficiary's Bank SWIFT BIC is not provided.

 

Account Reference

 

Attribute

Type

Condition

Description

iban

IBAN

Conditional

If BGN Budget transfer, position 13 must contain "8" or "3" only.

Budget Payment Details

 

Attribute

Type

Condition

Description

regulatoryReportType

Regulatory Report Type

mandatory

Regulatory Report Type – 1 digit code

documentNumber

String

optional

Document Number issued by Government authority

documentDate

ISODate

optional

Document Date issued by Government authority

taxpayer ID

String 10 digits

optional

Tax Id

taxpayer Type

Tax Type Code

optional

Tax Type – 3 CAP letters code

paymentCategory

Payment Category Code

optional

Payment Category – 6 digit code

fromDate

ISODate

optional

From Date – start of period date

endDate

ISODate

optional

End Date – end of period date

obligedPersonName

String

mandatory

This field is mandatory in our   processing systems and if PSU cannot provide it, than the payment will not be executed

 

 

Code table

 

Code attribute

Type

Description

Purpose Code

String 4 letters

GOVT - Constant marker budget payment

Service Level Code

String 4 letters

SEPA - Used for SEPA payment URGP – Used for payments through RTGS System (RINGS), NURG - Used for payments through BISERA Default value = NURG

SDVA – Used for Cross border CT. Payment must be executed with same day value to the creditor.

NEXT - Used for Cross border CT. Payment must be executed with next working day value to the creditor

SPOT - Used for Cross border CT. Payment must be executed with spot working day value to the creditor

Charge Bearer Code

String 4 letters

DEBT - Borne By Debtor CRED - Borne By Creditor SHAR - Shared In Credit Transfer context SLEV - Used for SEPA payments

Regulatory Report Type

1 digit

1 - Declaration 2 - Inspection Act 3 - Penalty Decree 4 - advance payment 5 - batch property number 6 - enforced collection order 9 - others

Tax Type Code

String 3 letters

ЕГН / EGN - Personal ID ЕИК / EIK - Corporate ID ЛНЧ / PNF - Foreign Person ID

paymentCategory

String-6 digits

110000 - НАП (NRA) 551111 - НОИ (NSSI) 561111 - НЗОК (NHIF) 581111 - ДЗПО (SCPI)

 

Payment statuses:

Single Payments

Status

after receving POST /payments request

RCVD

before signing of payment (if execution date is today, an automatic job set to 1 minute for triggering the settlement process)

after signing of payment (if execution date is today, an automatic job set to 1 minute for triggering the settlement process)

ACCP

 

ACSP

if funds check is OK settlement process is finished

ACSC (final status)

Corresponding transaction is generated in trx history as a pending after the funds check, and after 5 min transaction is changed to status booked.

 

ERROR SCENARIO:

 

if not sufficient funds

ACCP with flag fundsAvailable=false (final status, in Sandbox no check whether funds arrived later)

Single Payments future dated

Status

after receving POST /payments request

RCVD

before signing of payment (if execution date is today, an automatic job set to 1 minute for triggering the settlement process)

after signing of payment (if execution date is today, an automatic job set to 1 minute for triggering the settlement process)

ACCP

 

ACSP

if funds check is OK settlement process is finished

ACSC (final status)

Corresponding transaction is generated in trx history as a pending after the funds check, and after 5 min transaction is changed to status booked.

 

ERROR SCENARIO:

 

if not sufficient funds on dayOfExecution

ACCP with flag fundsAvailable=false (final status, in Sandbox no check whether funds arrived later)

Periodic Payments

Status

after receving POST /payments request

RCVD

before signing of payment (if execution date is today, an automatic job set to 1 minute for triggering the settlement process)

after signing of payment (if execution date is today, an automatic job set to 1 minute for triggering the settlement process)

ACCP

 

ACSP

if funds check is OK settlement process is finished

ACSC (final status)

Single payment out of the periodic payments sequence doe not have any paymentId, only transactionId and are shown in Transaction history of that account. Transaction remains in ACTC until it is expired or cancelled.

 

 

Cancellation of payments: 

You, as a TPP’s developer can cancel only payments that are initiated by your application.

Valid for both possibilities: real time and future-dated payments.

Single payments can be cancelled only:

  • if not yet executed

 

 Payment Status

Cancellation possible Y/N

SCA required for cancellation Y/N

RCVD

Y

N

ACCP

Y

N

RJCT

N

-

ACSP

N

-

ACSC

N

-

CANC

N

 

 

Foreign payments specific

Bellow table should be used when PSU would like to order a SEPA or cross-border credit transfer. In this case, bellow code should be provided at the beginning of remittanceInformationUnstructured in the body of POST /v1/payments/ {payment-product} in the way given in the table, column EXAMPLE.

When the payment is related to following activities, then between % BNB reference number% should be provided Bulgarian National Bank reference number of already registered services (please see also the examples given in the table):

  • Direct investments in joint-stock capital by residents abroad
  • Direct investment in joint-stock capital by non-residents in Bulgaria
  • Investments by residents in real estate abroad
  • Investments by non-residents in real estates in Bulgaria
  • Portfolio investments by residents in shares issued by non-residents
  • Portfolio investments by non-residents in shares issued by residents
  • Investments of residents in options issued by non-re
  • Investments by non-residents in options issued by residents
  • Trading with financial derivatives other than options
  • Income generated by derivatives
  • Short-term loans granted by residents to non-residents
  • Short-term loans granted by non-residents to residents
  • Long-term loans granted by residents to non-residents
  • Long-term loans granted by non-residents to residents
  • Deposits, current and other accounts held by residents, customers of the bank, with non-residents
  • Deposits, current and other accounts held by non-residents, not banks, with residents

КОД/CODE

ОПИСАНИЕ

DESCRIPTION

EXAMPLE

101

Стоки

Goods

remittanceInformationUnstructured = 101%%Payment details for Goods

201

Товарен транспорт

Logistics

remittanceInformationUnstructured = 201%%Payment details for Goods

202

Пътнически транспорт

Passengers transport

remittanceInformationUnstructured = 202%%Payment details for Goods

203

Други транспортни услуги

Other transport services

remittanceInformationUnstructured = 203%%Payment details for Goods

281

Разплащане с чекове

Payment by checks

remittanceInformationUnstructured = 281%%Payment details for Goods

282

Разплащане с банкови карти

Payment by credit cards

remittanceInformationUnstructured = 282%%Payment details for Goods

291

Пътуване

Tourist services

remittanceInformationUnstructured = 291%%Payment details for Goods

292

Образователни услуги

Educational services

remittanceInformationUnstructured = 292%%Payment details for Goods

293

Здравни услуги

Medical services

remittanceInformationUnstructured = 293%%Payment details for Goods

310

Застрахователни услуги

Insurance services

remittanceInformationUnstructured = 310%%Payment details for Goods

350

Финансови услуги

Financial services

remittanceInformationUnstructured = 350%%Payment details for Goods

401

Пощенски услуги

Postal services

remittanceInformationUnstructured = 401%%Payment details for Goods

402

Куриерски услуги

Courier services

remittanceInformationUnstructured = 402%%Payment details for Goods

403

Телекомуникационни услуги

Telecommunication services

remittanceInformationUnstructured = 403%%Payment details for Goods

411

Строителни услуги в страната

Construction services domestic

remittanceInformationUnstructured = 411%%Payment details for Goods

412

Строителни услуги в чужбина

Construction services abroad

remittanceInformationUnstructured = 412%%Payment details for Goods

421

Франчайзинг и сродни права

Franchising and related rights

remittanceInformationUnstructured = 421%%Payment details for Goods

422

Други авторски права и лицензионни такси

Other copyrights and licence fees

remittanceInformationUnstructured = 422%%Payment details for Goods

431

Компютърни услуги

Computer services

remittanceInformationUnstructured = 431%%Payment details for Goods

432

Новинарски услуги

Information services

remittanceInformationUnstructured = 432%%Payment details for Goods

439

Други информационни услуги

Other information services

remittanceInformationUnstructured = 439%%Payment details for Goods

441

Търговско посредничество

Commercial agency

remittanceInformationUnstructured = 441%%Payment details for Goods

449

Други търговски услуги

Other commercial services

remittanceInformationUnstructured = 449%%Payment details for Goods

450

Оперативен лизинг

Operational leasing

remittanceInformationUnstructured = 450%%Payment details for Goods

461

Преработка на отпадъци и пречистване на околната среда

Recycling and environmental purification

remittanceInformationUnstructured = 461%%Payment details for Goods

462

Услуги, свързани със селското, горското стопанство, минно-добивната и преработващата промишленост

Services related to agriculture, forestry, mining and manufacturing

remittanceInformationUnstructured = 462%%Payment details for Goods

471

Правни услуги

Legal services

remittanceInformationUnstructured = 471%%Payment details for Goods

472

Счетоводни, одиторски и данъчни консултации

Accounting, audit and tax consultations

remittanceInformationUnstructured = 472%%Payment details for Goods

473

Бизнес и управленско консултиране и връзки с обществеността

Business and management consultations; Public relations

remittanceInformationUnstructured = 473%%Payment details for Goods

474

Реклама, пазарни проучвания и изследване на общественото мнение

Advertising, market surveys and research of public opinion

remittanceInformationUnstructured = 474%%Payment details for Goods

475

Научно изследователска и развойна дейност

Research and development activities

remittanceInformationUnstructured = 475%%Payment details for Goods

476

Проектантски, инженерингови услуги и техническа помощ

Design, engineering and technical services

remittanceInformationUnstructured = 476%%Payment details for Goods

479

Други бизнес услуги

Other business servicesa

remittanceInformationUnstructured = 479%%Payment details for Goods

481

Аудиовизуални и сходни с тях услуги

Audiovisual and similar services

remittanceInformationUnstructured = 481%%Payment details for Goods

489

Други лични услуги и услуги в сферата на културата и спорта

Other personal services and services in the field of culture and sport

remittanceInformationUnstructured = 489%%Payment details for Goods

491

Услуги извършени от посолства и консулства

Services performed by embassies and consulates

remittanceInformationUnstructured = 491%%Payment details for Goods

492

Услуги извършени от военни подразделения и агенции

Services performed by military units and agencies

remittanceInformationUnstructured = 492%%Payment details for Goods

499

Други правителствени услуги

Other government services

remittanceInformationUnstructured = 499%%Payment details for Goods

510

Заплати и компенсации

Salaries and compensations

remittanceInformationUnstructured = 510%%Payment details for Goods

520

Доход от преки инвестиции

Income from direct investments

remittanceInformationUnstructured = 520%%Payment details for Goods

530

Доход от портфейлни инвестиции

Income from portfolio investments

remittanceInformationUnstructured = 530%%Payment details for Goods

540

Доход от лихви по кредити

Income from interest on loans

remittanceInformationUnstructured = 540%%Payment details for Goods

550

Доход от лихви по депозитни, разплащателни и др. сметки

Income from interest on deposit, current and other accounts

remittanceInformationUnstructured = 550%%Payment details for Goods

560

Доход от притежавани живото-застрахователни полици

Income from Life-insurance policies

remittanceInformationUnstructured = 560%%Payment details for Goods

610

Правителствени трансфери

Governmental transfers

remittanceInformationUnstructured = 610%%Payment details for Goods

621

Частни трансфери от роднини емигранти

Private transfers from migrant relatives

remittanceInformationUnstructured = 621%%Payment details for Goods

629

Други частни трансфери

Other private transfers

remittanceInformationUnstructured = 629%%Payment details for Goods

631

Частни трансфери за косвени данъци

Private transfers for indirect taxes

remittanceInformationUnstructured = 631%%Payment details for Goods

632

Частни трансфери за преки данъци

Private transfers for direct taxes

remittanceInformationUnstructured = 632%%Payment details for Goods

633

Частни трансфери за производствени субсидии

Private transfers of production subsidies

remittanceInformationUnstructured = 633%%Payment details for Goods

634

Частни трансфери за социални вноски

Private transfers for social contributions

remittanceInformationUnstructured = 634%%Payment details for Goods

635

Частни трансфери за социални плащания

Private transfers for social payments

remittanceInformationUnstructured = 635%%Payment details for Goods

641

Преводи по системи за експресни парични преводи (Money Gram, Western Union и др.)

Transfers by systestems for express money transfers(MoneyGram,Western Union and etc)

remittanceInformationUnstructured = 641%%Payment details for Goods

711

Преки инвестиции на местни лица в дялов капитал в чужбина

Direct investments in joint-stock capital by residents abroad

remittanceInformationUnstructured = 711%2/978/01176/003%Payment details for Goods

712

Преки инвестиции на чуждестранни лица в дялов капитал в България

Direct investment in joint-stock capital by non-residents in Bulgaria

remittanceInformationUnstructured = 712%2/978/01176/003%Payment details for Goods

721

Инвестиции на местни лица в недвижими имоти в чужбина

Investments by residents in real estate abroad

remittanceInformationUnstructured = 721%2/978/01176/003%Payment details for Goods

722

Инвестиции на чуждестранни лица в недвижими имоти в България

Investments by non-residents in real estates in Bulgaria

remittanceInformationUnstructured = 722%2/978/01176/003%Payment details for Goods

731

Портфейлни инвестиции на местни лица в ценни книжа емитирани от чуждестранни лица

Portfolio investments by residents in shares issued by non-residents

remittanceInformationUnstructured = 731%2/978/01176/003%Payment details for Goods

732

Портфейлни инвестиции на чуждестранни лица в ценни книжа емитирани от местни лица

Portfolio investments by non-residents in shares issued by residents

remittanceInformationUnstructured = 732%2/978/01176/003%Payment details for Goods

741

Инвестиции на местни лица в опции емитирани от чуждестранни лица

Investments of residents in options issued by non-re

remittanceInformationUnstructured = 741%2/978/01176/003%Payment details for Goods

742

Инвестиции на чуждестранни лица в опции емитирани от местни лица

Investments by non-residents  in options issued by residents

remittanceInformationUnstructured = 742%2/978/01176/003%Payment details for Goods

743

Покупко-продажба на финансови деривати различни от опции

Trading with financial derivatives other than options

remittanceInformationUnstructured = 743%2/978/01176/003%Payment details for Goods

744

Доход реализиран от деривати при упражняване на деривата

Income generated by derivatives

remittanceInformationUnstructured = 744%%Payment details for Goods

811

Краткосрочни кредити предоставени от местни на чуждестранни лица

Short-term loans granted by residents to non-residents

remittanceInformationUnstructured = 811%2/978/01176/003%Payment details for Goods

812

Краткосрочни кредити предоставени от чуждестранни на местни лица

Short-term loans granted by non-residents to residents

remittanceInformationUnstructured = 812%2/978/01176/003%Payment details for Goods

821

Дългосрочни кредити предоставени от местни на чуждестранни лица

Long-term loans granted by residents to non-residents

remittanceInformationUnstructured = 821%2/978/01176/003%Payment details for Goods

822

Дългосрочни кредити предоставени от чуждестранни на местни лица

Long-term loans granted by non-residents to residents

remittanceInformationUnstructured = 822%2/978/01176/003%Payment details for Goods

831

Репо операции, активи

Repo operations,assets

remittanceInformationUnstructured = 831%%Payment details for Goods

832

Репо операции, пасиви

Repo operations,liabilities

remittanceInformationUnstructured = 832%%Payment details for Goods

841

Депозитни, разплащателни и други сметки на местни лица, клиенти на банката, при чуждестранни лица

Deposits,curent and other accounts held by residents,customers of the bank, with non-residents

remittanceInformationUnstructured = 841%2/978/01176/003%Payment details for Goods

842

Депозитни, разплащателни и други сметки на чуждестранни лица небанки при местни банки

Deposits,curent and other accounts held by non-residents,not banks, with residents

remittanceInformationUnstructured = 842%2/978/01176/003%Payment details for Goods

891

Други задължения на чуждестранни към местни лица

Other duties from non-residents to residents

remittanceInformationUnstructured = 891%%Payment details for Goods

892

Други задължения на местни към чуждестранни лица

Other duties from residents to non-residents

remittanceInformationUnstructured = 892%%Payment details for Goods

900

Търговия с емисии парникови газове

Trading in greenhouse gas emissions

remittanceInformationUnstructured = 900%%Payment details for Goods

901

Временно некласифицирани постъпления от операции над 5000 лв.

Temporarily unclassified revenues for operations over 5000 BGN

remittanceInformationUnstructured = 901%%Payment details for Goods

902

Местно лице в страната, което получава от чуждестранно лице в страната

Resident who receives transfer from non-resident in the country

remittanceInformationUnstructured = 902%%Payment details for Goods

903

Чуждестранно лице в страната, което получава от местно лице в страната

Non-resident who receives from resident in the country

remittanceInformationUnstructured = 903%%Payment details for Goods

904

Операции като банка посредник

Operations as an intermediary bank

remittanceInformationUnstructured = 904%%Payment details for Goods

907

Операции по покупко-продажба на валута между банката и чуждестранно лице

Currency exchange operations between the bank and non-resident

remittanceInformationUnstructured = 907%%Payment details for Goods

908

Други операции на банката, непосочени по горе

Other operations of the bank, not specified above

remittanceInformationUnstructured = 908%%Payment details for Goods

950

Некласифицирани трансакции под 100 000

Unclassified transactions under 100 000

remittanceInformationUnstructured = 950%%Payment details for Goods