Online Banking Service

Access info
Endpoint https://online-banking-api.socrate.io/graphql
Required access keys Tenant-level service access key
Pricing Please contact us for details at contact@bitsoftware.ro
Notes To call the service, the access key must be provided in the x-api-key header of the HTTP request. If you are using the GraphQL console, you can view the service’s documentation and schema only after entering an access key. Make sure that the scope of the key allows access to the queries and mutations that you require. For example, to grant the key access to all queries and mutations, the keys’s scope must be set to online-banking-api:query:* online-banking-api:mutation:*.

Usage

The Online Banking Service enables API callers to perform the following actions:

  • obtain consent from banks on behalf of end users so that they can make real-time account balance or account transactions inquiries
  • revoke consents given previously
  • retrieve the list of banks for which the API supports balance inquiries or transactions inquiries
  • retrieve the list of bank accounts for which consent has been given by end user to make balance or transaction inquiries
  • make real-time inquiries about the balance of bank accounts, after such consent has been given by the end user
  • make real-time inquiries about transactions on bank accounts, after such consent has been given by the end user

The term “end user” above refers to a corporate (business) user. The Online Banking Service covers the authorization and balance and/or transaction inquiries for corporate (business) user accounts exclusively. Online banking for private bank accounts is not within scope.

The Online Banking Service supports the following banks or financial technology companies:

  • Alpha Bank (ALPH)
  • Banca Comercială Română (BCR)
  • BRD Groupe Société Générale (BRD)
  • Banca Transilvania (BT)
  • CEC Bank (CEC)
  • First Bank SA (FB)
  • Garanti Bank (GRT)
  • ING Bank (ING)
  • Libra Bank (LIB)
  • OTP Bank (OTP)
  • Raiffeisen Bank SA (RZB)
  • Revolut LTD (REV)
  • Unicredit Bank SA (UNC)

Prerequisites

Before using this service, the following prerequisites must be in place:

  1. Online banking must be enabled at SBS account level. To enable online banking at SBS account level, contact us.
  2. Online banking must be configured at application level. See Configure Online Banking.
  3. Online banking must be enabled at SBS tenant level. See Enable Online Banking.
  4. The organization for which online banking calls will take place must exist in SBS. You can add new organizations from the SBS Portal, or programmatically through the Organizations Service.

How it works

Before you can make any balance or transaction inquiries, consent must be given by your application’s end user to make the respective inquiries. To facilitate this, the initConsent mutation is available.

Note, however, that consent requirements (and, consequently, the input parameters to the initConsent mutation) may be different for each bank. For this reason, before running initConsent, you should first call consentRequirements. This query returns the requirements for obtaining user consent, depending on the bank code, country code, and email address supplied as input. For example, certain banks require that the caller provides in the initConsent call the list of accounts for which the user gives consent to inquire balance and/or transactions.

After you run the initConsent mutation, the response includes, among other details, a URL where your application should redirect the user so that they may give online banking consent. The URL depends on the bank and country codes supplied as input. Note that each call to initConsent creates an object of type Consent in SBS which has the status PENDING.

On accessing the URL, the user should go through all authorization steps with the respective bank in order to give consent (or perhaps decline giving consent). During the process, depending on the bank, the user may be prompted to specify the IBAN accounts to which they grant access for balance and/or transaction inquiries. At the end of the process, the user is redirected back to the URL configured in your application’s online banking settings (the so-called “callback URL”).

If the user has completed all steps and has given consent, they should see a success page at the callback URL. At this stage, the status of the consent in SBS changes to ACCEPTED. To query all available consents for a particular organization, bank and country, run the consents query.

If your app’s online banking settings are configured to use a custom (not implicit) callback URL, then you need to run the finalizeConsent mutation to finish the authorization process. In this scenario, the consent’s status will change to ACCEPTED only after you run finalizeConsent.

Once there are consents with status ACCEPTED, you can request the list of accounts for which balance and transaction inquiries are allowed, through the accounts query. Each account returned in the response provides two Boolean properties: balance and transactions. These indicate whether balance and transactions are inquirable for the account, respectively.

