API Store Documentation V2.0
Introduction
BOC now provides PSD2 and B2B APIs that are grouped into 6 high level categories:

Pre-requisite
As a prerequisite, to use any of our APIs you must first make sure that:

When working with Sandbox APIs you use the Sign-On functionality of the portal to create a developer account. Similarly to the API-Store you log onto the portal and register your app. You may follow by subscribing to the required 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:

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 an API from the Payments/Accounts family we need to have in hand a particular Subscription Id and Access Token which are used as part of the API call. The SubscriptionID is obtained as outlined in Step 1, whilst the Access Token is obtained as indicated in Step 2.

An Access Token is valid for a few minutes and you can get it using your Client ID and Client Secret. For calling APIs within the Bank Services family only a valid Access Token is required (no need for a Subscription ID).
Payments API
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. Note that an additional API is provided for simulating the API-Store signing functionality required for payments. Follow these steps to call Payments APIs.

Payment Flow Sequence Diagram

Account API
To get Account information you need to provide the Access Token and Subscription ID. Follow these steps to call Accounts APIs

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.

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.













Test a Subscription
The following steps are needed in order to test BOC the APIs for the creation of the subscriptions. Samples are provided based on the Swagger file provided in the portal and on testing scripts in Postman.

Below you can find the link to a test suite with the steps required to test the Creation of a Subscription ID APIs. It includes HTTP requests with sample headers and test data.

Save the content of the link below as a .json file and then import it in the tool as a test collection.


These are the variables that you can use to call the APIs in Postman:

accNumber: 
subscriptionId: 
url: 
client_id: 
client_secret: 
tppId:
PmtId:
originUserId: 
journeyId: 
oauthCode2: 
oauthCode:

The rest of this document explains the steps implemented in the test suite. You can use this information as guidance for the logic you need to implement in your application to be able to create a subscription ID.

1. Obtain an access token to invoke the Payment API
In this step you use the TPP credentials to obtain the access token required to submit in each API call.

Call the POST /oauth2/token endpoint in the tppoauth2security API. The following parameters must be passed as headers in the HTTP request (Mandatory fields highlighted in Red).

Example API

Example API

Example Request in POSTMAN


The access token received will be used in all the API calls.

2. Obtain a Subscription Id
The subscription Id will be used in all the API calls. The Subscription ID must be authorized in order to be used.
Example Request

Example Request



Variables



tppId = ‘singpaymentdata’

originUserId= anything for sandbox, it must be used in all the APIs for that subscription ID

oauthCode = The authorization code provided from the oauth2 API.

Sample body
{ 
      
       "accounts": {
      
          "transactionHistory": true,
      
          "balance": true,
      
          "details": true,
      
          "checkFundsAvailability": true
      
        },
      
        "payments": {
      
          "limit": 8.64181767,
      
          "currency": "EUR",
      
          "amount": 93.21948702
      
        }
      
}     
Example Request in POSTMAN

3. Select Accounts for the Subscription Id
The following link is needed for selecting the accounts. The respective values must be entered.
Example Request



After entering the username=999999 and passcode = 112233 we get the following screen.

After selecting the accounts, the code is provided in the URL. This code is needed to be used in the authorization API.

Example Response

4. Get second Access token for the update of subscription
Example Request

Example Response

Example Request in POSTMAN

Example Response in POSTMAN

The access token will be used for the authorization of the Subscription Id.
5. Update Subscription Id
Example Request

Example Response

Example Request in POSTMAN


Example Response in POSTMAN

The access token will be used for the authorization of the Subscription Id.












Test an Account
The following steps are needed in order to test BOC the APIs for the different action on customer accounts. Samples are provided based on the Swagger file provided in the portal and on testing scripts in Postman.

Below you can find the link to a test suite with the steps required to test the following actions, it includes HTTP requests with sample headers and test data.

Save the content of the link below as a .json file and then import it in the tool as a test collection. NOTE: Link to PSD2 postman collection

These are the variables that you can use to call the APIs in Postman:

accNumber: 
subscriptionId: 
url: 
client_id: 
client_secret: 
tppId:
PmtId:
originUserId: 
journeyId: 
oauthCode2: 
oauthCode:

The rest of this document explains the steps implemented in the test suite. You can use this information as guidance for the logic you need to implement in your application to be able to do actions on customer accounts.

1. Get Accounts for specific subscription IDs
Example Request

Example Request

Example Request in POSTMAN

Example Request in POSTMAN
The response will provide the information of all the customer accounts linked to the specific subscription ID.

2. Get Accounts Details
This API will retrieve the information for specific accounts.
Example Request

Example Request

Example Request in POSTMAN

3. Get Balances API
The GetBalance API uses the same headers as AccountDetails API.

GetBalance Api sample call:

4. Get Account Statement API
The GetAccStatement API uses the same headers as the AccountDetails API.

GetAccStatement Api sample call:












Test a Payment
The following steps are needed in order to test BOC the APIs for the creation of a payment. Samples are provided based on the Swagger file provided in the portal and on testing scripts in Postman.

Below you can find the link to a test suite with the steps required to test the following actions, it includes HTTP requests with sample headers and test data.

APIs for the creation of Payment

APIs for different actions on Payments

Save the content of the link below as a .json file and then import it in the tool as a test collection. NOTE: Link to PSD2 postman collection

These are the variables that you can use to call the APIs in Postman:

accNumber: 
subscriptionId: 
url: 
client_id: 
client_secret: 
tppId:
PmtId:
originUserId: 
journeyId: 
oauthCode2: 
oauthCode:

The rest of this document explains the steps implemented in the test suite. You can use this information as guidance for the logic you need to implement in your application to be able to create a payment.

1. Sign Request (JWS_Sign_Verify APU)
When creating a payment, this must have a JWS signature; therefore we need to get first this in order to proceed with the payment.
Example Request

Example Response

Example Request in POSTMAN

Body (The information about the payment)
{
          "debtor":{
            "bankId": "",
            "accountId": "351012345671"
          },
          "creditor": {
            "bankId": "",
            "accountId": "351012345671"
          },
          "transactionAmount": {
           "amount": 3.55,
            "currency": "EUR",
             "currencyRate": "string"
          },
          "endToEndId": "string",
          "paymentDetails": "test sandbox",
          "terminalId": "string",
          "branch": "",
          "executionDate": "",
          "valueDate": ""
}
Example Response in POSTMAN

2. Create Payment
The JWS signature string will be provided on the body of the API call.
Example Request

Example Response

Example Request in POSTMAN

Example Request in POSTMAN

Example Response in POSTMAN

3. Approve Payment
The JWS signature string will be provided on the body of the API call.
Example Request

Example Response

Example Request in POSTMAN

Body
{
              "transactionTime": "1515051381394",
              "authCode": "123456"
    }
Example Response in Postman

The transaction has status CPLT.

Get Ready! Sign up, register, and you "ll be ready to go.