API Integration

For the Online and Mobile Banking solution has an extensive system in place to request and receive data from external, third-party systems. The information below explains the existing developments within the solution (server libraries, functions, scripts and entities) which make up the API integration. There are examples as well for calling information about the customer, getting currency rates, getting the list of bank accounts and other data.

As a financial institution, you most likely have to map one-to-one the existing API the institution has to these explained in this chapter. A gap analysis is required.

The product development contains the server libraries that are updates each time the product is upgraded:

  • FTOS_IB_System
  • FTOS_IB_Accounts
  • FTOS_IB_Fees
  • FTOS_IB_Payments.

Behind these libraries there is a parameter that dictates what to call a Custom (then the .Custom libraries are executes with their logic) or a Mock function (and its logic).

Between the libraries FTOS_IB_System, FTOS_IB_Accounts, FTOS_IB_Fee, FTOS_IB_Payments and the libraries FTOS_IB_System.Custom, FTOS_IB_Accounts.Custom, FTOS_IB_Fees.Custom, FTOS_IB_Payments.Custom there is a liaison.

IMPORTANT!  
Modifications can be made to the .Custom libraries only.

Data Types Explained

Each request returns a response that holds data of various types:

  • dateTime ISO String, e.g., "2005-03-31T00:00:00Z"
  • uniqueIdentifier, e.g., "cec0a815-4808-4567-8d74-3914687d1ae8"
  • numeric, e.g., 1.73067
  • string, e.g., "AABAFI22XXX"

FTOS.InternetBanking_Integrations

The package FTOS.InternetBanking_Integrations contains the Server Libraries:

  • FTOS_IB_System

    general library for synchronizing dictionary, customer, currency rates, etc.

  • FTOS_IB_Accounts

    general library for synchronizing all details related to bank accounts (transactions, details, etc.)

  • FTOS_IB_Fees
  • FTOS_IB_Payments

    general library used for payment creation (bulk payments, instant payment, general payments, etc.).

Users Enrolment & Administration

API call library API EndPoints Integration Type
FTOS_IB_System.syncCustomerList /OpenApi/CallAction/FTOS_IB_GetCustomer REST API
FTOS_IB_Accounts.syncBankAccountList Accounts_AcquireAccountListSummaryData REST API
Loans_AcquireLoanListData REST API
Loans_AcquireLoanSummaryData REST API
FTOS_IB_UpdateCustomer /OpenApi/CallAction/FTOS_IB_UpdateCustomer REST API bulk sync
FTOS_IB_System.syncBankingProducts /OpenApi/CallAction/FTOS_IB_GetBankingProducts REST API bulk sync
FTOS_IB_System.getCurrencyRates System_AcquireCurrencyRates REST API

 

It searches for the customers with the information: First name, Last name, Company name, Personal ID, Company ID, Unique ID CBS, mobile phone, email.

The source: FintechOS.

Copy

Request

"{""customerName"":  
""customerIdCB"":  
""pin"":  
""companyRegNo"":  
""mobilePhone"":  }"

 

Copy

Response

"{    ""Name"": ""Jane Doe"",
    ""Accountid"": ""cec0a815-4808-4567-8d74-3914687d1ae8"",
    ""TypeId"": ""3fd3ac7a-a573-47ce-af26-930c7d0b4e00"",
    ""PIN"": ""8007302835"",
    ""CommercialRegistration"": null,
    ""MobilePhone"": ""0886470444"",
    ""Phone"": null,
    ""Email"": ""jane@mail.bg"",
    ""InboxAddress"": null,
    ""Id1"": null,
    ""Id2"": null,
    ""FiscalRegistrationNo"": null,
    ""AccountPicture"": null,
    ""FullAddress"": null,
    ""IdCardSeries"": null,
    ""IdCardSeriesNumber"": ""123456789"",
    ""IdIssueDate"": ""2005-03-31T00:00:00Z"",
    ""IdIssueInstitution"": ""МВР СОФИЯ"",
    ""FirstName"": ""DANIELA"",
    ""LastName"": ""IVANOVA-NIKOLOVA"",
    ""MiddleName"": ""STRAHILOVA"",
    ""PlaceOfBirth"": null,
    ""City"": null,
    ""AccountCountryCode"": null,
    ""UniqueID"": null,
    ""CustomerCoreBankingId"": ""100556"",
    ""CustomerCoreBankingCode"": null }"
 

It searches for the bank accounts types current accounts, saving accounts, term deposits, and loans.

The source: Core Banking System.

It synchronizes the list of customers.

The source: FintechOS.

