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:
- Domestic payment (standard credit transfer in BGN): transaction currency is „BGN“ and IBAN starts with „BG*“
- SEPA payment: transaction currency is „EUR“, destination bank is SEPA reachable, all mandatory fields for SEPA payment are filled
- Foreign payment: any other payment not meeting conditions of above payments
- 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 |
|