Online Banking Service

Access info

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
• Banca Comercială Română
• BRD Groupe Société Générale
• Banca Transilvania
• CEC Bank
• First Bank SA
• Garanti Bank
• ING Bank
• Libra Bank
• OTP Bank
• Raiffeisen Bank SA
• Revolut LTD
• Unicredit Bank SA

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.

Handling authorization without a callback URL

Certain banks (currently, BRDE) use an authorization process which does not involve a callback URL at all. More specifically, when you run initConsent for such banks, there is no callback URL returned in the response. This means that your application should provide means for the user to finalize the authorization process manually.

A possible implementation of the authorization flow in this scenario could look as follows:

• When your application runs initConsent, a consent in PENDING status is created in SBS, but no callback URL is returned in the API response.

• In this case (that is, if no callback URL exists), your application’s UI should inform the user to go to their online banking app or platform and complete the authorization process at the bank. For example, your app could display for that purpose a dialog box with a text message, for example:

  You have initiated a consent process that will enable Socrate Business Services API to access your online banking information at {BANK}, if you approve it. To approve the consent, sign in to your online banking at the {BANK} website, and complete the authorization steps when prompted.

• Your application should also provide a UI that will enable the user to run the finalizeConsent mutation once they finished the authorization process at the bank. For example, your application’s UI may let the user click on a previously initiated consent in PENDING status. As a result, a dialog box would be displayed that provides a button called “Finalize consent”. Clicking this button would run the finalizeConsent mutation.

Queries

accounts

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

Arguments

AccountsFilter input

Result

Account type

banks

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

Arguments

Result

Bank type

balance

Retrieves balance information for the IBAN supplied as argument.

Arguments

Result

Balance type

Amount type

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

ConsentRequirementsInput type

Result

ConsentRequirements type

consents

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

Arguments

Result

Consent type

transactions

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

Arguments

PeriodInput type

Result

TransactionResult type

Transaction type

ExchangeRate type

Remittance type

version

Returns the API version.

Mutations

finalizeConsent

Finalize an online banking consent that was initiated through the initConsent mutation. Finalizing a consent is required in the following cases:

• your app is configured to use custom online banking settings (that is, a custom online banking callback URL was configured for your app).
• the bank for which consent was initiated does not provide a callback URL and thus you must finalize the authorization manually.

Arguments

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

InitConsentInput type

InitConsentAccountInput type

Result

ConsentRequest type

revokeConsent

Revoke a previously given online banking consent.

Arguments

Result

See the Consent type.

Appendices

Bank codes

Country codes

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.