It synchronizes the banking products. This is a scheduled job which runs at midnight, but it can be triggered manually as well.

The source: FintechOS.

It gets the currency rates for exchange. This is a scheduled job which runs at every two minutes.

The source: the Core Banking system.

Copy

Request

{"currencyCode":  }

 

Copy
"{
    ""fromCurrencyId"": ""fc9c53a8-31c6-41ff-a979-9c7788d32fb0"",
    ""toCurrencyId"": ""5c1497d0-e7c7-4f01-ab9a-fdaa2d6d0734"",
    ""exchangeDate"": ""2022-01-11T07:04:46.082Z"",
    ""exchangeRate"": 1.73067,
    ""name"": ""From USD to BGN""
}"

Homepage

API call libraryAPI EndpointsIntegration Type
FTOS_IB_Accounts.syncBankAccountList Accounts_AcquireAccountListSummaryData REST API
"Loans_AcquireLoanListData 'Loans_AcquireLoanSummaryData"  
FTOS_IB_Accounts.getAccountDataAccounts_AcquireAccountSummaryData FTOS_IB_Accounts.getAccountDataREST API
FTOS_IB_Accounts.syncBankAccountListLoans_AcquireLoanListDataREST API
Loans_AcquireLoanSummaryDataREST API
FTOS_IB_Accounts.getTransactionListAccounts_AcquireTransactionListREST API
FTOS_IB_Accounts.getTransactionDetailsAccounts_AcquireTransactionDetailsREST API
FTOS_IB_System.serverStatusSystem_ AcquireServerStatusREST API

 

It synchronizes the bank accounts types current accounts, saving accounts, term deposits, and loans.

The source: Core Banking System.

Copy

Request

"{""customerCoreBankingId"":  
""pin"":  }"

 

Copy

Response

"{    ""iban"": ""BG11BULG93101009069606"",
    ""balance"": 79.94,
    ""currencyId"": ""5c1497d0-e7c7-4f01-ab9a-fdaa2d6d0734"",
    ""accountTypeId"": null,
    ""isActive"": true,
    ""activeDebitCards"": true,
    ""accountNo"": ""1-100248"",
    ""bankId"": ""39a512df-9eaa-4b1e-b5f0-0cdbe95ceb7a"",
    ""bankCode"": ""101"",
    ""coreBankingCodeType"": ""fb10cbd8-af58-42fc-aaaa-5eba93383c32"",
    ""coreBankingCodeTypeCode"": ""1-25"",
    ""blockedAmount"": 0,
    ""total"": null,
    ""dueDate"": null,
    ""nextPayment"": null,
    ""remaining"": 79.94,
    ""openingAmount"": null,
    ""interestRate"": null,
    ""contractStartDate"": null,
    ""contractEndDate"": null,
    ""numberOfPaidInstallments"": null,
    ""numberOfRemainingInstallments"": null,
    ""dateOfLastPayment"": null,
    ""typeOfLoan"": null,
    ""tenor"": null,
    ""overDueAmount"": null,
    ""daysInOverdue"": null,
    ""lifeInsurance"": null }"
 

It synchronizes the bank accounts types current accounts, saving accounts, term deposits, and loans.

The source: Core Banking System.

Copy

Request

{"iban":}

 

Copy

Response

"{
    ""iban"": ""BG97BULG93101090278301"",
    ""balance"": 50366.54,
    ""currencyId"": ""5c1497d0-e7c7-4f01-ab9a-fdaa2d6d0734"",
    ""currencyCode"": ""BGN"",
    ""accountTypeId"": null,
    ""isActive"": true,
    ""bankId"": ""39a512df-9eaa-4b1e-b5f0-0cdbe95ceb7a"",
    ""bankCode"": ""12"",
    ""accountNo"": ""1-276130"",
    ""coreBankingCodeType"": ""fb10cbd8-af58-42fc-aaaa-5eba93383c32"",
    ""coreBankingCodeTypeCode"": ""1-25"",
    ""blockedAmountValue"": 0,
    ""calculatedInterest"": null,
    ""totalAmountAtMaturity"": null,
    ""dueDate"": null,
    ""nextPayment"": null,
    ""remaining"": null,
    ""openingAmount"": null,
    ""contractStartDate"": null,
    ""contractEndDate"": null,
    ""numberOfPaidInstallments"": null,
    ""numberOfRemainingInstallments"": null,
    ""dateOfLastPayment"": null,
    ""typeOfLoan"": null,
    ""tenor"": null,
    ""overDueAmount"": null,
    ""daysInOverdue"": null,
    ""lifeInsurance"": null
}"
 

