BOC API Guide
Introduction
BOC provides PSD2 APIs that are grouped into three main categories:
BOC also offers another four sets of B2B:
Pre-requisite
As a pre-requisite, to use any of our APIs you must first make sure that you are registered and that you have subscribed to the required APIs.
PSD2 TPPs that are authorized by any European competent authority are required to use digital eIDAS certificates (QSeal, QWAC). and can register using our Registration APIs. When calling the Registration APIs make sure that you use your eIDAS QWAC as a transport certificate. You will also need to sign the payload with your eIDAS QSeal certificate and generate a JWS which you will pass in the body.
The B2B customer can register through their banker.
PSD2 TPPs that are authorized by any European competent authority are required to use digital eIDAS certificates (QSeal, QWAC). and can register using our Registration APIs. When calling the Registration APIs make sure that you use your eIDAS QWAC as a transport certificate. You will also need to sign the payload with your eIDAS QSeal certificate and generate a JWS which you will pass in the body.
The B2B customer can register through their banker.
Future changes in the APIs
In case of changes that affect the operability of the APIs, Bank of Cyprus Ltd will notify you via an email three months prior to the changes effect date.
Registration APIs for PSD2 providers
The registration API needs the JSON body in JWS format sign with your digital eIDAS QSeal certificate.
Example Request:
Example Request:
{
"payload": "eyJkZXZlbG9wZXIiOnsiZmlyc3ROYW1lIjoiU2F2dmFzIiwibGFzdE5hbWUiOiJNaWNoYWVsIiwiZW1haWwiOiJlYXJ0aGZsYXgtZGlhc3BpZGlkYWUtdW5tb2RpZmllZEBsYW5kbWFyay5pbyIsInBob25lIjoiOTkwNTg2NzYifSwiY29udGFjdCI6eyJmaXJzdE5hbWUiOiJDaHJpc3RvcyIsImxhc3ROYW1lIjoiTmljb2xhb3UiLCJlbWFpbCI6ImNuaWNvbGFvdTFAZ21haWwuY29tIiwicGhvbmUiOiI5OTY5NTE5MSJ9LCJzaWduaW5nQ2VydGlmaWNhdGUiOiJNSUlIdmpDQ0JhYWdBd0lCQWdJUUNwZlVnSmMvSWtMdTJpNngwTmQxYS4uLi4ifQ",
"signatures": [
{
"protected": "eyJhbGciOiJIUzI1NiJ9",
"signature": "XkU8RonWMjBsrDrA9geT_UmpskDmolNx2wMKUP43Heg"
}
]
}
In case of a successful registration the developer included in the API will receive appropriate credentials via email in order to get access to the developer portal. Through the Developer portal a developer can create one or more applications and subscribe to APIs in order to use them as described below in the Register an application section
Production APIs
The documentation that follows describes how the APIs can be used with examples from the Sandbox environment where you can register for free in order to experiment with the APIs. Once you finish your implementation you can switch to the production environment by changing the base URL of the examples. The URLs are listed below
PSD2 Providers:
https://apis-secure.bankofcyprus.com/df-boc-org-prd/prod/psd2/v2
B2B Customers::
https://apis.bankofcyprus.com/df-boc-org-prd/prod/psd2
PSD2 providers must pass the eIDAS QWAC as a transport certificate with every call and they will use the eIDAS QSeal when signing payment initiation requests.
B2B providers do not need to provide a transport certificate but in case they will be requiring payments then they will need Signing Certificate. In such case during their registration they will be provided with instructions in regards to high such a certificate will be issued
PSD2 Providers:
https://apis-secure.bankofcyprus.com/df-boc-org-prd/prod/psd2/v2
B2B Customers::
https://apis.bankofcyprus.com/df-boc-org-prd/prod/psd2
PSD2 providers must pass the eIDAS QWAC as a transport certificate with every call and they will use the eIDAS QSeal when signing payment initiation requests.
B2B providers do not need to provide a transport certificate but in case they will be requiring payments then they will need Signing Certificate. In such case during their registration they will be provided with instructions in regards to high such a certificate will be issued
The BOC APIs
Get Access Token
Use this API to get an Access Token using your app Client ID and Client Secret. This token would be used in each subsequent call to authenticate your app to BOC resources. It is valid for a few minutes.
Create Subscription
Before calling any of the APIs in the Accounts and 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 banking context, this means that users have the granularity of choice in granting access to specific accounts for specific functions.
APIs called: POST Subscriptions, PATCH Subscriptions
Result: The Client acquires a Subscription ID
The client app should first call the create subscription API which will return the Subscription Id. Once we have the Subscription Id the client re-directs the user to their 1Bank login screen (browser re-direct/through application).
The user will be requested to login to 1Bank by supplying their User Name and password. Following they would then be requested to give authorization for what Accounts they would grant access and for the appropriate functionality. 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 PATCH subscription in order to activate the subscription.
The ‘Create Subscription’ process is described in the following sequence diagram:
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 banking context, this means that users have the granularity of choice in granting access to specific accounts for specific functions.
APIs called: POST Subscriptions, PATCH Subscriptions
Result: The Client acquires a Subscription ID
The client app should first call the create subscription API which will return the Subscription Id. Once we have the Subscription Id the client re-directs the user to their 1Bank login screen (browser re-direct/through application).
The user will be requested to login to 1Bank by supplying their User Name and password. Following they would then be requested to give authorization for what Accounts they would grant access and for the appropriate functionality. 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 PATCH subscription in order to activate the subscription.
The ‘Create Subscription’ process is described in the following sequence diagram:
Get Subscription Diagram
NOTE: Subscription ID is valid for 30 days For API calls you first need to get an Access Token (valid for 10mins), and along with each call you must pass the Token and SubscriptionId
Keep in mind that the Subscription ID provided is only valid for 30 days. 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. When calling APIs from the Accounts & B2B families we also need to have in hand a particular Subscription Id which is used as part of the API call.
The registration functionality outlined above is simulated within the Sandbox environment. In order to use it you will need to register as a developer. Similarly to the API-Store, you will need to log onto the portal and register your app. You may follow by subscribing to the required APIs you wish to use.
The registration functionality outlined above is simulated within the Sandbox environment. In order to use it you will need to register as a developer. Similarly to the API-Store, you will need to log onto the portal and register your app. You may follow by subscribing to the required APIs you wish to use.
Account API
To get Account information you need to provide the Access Token and Subscription ID.
Follow these Steps to try the Accounts APIs in Sandbox.
Follow these Steps to try the Accounts APIs in Sandbox.
B2B APIs
To initiate B2B payments you need to provide the Access Token and Subscription ID. With 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.
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 (add link) 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 paymentId 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 User Name 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 try the Payments API in Sandbox.
Note, that the initiate payment API requires the Client to sign the payment payload with a Digital Certificate and provide it as a JWS. In sandbox an additional API is provided for simulating the API-Store signing functionality required for payments in order to assist the developers during implementation.
The client app should first call the initiate payment (add link) 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 paymentId 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 User Name 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 try the Payments API in Sandbox.
Note, that the initiate payment API requires the Client to sign the payment payload with a Digital Certificate and provide it as a JWS. In sandbox an additional API is provided for simulating the API-Store signing functionality required for payments in order to assist the developers during implementation.
Payment Flow Sequence Diagram
Register an application
Through the "My Apps" menu you can 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 may 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.
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.
Subscribe to a 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 in order to subscribe the API plan to the Application.
The subscribed API can be seen in the SUBSCRIPTION section of the Application.
