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) transfer
  • Single Domestic Budgetary (BGN) transfer
  • Single SEPA Credit Transfer
  • Single Foreign Payment
  • The currencies available in Sandbox for initiating single payments are: BGN, EUR, USD, JPY. 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 and available in Sandbox Test Data 
  • 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

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 i the next Sandbox release.

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.

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 Transfer, BGN Credit Transfer. Moreover, Bulgaria is non-Euro country and there are specifics in SCT EU Core to the following extended format. Please note that the extended data elements are coloured.

 

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.

Conditional

creditorAgentAddress **

Address

n.a.

n.a.

n.a.

Conditional

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

Optional

Optional

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

optional

optional

optional

optional

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

 

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

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

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

ACTC

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

after signing of payment

ACTC

on dayOfExecution and after 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

after signing of payment

ACTC (final status)

On dayOfExecution single payment out of recurring sequence is executed - no funds check is performed, if no available funds, payment is executed and balance goes into minus.

 

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
  • If already authorized, then another SCA has to be performed to authorize cancellation.

 

 Payment Status

Cancellation possible Y/N

SCA required for cancellation Y/N

RCVD

Y

N

ACTC

Y

Y

ACCP

N

-

RJCT

N

-

ACSP

N

-

ACSC

N

-

CANC

N