It gets the transactions of the .

The source: Core Banking System.

Copy

Request

"{""iban"":  
""dateFrom"":  
""dateTo"":  
""countTo"":  
""bookingTypeFilter"":  
""transactionStatus"":  }"

 

Copy

Response

"{
    ""correspondentName"": """",
    ""correspondentAccount"": """",
    ""bookingType"": ""Debit"",
    ""transactionAmountInAccountCurrency"": 15,
    ""transactionCurrencyCodeInAccountCurrency"": ""EUR"",
    ""transactionCurrencyIdInAccountCurrency"": ""8cd87c03-a97a-40ed-a31f-7adcd5ed7764"",
    ""paymentBookingDate"": ""2021-12-31T00:00:00.000Z"",
    ""status"": ""Transaction is booked"",
    ""statusCode"": ""ASCP"",
    ""transactionId"": ""341-7497600-20211231-1"",
    ""valueDate"": ""2021-12-31T00:00:00.000Z"",
    ""balanceAfterCurrencyId"": ""8cd87c03-a97a-40ed-a31f-7adcd5ed7764"",
    ""balanceAfterValue"": 0,
    ""balanceBeginDayCurrencyId"": ""8cd87c03-a97a-40ed-a31f-7adcd5ed7764"",
    ""balanceBeginDayValue"": 47.47,
    ""amount"": 15,
    ""currency"": ""EUR"",
    ""currencyId"": ""8cd87c03-a97a-40ed-a31f-7adcd5ed7764"",
    ""transactionAmountLocalValue"": 29.33745,
    ""transactionAmountLocalCurrencyId"": ""5c1497d0-e7c7-4f01-ab9a-fdaa2d6d0734"",
    ""currencyRate"": 1.95583,
    ""paymentType"": ""MultipleRow"",
    ""transactionTypeValue"": 1035,
    ""transactionTypeName"": ""Автоматична такса"",
    ""remittanceInformation"": ""Месечна такса обслужване на сметка, РС,ЮЛ, с вальор 31.12.2021. Сделка тип 'Разплащателна сделка' номер '203099'.""
}"
 

It gets the transactions depiction of the .

The source: Core Banking System.

Copy

Request

{"transactionId":  }

 

Copy

Response

"{
    ""transactionId"": ""341-3177682-20191002-1"",
    ""transactionAmountCurrencyId"": ""5c1497d0-e7c7-4f01-ab9a-fdaa2d6d0734"",
    ""transactionAmountValue"": 2,
    ""transactionAmountLocalCurrencyId"": ""5c1497d0-e7c7-4f01-ab9a-fdaa2d6d0734"",
    ""transactionAmountLocalValue"": 2,
    ""currencyRate"": 1,
    ""paymentType"": ""MultipleRow"",
    ""transactionTypeValue"": 1035,
    ""transactionTypeName"": ""Автоматична такса"",
    ""debtorName"": ""Jane Doe"",
    ""debtorAccountNumber"": ""BG97BULG93101090278301"",
    ""creditorName"": """",
    ""creditorAccountNumber"": """",
    ""valueDate"": """",
    ""bookingDate"": ""2019-10-02T00:00:00"",
    ""bookingType"": ""Debit"",
    ""balanceAfterCurrencyId"": """",
    ""balanceAfterValue"": """",
    ""balanceBeginDayCurrencyId"": """",
    ""balanceBeginDayValue"": """",
    ""transactionStatus"": ""Transaction is booked"",
    ""transactionStatusCode"": ""ASCP"",
    ""document"": ""3177682"",
    ""registrationDate"": ""2019-10-02T00:00:00.000Z"",
    ""budgetTransferDetails"": {
        ""regulatoryReportType"": 0,
        ""creditorPaymentCategory"": 0,
        ""debtorPaymentCategory"": 0,
        ""documentNumber"": """",
        ""documentDate"": ""0001-01-01T00:00:00.000Z"",
        ""ultimateDebtorName"": """",
        ""taxPayerType"": ""EGN"",
        ""taxPayerID"": """",
        ""beginDate"": ""0001-01-01T00:00:00.000Z"",
        ""endDate"": ""0001-01-01T00:00:00.000Z""
    }
}"
 

It gets the status of Core Banking. It is used when the user logs in the platform. If the Core Banking is functional, the user can log in, otherwise, the system displays an idle page, and as well, it is used when initiating a payment.

The source: Core Banking System.

Copy

Response

"{""status"":  
""accountDate"":}"

List of orders

