How to access API

In this tutorial, which is divided into three parts, we will describe step by step how to access the Best Bank API. Our goal is to obtain an Access Token to access a Best Bank user account in a sandbox environment.

Requirements to start

To access the API you need:

1. Register in Best Banking API platform

2. Register your application

3. Get an valid certificate (.cer)

API Registration

After registering and logging in, you should access the applications page. This page should contain the data for all your registered applications. To register a new application, you must click on New Application.

Create New APP

To create your first application, you will need to fill in some required information. Follow the form template and note that when creating a new application, the environment field will be filled as Sandbox. But when you are ready for production, you can request it inside the Apps Details page. After your request, Best Bank will evaluate your request and inform you of our decision by e-mail.

After registering your new application, you will be provided the respective Consumer Key and Secret Key to your application. You should save this data in a secure place, since the Secret Key will not be visible again. With the registration done, you can now access the sandbox API.

Certificate Roles

In order to have access to the API, you will need a valid certificate. These certificates will have different PSP Roles (Payment Service Provider) which will be indicative of what the partners are able to do with our API. Each of the different endpoint will list the Roles that are permitted to use it.

The existing roles are as follows:

Role Code	Role Name
PSP_AI	Account Information
PSP_AS	Account Servicing
PSP_IC	Card-Based Payment Instruments
PSP_PI	Payment Initiation

Access the API

To access the API, we used the OAuth 2.0. If you are unfamiliar with this term, we suggest a more thorough reading on the subject before proceeding.

Briefly, the purpose of the authentication flow is for your application to get an Access Token. With this Access Token, the application is allowed to perform the operations of a user. However, the user of your application must first authorize access to personal data.

To access the API there is three steps:

1. Obtain the user's authentication URL for Best Bank.

2. After the user's login, obtain the temporary code.

3. With this temporary code, obtain the Access Token.

Obtain a Login URL

In this first step, the purpose is to obtain a login URL in Best Bank environment, where the user of your application will log in, choose the bank account and the features that authorize your application to access. It's impossible to enter on Best Bank platform with just the user Login URL, it's always necessary along with the URL to send some Query String parameters used by Best Bank. Hence, the need of firstly happening what we call "handshaking" between the application and the API.

Since this is a tutorial, we will start connecting to the Sandbox of Best Banking API with a web services testing tool, such as Postman, but you can use any other tool of your choice.

Below is the endpoint we're connecting to obtain the login URL. In the testing tool, enter this address:

https://dev.openbank.bancobest.pt/sandbox/api/v2/OAuth/Initiate

Now, you need to add an authorization header. In Postman click Headers and add a parameter with a Key named "Authorization". The value of this parameter must be the access variables. What are these parameters? Let's see what they are and each function in the table below:

Variable	Example Value	Description	Mandatory?
oauth_consumer_key	0f4c0d842b0e70d42348280681...	APP Consumer Key	Yes
oauth_timestamp	1529597435	Unix Timestamp in UTC	Yes
oauth_version	1.1	API Version	Yes
oauth_signature	6YWEI87xEHTqOSXsL...	Signature that validates the header. The standard used at Best Bank is SHA256.	Yes
oauth_guid	5cc22f7f-0f39-422c-b69f-a232954c7929	Random GUID generated for the request.	Yes

It is necessary an eDAIS certificate (qSEAL). Add a parameter with a Key called "certificate". The value will be the certificate in base64 encode (this certificate has to contain the public key).

After the formatted message, the Header of a request will be very similar to the example below:

Header

Authorization:OAuth 
oauth_consumer_key=0f4c0d842b0e70d423482806812bd42657a155eb759530f4b9d4c95c81cd485c,
oauth_timestamp=1672531200,
oauth_version=1.1,
oauth_signature=5YWEI87xEHTqOSXsL%2B8mzUDKYypH6LYBt400fWek2rU%3D,
oauth_guid=5cc22f7f-0f39-422c-b69f-a232954c7929,
Certificate:9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD==

Header Authorization parameters must not have spaces after the comma.

Do remember to never share your app's private key (oauth_consumer_secret) in this Header. This field should be passed along exclusively at the signature!

You should now be able to complete the above request with your application data, the current timestamp that must be set to UTC time, the URL to return to your application.

The timestamp will be validated in order to ensure the time is being sent in UTC, and the GUID must be random and unique. A timestamp + GUID combination being repeated will result in an error. We do not allow for repeated use of signatures.

What about the oauth_signature? We will see now:

Generate signature

Generating a signature is a common process in OAuth authentication. In this tutorial we will briefly describe this process.

To generate a signature first we need to form a Base String. The Base String pattern of Best Bank API follows the following rules:

Variable	Description
oauth_consumer_key	APP Consumer Key
oauth_guid	Random GUID generated for the request.
oauth_timestamp	Unix Timestamp in UTC
oauth_version	API Version
oauth_consumer_secret	APP Secret Key (MUST BE LAST!)

ALL variables are in alphabetical order, with the exception of the APP Secret Key that will always be added to the end of the base string.

Below there is an example of a base string:

Base String