If there are any accounts where balance or transactions are inquirable, you can proceed to the actual balance or transaction inquiry. To make a balance inquiry, run the balance query, providing the IBAN of the relevant bank account as input. To make a transactions inquiry, run the transactions query.

Consents with status ACCEPTED will expire automatically after 90 days. If necessary, you can revoke existing consents earlier, through the revokeConsent mutation. The latter takes the consent ID as input parameter.

Queries

accounts

Retrieves a list of accounts for which consent has been given to make balance inquiries or transactions inquiries.

Arguments

Argument Type Description
organizationId ID! Mandatory. The ID of the organization for which accounts information is being requested.
filter AccountsFilter Optional. Supplies filtering criteria to the query.
AccountsFilter input
Attribute Type Description
country CountryCode Optional. If set, only accounts for this country will be retrieved. For the list of valid values, see Country codes.
bankCode BankCode Optional. If set, only accounts for this bank will be retrieved. For the list of valid values, see Bank codes.

Result

Account type
Attribute Type Description
iban IBAN The International Banking Account Number (IBAN).
currency CurrencyCode The account’s currency code. For example, RON for Romanian Lei.
country CountryCode The country code. For the list of valid values, see Country codes.
bankCode BankCode The bank code. For the list of valid values, see Bank codes.
balance Boolean A Boolean flag. If true, the balance of this account is inquirable.
transactions Boolean A Boolean flag. If true, transactions on this account are inquirable.

banks

Retrieves a list of banks for which the API supports balance inquiries or transactions inquiries.

Arguments

Argument Type Description
country CountryCode! The two-digit code of the country where the bank list should be retrieved. See Country codes.

Result

Bank type
Attribute Type Description
code BankCode The bank code. For the list of possible values, see Bank codes.
name String The bank name.
logo String The bank logo encoded as a Base64 encoded string.

balance

Retrieves balance information for the IBAN supplied as argument.

Arguments

Argument Type Description
organizationId ID! Mandatory. The ID of the organization for which balance inquiry is being requested.
iban IBAN! Mandatory. The IBAN for which balance inquiry is being requested.
creditLimitIncluded Boolean Optional Boolean flag. If true, the returned balance information will take into account the credit limit available on the account. If false, the returned balance information does not take the credit limit into account. The default value is false.

Result

Balance type
Attribute Type Description
balanceAmount Amount The available balance, expressed as an object of type Amount.
balanceType String
referenceDate Date The date of the inquiry.
creditLimitIncluded Boolean If true, the returned balance information includes the credit limit available on the account; false otherwise.
Amount type
Attribute Type Description
currency CurrencyCode The currency in which the amount is expressed. For example, RON for Romanian Lei.
amount Float The actual amount value.

consentRequirements

Returns a list of requirements that should be known to the API caller before calling initConsent. More specifically, for each combination of bank, country, and email supplied as arguments, this query returns the following information:

  • whether the initConsent query for the respective bank, country, and email requires a bankUserId as input argument
  • whether the initConsent query requires the IBAN account(s) for which consent must be obtained
  • the hub (platform) through which consent will be requested
  • whether the email address supplied as input has accepted the hub’s Terms and Conditions
  • the URL at which the end user can accept the hub’s Terms and Conditions

Arguments

Argument Type Description
input ConsentRequirementsInput! Mandatory. Provides the input data to the query, as an object of type ConsentRequirementsInput.
ConsentRequirementsInput type
Attribute Type Description
bankCode BankCode! The bank code for which the consent requirements are being requested. See Bank Codes.
countryCode CountryCode! The country code for which the consent requirements are being requested. See Country Codes.
email EmailAddress! The email address for which the consent requirements are being requested.

Result