API EndpointsIntegration Type
PaymentRequests_AcquirePaymentRequestStatusREST API
PaymentRequests_AcquirePaymentRequestDetailsREST API
 

It gets the payment status.

The source: Core Banking System.

It gets the payment details.

The source: Core Banking System.

Payments

API call libraryAPI EndpointsIntegration Type
FTOS_IB_System.serverStatus System_ AcquireServerStatus REST API
   
FTOS_IB_Fees.transferSchemaFees_CalculateLocalCurrencyTransferFee REST API
Fees_CalculateForeignCurrencyTransferFee  
FTOS_IB_Accounts.getAccountDataAccounts_AcquireAccountSummaryData  
FTOS_IB_System.getParticipantBankSchemas  
 

It gets the banking date.

The source: Core Banking System.

It gets the fees for a transaction in the .

The source: Core Banking System.

Copy

Request

"{""currencyId"":
""currencyCode"":
""value"":}"

 

Copy

Request

"{""debtor""  :{""name"":  
""iban"":  }
  ""creditor"":  {""name"":  
""iban"":  }
  ""amount"":  {""currency"":  
""value"":  }
  ""schemaType"":  
""paymentSystem"":  
""detailsOfCharges"":  
""settlementType"":  }"
 

It gets the customer and the account currency based on IBAN for the beneficiary in Initializing an Intra-Bank Other Customer Payment.

The source: Core Banking System.

It gets the Bank Participants to Payment schemas for the .

The source: Core Banking System.

Copy

Resquest

{"bic":  }

 

Copy

Response

"{
    ""id"": ""f1d4ac98-3f22-4b4e-85bd-6a1e0232022b"",
    ""bic"": ""AABAFI22XXX"",
    ""target2"": ""AABAFI22XXX"",
    ""sepaEur"": null,
    ""sepaEurInstant"": null,
    ""lcyHighValueOrUrgent"": null,
    ""lcySmallValDom"": null,
    ""lcyInstant"": null
}"

Bulk Payments

API call libraryAPI EndpointsIntegration Type
FTOS_IB_Payments.validateMassPaymentRequestPaymentRequests_ValidateMassPaymentRequestREST API

FTOS_IB_Payments.createMassPaymentRequest

PaymentRequests_CreateMassPaymentRequestREST API

FTOS_IB_Payments.acquireMassPaymentRequestStatus

PaymentRequests_AcquireMassPaymentRequestStatusREST API
 

It takes the file for the bulk payment uploaded by the user and validate it in Core Banking in Initiating and Authorizing a Bulk Payment. Also to answer with the error messages in Core Banking and with the total fees.

The source: Core Banking System.

This is used for Bulk Payments, it sends the payment to Core Banking.

The source: Core Banking System.

This is the answer from Core Banking to check the status of the bulk payment.

The source: Core Banking System.

Queuing payments

API call libraryAPI EndpointsIntegration Type

FTOS_IB_Payments.createAndConfirmAgnosticPayment

PaymentRequests_CreateCreditTransferRequest REST API
PaymentRequests_CreateCurrencyTransferRequest REST API
PaymentRequests_ConfirmPaymentRequest REST API

PaymentRequests_CreateCurrencyTransferRequest

REST API

CreateBudgetTransferRequest

REST API

PaymentRequests_UtilityPaymentRequest

REST API

FTOS_IB_Accounts.getConfirmationOfFunds

Accounts_ConfirmationOfFunds

REST API
 

It sends the payment types messages to Core Banking and it is used for Instant Payments EUR, Budget Payments and Utility Payment.

The source: Core Banking System.

Copy

Request

{"transactionId":}

 

Copy

Response

"{  ""CoreBankingTransactionId"":  
""CoreTransactionStatusCode"":  
""CoreBankingExecutionDate"":  
""FTOSStatus"":  }"
 

It gets the available balance in the step .

The source: Core Banking System.

Copy

Request

"{""iban"":  
""currency"":  
""value"":}"

 

Copy

Response

"{
    ""fundsAvailability"": 1
}"

Mailbox

API call libraryIntegration Type
FTOS_IB_System.uploadMailboxMessageFintechOS
FTOS_IB_System.getMailboxMessagesFintechOS
 

It sends messages from FintechOS to the Helpdesk Queue.

It initiates mailbox message from Helpdesk to answer the client.

4 FTOS.InternetBanking_Integrations_Custom

In the deployment package named FTOS.InternetBanking_Integrations_Custom, there are the server libraries:

  • FTOS_IB_System.Custom
  • FTOS_IB_Accounts.Custom
  • FTOS_IB_Fees.Custom
  • FTOS_IB_Payments.Custom.