oauth_consumer_key%3D735a1cfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1%26oauth_guid%3D5cc22f7f-0f39-422c-b69f-a232954c7929%26oauth_timestamp%3D1531842924%26oauth_version%3D1.1%26oauth_consumer_secret%3D635a1cfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1

As you can see, the above message is coded. To generate a base string, you must first convert to URL encoding.

To generate a signature, we must use HMAC SHA256 along with the App Secret. In the case of the base string above, the following signature using HMAC 256 along with the App Secret (the app secret in example is: 635a1cfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1) generated this:

a453de63e7e926d29aacaec8b9a3a8976f2ed98ad12897b96874388bef949fd2

But wait, this is not the signature yet. We now have to encode it in base 64:

pFPeY+fpJtKarK7IuaOol28u2YrRKJe5aHQ4i++Un9I=

Wait, we also must to convert it to URL encoding:

pFPeY%2BfpJtKarK7IuaOol28u2YrRKJe5aHQ4i%2B%2BUn9I%3D

Now YES, we have our signature.

To continue this tutorial, build a base string adding your application data or use the example base string above.You could use this online tool to generate it. If you are testing the base string above with this tool, you should use as Key this following App Secret Key:

635a1cfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1

After the generation of the Base 64 signature, you could use this other online tool to URL Encode.

The field below its editable and might help you build a base string adapted to your application.

