How to access and call our APIs?
To access and call any of our APIs, you need to first get an access token that would be used in each subsequent call to authenticate your app to BoC resources, but also a subscription id (only for Accounts and B2B API families) that will define the access rights users have for a particular resource for prescribed amount of time.
Get Access Token
To retrieve an Access Token, token API needs to be called using Client ID and Client Secret, granted on the registration process. The Access token has a short lifetime of a few minutes.
Create Subscription
Before calling any of the APIs in the Accounts and B2B Payments API families, you must ensure that you follow the ‘Create Subscription’ process. The process is essentially the BoC implementation of an OAuth 2.0 Authorization workflow which will result in the acquisition of a Subscription ID.
BoC follows OAuth 2.0 which is the industry standard for delegating authorization for accessing resources via HTTP. This enables giving access rights to services and accounts to an app without explicitly providing a password. Instead, a Subscription ID is handed to the app/service which represents the access rights for a particular resource for a prescribed amount of time.
Within a banking context, this means that users have the granularity of choice in granting access to specific accounts for specific functions.
The client app should first call the POST Subscription API which will return the Subscription ID. Once we have the Subscription ID the client app re-directs the user to BoC Web banking login screen.
The user will be requested to login to 1Bank by supplying their UserID and Passcode. Following login, authorization will be requested for the Accounts and the appropriate functionality that will be provided to the subscription. As part of this Authorization workflow the client app would be provided with a specific temporary Authorization Code which will be used to get a second access token needed for the PATCH Subscription API to activate the subscription. The PATCH Subscription API expects also the approved subscription details in the payload which the client app can retrieve using the Subscription API before calling the PATCH API.
The ‘Create Subscription’ process is described in the following sequence diagram:
Subscription Flow Sequence Diagram
NOTE: Subscription ID is valid for 180 days. For API calls you first need to get an Access Token (valid for 60mins), and along with each call you must pass the Token and the SubscriptionId. In case the subscription expires then re-send the subscription request with the same details i.e. functions and accounts to again get the consent of the customer.
Call an API
To call any API, an Access Token is required as indicated in section Get access Token. When calling APIs from the Accounts & B2B families you also need to have in hand a particular Subscription Id which is used as part of the API call. The SubscriptionId can be obtained as outlined in section Create Subscription.
You will then need to log onto the portal, register your application and subscribe to the required APIs you would like to use.
Account API
Follow these steps to test Accounts APIs.
Payments API
The payment APIs require an OAuth2 flow for authorizing a payment every time you initiate a payment as per the PSD2 Strong Customer Authorization (SCA) guidelines. The flow is similar to the subscription one above.
The client app should first call the initiate payment API with the details of the payment including the amount and the beneficiary. The ordering account is optional and in case it is not provided the customer will be asked to select it when redirected to BoC. All kinds of transfers are supported by this set of APIs including transfers within BoC, SEPA and SWIFT. Once the payment is initiated a Payment Id is returned which is passed as a query parameter when redirecting the user to BoC.
The users will be requested to login to 1Bank by supplying a UserID and a password. They will then be requested to select an ordering account if it was not provided, review the payment details and confirm the payment. As part of this Authorization workflow the Client would be provided with a specific Temporary Authorization Code which is used to get an access token and then call the POST Execute Payment API to complete the payment.
Follow these steps to test Payment APIs.
Note, that the initiate payment API requires the Client to sign the payment payload with your eIDAS QSeal Certificate and provide it as a JWS. The expected signing algorithm is RS256. JWS is a json format of JWT to be used in API payloads. You can find several libraries that do this at “https://jwt.io”. You can also find a few articles on JWS on the internet that explain this very well.
Payment Flow Sequence Diagram
B2B APIs
Using B2B payments you can initiate in one call multiple payments which can then be authorized by an appropriate signatory at a later stage using the 1Bank “Pending for Authorization Page”. There are two types of B2B payments. The first one is “Mass Payments” which can be used to initiate all kinds of transfers including transfers within BoC, SEPA and SWIFT. The other type is “Payroll/Group Transfers” which have a single ordering account for all credits and are handled as a single transaction so that only one transaction will appear in your payment account statement.
Register an application
Use "My Apps" menu to register an application. When you register an application, you need to provide the OAuth redirect URI. This is a mandatory field for the login/authentication mechanism to be able to return the oauth token back to your application.
After registering the application, a new screen will appear with the assigned unique client ID and client secret. You must verify the Client Secret by taking the value from the client secret in the beginning of the page.
Make a note of your client ID and client secret. These will be needed for your application to access the API. Some APIs need only the client id, while others (the ones that need to authenticate the end user first) need both the client id and client secret for the oauth end user authentication.
Your client secret will only be displayed once. If you forget or lose it, you can verify the secret to see if it's correct or reset it to get a new one. The verification screen will ask to enter the secret Id.
The credential screen will show the client Id and the option to reset the values.
Select a product / plan
The registered application needs to be subscribed to a plan of one or more APIs. For the first time the link to available APIs will be in the Subscription Area of the Application page.
When selecting the Available APIs, the API list screen will appear. Any API can be selected for this application.
After selecting any of the API, the subscription screen will appear to subscribe the API plan to the Application.
The subscribed API can be seen in the SUBSCRIPTION section of the Application.
All the APIs mentioned above can be found on the APIs catalogue. You can navigate to it using global tabs menu.