ConsentRequirements type
Attribute Type Description
bankUserId Boolean Returns true if initConsent requires an input bankUserId; false otherwise.
accounts Boolean Returns true if initConsent requires an input accounts array; false otherwise.
hub Hub The platform (hub) through which initConsent is supported.
hubTermsAndConditionsUrl Uri The URL at which the end user may accept the hub’s Terms and Conditions.
hubTermsAndConditionsAcceptanceRequired Boolean If true, the user must accept the hub’s Terms and Conditions before initConsent is called. If false, the end user has already accepted the hub’s Terms and Conditions.

consents

Retrieves the list of consents available for the organization supplied as argument.

Arguments

Argument Type Description
organizationId ID! Mandatory. The ID of the organization for which balance inquiry is being requested.

Result

Attribute Type Description
id ID The unique identifier of the consent record in SBS.
organizationId ID The organization to which this consent belongs.
bank BankCode The bank from which this consent was requested. For the list of possible values, see Bank codes.
country CountryCode The country for which this consent was requested. For the list of possible values, see Country codes.
state String An internal value that identifies the consent state.
hub Hub The hub through which the consent was requested. Currently, the only valid value is SMARTFINTECH.
status ConsentStatus The status of the consent. Valid values: PENDING - the consent was requested but not given by the user; ACCEPTED - the consent has been given by the user; REJECTED - the consent has been rejected by the user; REVOKED - the consent has been revoked by the user.

transactions

Makes an account transactions inquiry for the organization, bank account, and period supplied as arguments.

Arguments

Argument Type Description
organizationId ID! Mandatory. The ID of the organization for which transactions inquiry is being requested.
iban IBAN! Mandatory. The IBAN for which transactions inquiry is being requested.
period PeriodInput! Mandatory. The period for which transactions inquiry is being requested.
nextToken String Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the TransactionsResult type.
PeriodInput type
Attribute Type Description
startDate Date! Mandatory. The period’s start date. For example, 2024-06-19.
endDate Date! Mandatory. The period’s end date. For example, 2024-06-20.

Result

TransactionResult type
Attribute Type Description
items Transaction The array of transactions that match the input parameters. See the Transaction type.
nextToken String If null, then the query has reached the end of the list of records that match the query criteria. If not null, then use this value in the nextToken input argument to fetch the next page.
Transaction type
Attribute Type Description
transactionId String The unique identifier of the transaction record in SBS.
entryReference String
endToEndId String
bookingDate Date
valueDate Date
transactionAmount Amount The transaction amount.
transactionType String
exchangeRate ExchangeRate
creditorName String
creditorAccount IBAN
remittanceInformationUnstructured String
proprietaryBankTransactionCode String
merchantDetails String
additionalInformation String
remittance Remittance
ExchangeRate type
Attribute Type Description
currencyFrom CurrencyCode
rateFrom Float
currencyTo CurrencyCode
rateDate Date
Remittance type
Attribute Type Description
creditorName String
creditorAccount String
debtorName String
debtorAccount String
fiscalRegistrationNumber String
transactionDetails String
cardNumber String
transactionType String
merchantName String
transactionFee String
exchangeRate String
currencyExchanged String

version

Returns the API version.

Mutations

finalizeConsent

Finalize an online banking consent that was initiated through the initConsent mutation. Finalizing a consent is required only if your app is configured to use custom online banking settings (more specifically, if a custom online banking callback URL was configured for your app).

Arguments

Attribute Type Description
internalConsentId String Mandatory. After the user completes the consent process with the bank, this value is returned in the response callback URL returned by the bank, as a URL parameter.

Result

See the Consent type.

initConsent

Initiate a consent to use online banking. The goal is to obtain the URL to which the user should be redirected in order to go through the authorization process with the respective bank. Note that the input arguments depend on the bank. To obtain the specific requirements for each bank, run the consentRequirements query first.

Arguments