oauth_consumer_key%3D[YOUR APP CONSUMER KEY]%26oauth_guid%3D[GENERATED GUID]%26oauth_timestamp%3D[UNIX TIMESTAMP ATUALIZADO%26oauth_version%3D1.1%26oauth_consumer_secret%3D[YOUR APP SECRET KEY]

Return

After the base string has been generated and already having the signature, we can now proceed to the Header.

The field below its editable and might help you build a Header correctly.

Authorization:OAuth oauth_consumer_key=[YOUR APP CONSUMER KEY], oauth_timestamp=[UPDATED UNIX TIMESTAMP], oauth_version=1.1, oauth_signature=[SIGNATURE FROM THE LAST STEP], oauth_guid=[RANDOM GUID], certificate:[EDAIS CERTIFICATE'S PUBLIC KEY IN BASE64 FORMAT]

Change the method to POST and send. In case of success, a similar message to the one below will be returned:

{
    "LoginUrl": "http://www.bestbank.pt/LoginPSD2/Auth/LoginSandbox?login_token=eyJub25jZSI6ImYxODgyNTk5YjIxIiwic2NvcGUiOiJ1c2VyIiwicmVkaXJlY3RVcmwiOiJodHRwOi8vaHR0cGJpbi5vcmcvZ2V0Iiwic3RhdGUiOiJub25lMiIsIm5hbWUiOiJBcHAgUG9ydHVnYWwgU2FuZCJ9&state=none2"
}

Finally, the application should redirect the user to Best Bank login page.

We finished the first part of Best Bank authentication. We will now see the second part: Obtain a Temporary Code.

Obtain a temporary code

In the previous step we saw how to register your app and how to make the "handshaking" between the application and the API. In this step, we will obtain a temporary code.

User Redirection

In the previous step, the service returned the JSON bellow:

{
    "LoginUrl": "http://www.bestbank.pt/LoginPSD2/Auth/LoginSandbox?login_token=eyJub25jZSI6ImYxODgyNTk5YjIxIiwic2NvcGUiOiJ1c21VyIiwicmVkaXJlY3RVcmwiOiJodHRwOi8vaHR0cGJpbi5vcmcvZ2V0Iiwic3RhdGUiOiJub25lMiIsIm5hbWUiOiJBcHAgUG9ydHVnYWwgU2FuZCJ9&state=none2"
}

Variable	Description
LoginUrl	Contains the Login URL address to Best Bank, to which the application will redirecting the user.

Your application should handle the returned JSON, and redirect the user to Best Bank login page.

If you are testing your application in the Sandbox environment, the returned URL will return an environment banking page inside the sandbox. You can use your Sandbox account login to enter this testing banking environment. This login is intended to simulate a secure banking environment of Best Bank.

From this point on, your application must wait for the user to end his authentication and return from the sent URL address in the previous step to the application. At this point the user is browsing inside the bank authentication environment provided by Best Bank.

Since in this tutorial we are in a sandbox environment, you must login into the sandbox environment:

1. Before you start this process, add a virtual bank account to your Sandbox environment. After your login, inside the developer menu, select Sandbox and below the _Virtual Sandbox Bank Account click on ADD. In this field, you must define the amount of your virtual bank account and once you click on CREATE, you will get your virtual IBAN.´

2. At this moment you should access the URL returned in the previous step. If you are testing on a testing tool as we suggested in the previous step, you need to access the URL in an external browser. If your token is expired, make a new request like we did in the previous step and another login URL will be generated.

3. If your token is expired, make a new request like we did in the previous step and another login URL will be generated.

4. Login into the Sandbox environment. To login, you will need the login and password for your environment.

5. If you are already logged in, a page where you should select the bank account will show up. In this case it’s a virtual bank account, to which your application will be authorized to access.

6. Finally, you successfully logged in. Click on the Back to application button and you will be redirected to the URL address provided in this previous step.

After the login, your Sandbox environment will be as closest possible to the actual bank environment.

Return

The user's last step is to return to the address provided by the application. Upon returning, two variables will be returned via Query String.

Variable	Description
oper_id	Operation Identifier
code	Temporary code to obtain the Access Token
status	Application controlling variable, it was sent on the first request

Below there is an example of a returned URL:

http://www.myapplication.pt/Login?code=abb96157cbcc4867b60479616d4af4e2&status=none

The variable code it's a temporary code that we will be used in the next step to get the Access Token. Along with the variable code, we will get the variable status that can be used by your application and it will be returned the exact same value that was sent in the previous step.

We finally finished the second part of Best Bank authentication process. We will now see the last part: How to Obtain the Access Token. To do this, copy the code returned by the variable code and we will use it in the next step.

Obtain the Access Token

In the previous step, after the user authenticates himself inside the environment of Best Bank, we saw how to obtain a temporary code. Let's now finish the process to access the API and get the Access Token.

As it was done in the first step, we will begin connecting to the Sandbox environment of Best Bank API using a web services testing tool such as Postman, but you can use another tool of your choice.

https://dev.openbank.bancobest.pt/sandbox/api/v2/OAuth/Token

Now, we need to add an Authorization Header. So, like we did in the first step, in Postman click Headers. Add a parameter with a Key named "Authorization". In this parameter value we should have the access parameters. We need to send the following variables:

Variable	Example Value	Description	Mandatory?
code	c0d842b0e70d42348280 ...	Temporary code returned after application user authentication	Yes
oauth_consumer_key	0f4c0d842b0e70d42348280681 ...	Application Consumer Key	Yes
oauth_timestamp	1529597435	Unix Timestamp	Yes
oauth_version	1.1	API Version	Yes
oauth_guid	5cc22f7f-0f39-422c-b69f-a232954c7929	Random GUID generated for the request.	Yes
oauth_signature	6YWEI87xEHTqOSXsL ...	Signature that validates the header. The standard used on Best Bank is SHA256.	Yes
certificate	9dFpJUCnQcwe80aAOHx7...	eDAIS Certificate's Public Key in BASE64 format	Sim

With the message formatted, the Header of a request will be similiar to the example below:

Header

Authorization:OAuth 
code=a9dadedc4ea94f2da6a87be6a66e45a4,
oauth_consumer_key=835a1oicfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1,
oauth_timestamp=1672531200,
oauth_version=1.1,
oauth_guid=5cc22f7f-0f39-422c-b69f-a232954c7929,
oauth_signature=frBL78jfC5TlWOYCm62Nw8wjjtYknW2xkYqcRfyIG0U%3d
certificate:9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD==

The field below is editable and can help you mount a Header correctly according to your application.

Authorization:OAuth code=[TEMPORARY CODE PREVIOUSLY RETURNED], oauth_consumer_key=[APP CONSUMER KEY], oauth_timestamp=[UPDATED UNIX TIMESTAMP], oauth_version=1.1, oauth_guid=[GUID], oauth_signature=[SIGNATURE] certificate:[EDAIS CERTIFICATE'S PUBLIC KEY IN BASE64 FORMAT]

To get the signature, the formatted base string it's similar to the process we saw in the first step. Here is an example of a base string for this request:

Base String

code%3Dcefda5ea083a459ba1370ca8149d1dea%26%0Aoauth_consumer_key%3D835a1cfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1%26%0Aoauth_guid%3D5cc22f7f-0f39-422c-b69f-a232954c7929%26%0Aoauth_timestamp%3D1672531200%26%0Aoauth_version%3D1.1%26%0Aoauth_consumer_secret%3DSECRET835a1cfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1

The field below is editable and can help you assemble a Base String correctly according to your application.

code%3D[TEMPORARY CODE PREVIOUSLY RETURNED]%26 oauth_consumer_key%3D[APP CONSUMER KEY]%26 oauth_guid%3D[RANDOM GUID]%26 oauth_timestamp%3D[UPDATED UNIX TIMESTAMP]%26 oauth_version%3D1.1%26 oauth_consumer_secret%3D[SIGNATURE]

Return

At the end of the request it will be returned the Access Token as it is in the request below:

{
    "access_token": "0c08dbacf98549e9a552a58371a41618",
    "expires_in": 1532262026
}

Variable	Description
access_token	Access Token code
expires_in	Unit Timestamp with the validation of the Access Token

With the Access Token, we finally finished accessing the API and it is now possible to perform operations on Best Bank API.

This Access Token should be added to the 'Authorization' Header for all operation requests that are not of the "Initiate" type. (contained in the endpoint's name)

Note that only one Access Token can be active per user. When making a successfull request to this endpoint, the previously active Access Token will no longer be valid for use.

The request to endpoints that recieve an invalid Access Token return an Internal System Error described as EGEN003.

We suggest that you read the remaining documentation to learn how to use all the other available operations.