Attribute Type Description
organizationId ID! Mandatory. The ID of the organization for which the consent is being initiated.
input InitConsentInput! Mandatory. This object groups together various other input parameters. See the InitConsentInput type.
InitConsentInput type
Attribute Type Description
bank BankCode! Mandatory. The bank code. For the list of valid values, see Bank codes.
country CountryCode! Mandatory. The country code. For the list of valid values, see Country codes.
email EmailAddress! Mandatory. The email address of the user that initiates the consent.
userIpAddress IP! Mandatory. The IP address of the browser/device from where the consent is being initiated.
bankUserId String Conditional, required only by some banks. The bank user ID (as provided by the bank) of the user that initiates the consent.
accounts [InitConsentAccountInput] Conditional, required only by some banks. The list of IBAN accounts for which consent is being requested.
InitConsentAccountInput type
Attribute Type Description
iban IBAN Mandatory. The IBAN number.
currencyCode CurrencyCode Mandatory. The currency of the account. Valid currency codes are according to ISO 4217.

Result

ConsentRequest type
Attribute Type Description
id ID The unique identifier of the consent request record in SBS.
organizationId ID The organization to which this consent request belongs.
bank BankCode The bank from which this consent was requested. For the list of possible values, see Bank codes.
country CountryCode The country for which this consent was requested. For the list of possible values, see Country codes.
state String An internal value that identifies the consent state.
hub Hub The hub through which the consent was requested. Currently, the only valid value is SMARTFINTECH.
status ConsentStatus The status of the consent. Valid values: PENDING - the consent was requested but not given by the user; ACCEPTED - the consent has been given by the user; REJECTED - the consent has been rejected by the user; REVOKED - the consent has been revoked by the user.
href Uri The URL to which your app should redirect the end user so that they proceed to giving consent for online banking usage.
shortHref Uri Your app may optionally redirect the user’s browser to this URL instead of redirecting to the href URL above. This is useful if your app uses implicit online banking settings. When your app uses implicit online banking settings, the callback URL to which the user is redirected after completing the online banking authorization process is provided by socrate.io and cannot be changed. For some users, this means they might not be able to access the callback URL if their organization blocks the domain socrate.io due to their security policies. To ensure that the user can indeed access the callback URL, your app should redirect the user to shortHref instead of href for online banking authorization. If shortHref is accessible, the user will be automatically redirected to href and complete the authorization process. However, if shortHref is not accessible to the end user due to some security policy in their organization, the user will see a browser error and fail the authorization process early, since it cannot be completed anyway.

revokeConsent

Revoke a previously given online banking consent.

Arguments

Attribute Type Description
id ID! Mandatory. The ID of the consent to be revoked.

Result

See the Consent type.

Appendices

Bank codes

Code Bank
ALPH Alpha Bank
BCR Banca Comercială Română
BRD BRD Groupe Société Générale
BT Banca Transilvania
CEC CEC Bank
FB First Bank SA
GRT Garanti Bank
ING ING Bank
LIB Libra Bank
OTP OTP Bank
RZB Raiffeisen Bank SA
REV Revolut LTD
UNC Unicredit Bank SA

Country codes

Code Country
AT Austria
BE Belgium
BG Bulgaria
CY Cyprus
CZ Czech Republic
DE Germany
DK Denmark
EE Estonia
EL Greece
ES Spain
FI Finland
FR France
HR Croatia
HU Hungary
IE Ireland
IT Italy
LT Lithuania
LU Luxembourg
LV Latvia
MT Malta
NL Netherlands
PL Poland
PT Portugal
RO Romania
SE Sweden
SI Slovenia
SK Slovakia
XI Northern Ireland

Sandbox credentials

The following table provides sandbox credentials for testing the consent initiation process (initConsent mutation) as an end user with each bank.

You can use the sandbox credentials if your app is configured to use the test environment for online banking (see Configure Online Banking).

Legend:

  • the Username and Password must be entered at the respective sandbox authorization page.
  • the bankUserId and Accounts are provided as input to the initConsent mutation.
  • An asterisk (*) indicates that any value is accepted on the respective sandbox.
  • A dash (-) indicates that the value is not required on the respective sandbox.

Read more

OAuth 2.0 Service Organizations Service