NAV

Introduction

   ____  _____  ______ _   _            _____ _____
  / __ \|  __ \|  ____| \ | |     /\   |  __ \_   _|
 | |  | | |__) | |__  |  \| |    /  \  | |__) || | 
 | |  | |  ___/|  __| | . ` |   / /\ \ |  ___/ | | 
 | |__| | |    | |____| |\  |  / ____ \| |    _| |_
  \____/|_|    |______|_| \_| /_/    \_\_|   |_____|

Welcome to the Banco Sabadell Open API! Our API allows you to easily access your Banco Sabadell bank account, get information about your authorized accounts and cards, get your transactions history, simulate transfers and prepare Instant Money transactions.

To know more about our developers program, please visit our Developers Portal.

Our API is RESTful, we use JSON format and OAuth 2.0 authorization.

Getting Started

Create a Banco Sabadell Account

Banco Sabadell uses API keys to allow access to the API. To start working with the API, you need to meet the following requirements:

STEP ONE. Register a bank account in Banco Sabadell.

STEP TWO. Get Banco Sabadell Online credentials.

STEP THREE. Log in with your bank account to get you API key at our Developers Portal.

Add an Application

In order to add a new app, you need to log into the Application Manager with your Banco Sabadell credentials and select “Añadir una aplicación”.

In order to use the Open API, you will have to provide Banco Sabadell the name, purpose and some extra technical information of your new applicaction which will be connect to the Banco Sabadell Open API. Once you have introduced this information, Banco Sabadell agents will contact you to validate your app.

To check the current status of your app, you can visit the Application Manager.

Try our Sample Apps

We provide you a set of example applications. They have been created to help you understantd how the resources of the API and the authentication process work.

For the moment, you can test the following dummies apps:

 
Runwards Invisibly InstaEuro FinzApp

OAuth Authorization

The Banco Sabadell’s API REST provides a series of services (resources) in order to facilitate access to different types of data concerning Banco Sabadell’s customers, so that the client application is able to integrate this information into its system. Security of data transmission and protection of user credentials (we understand a user as a person registered and with access to both the app and BS Online) will be achieved following the rules of the OAuth 2.0 protocol.

What’s OAuth?

OAuth (Open Authorization) is an open protocol which permits a secure authorisation of a standard and simple API for desktop, mobile and web apps. Through the client application, OAuth provides users access to their data while protecting their account credentials. Banco Sabadell’s API REST uses the OAuth open protocol to secure authorizations. The OAuth protocol version used is 2.0, as described in RFC6749.

What’s the Banco Sabadell’s API REST?

It is an API which uses OAuth to protect user data stored in the client application and which provides services to facilitate the transmission of information from Banco Sabadell (BS) for its integration into other systems. Below, you will find the definition of the services offered by Banco Sabadell’s API REST and the detail of its integration with the client application system. The services (resources) are exposed through REST architecture and protected by OAuth.

Authentication and Authorization

Banco Sabadell’s API REST carries out the authentication and authorisation of users of the client application without storing any credentials in the system, verifying and managing access to the requested services using tokens. It is necessary to carry out Authentication and Authorisation when the client application does not provide an access token, as well as if it has expired or it is invalid. OAuth allows multiple implementations regarding the way in which the client application obtains access to the requested resources. The Banco Sabadell’s API REST will use authentication and explicit authorisation schemes. RFC6749 defines the next flow to obtain a token using the explicit model (Authorization code grant).

Authentication Flow and EXPLICIT Authorisation

The Banco Sabadell’s API REST returns a generated code (CODE) after obtaining the authorisation to access the resources. The client application will execute a second request to the API REST with this code, jointly with other values of the call to strengthen security, in order to obtain the token to access resources later.

Use case Authentication and EXPLICIT Authorization
Actors User, client application, Banco Sabadell’s API REST, BS
Description Authenticate and authorize the user
Pre-Conditions The user is registered in the client application and BS
Post- Conditions The Banco Sabadell’s API REST returns an access token so that the user can use the resources
Main flow
A user with access to the client application and BS makes a request to access a resource, for example, to obtain account activity.
The client application detects that there is not an access token to obtain the requested resources or is invalid. The client application requests the authentication and authorization to the Banco Sabadell’s API REST.
The Banco Sabadell’s API REST verifies that there is no connection and requests the user’s login showing an authentication screen.
The user enters his/her BS authentication details (username and password) and validates them.
The Banco Sabadell’s API REST validates the data and shows an authorization screen to access accounts. The accounts need to be approved so that the Banco Sabadell’s API REST can access the data on behalf of the user.
The user approves the access
The Banco Sabadell’s API REST returns a code to the client application in order to request an access token.
The client application stores the code and requests the token.
The Banco Sabadell’s API REST receives and validates the code. The data is correct and the Banco Sabadell’s API REST generates an access token and returns it to the client application with the associated characteristics.
Alternatives
A user with access to the client application and BS makes a request to access a resource, for example, to obtain account activity.
The client application detects that there is not an access token to obtain the requested resources or is invalid. The client application requests the authentication and authorization to the Banco Sabadell’s API REST.
The Banco Sabadell’s API REST verifies that there is an existing session and shows an authorization screen to access the accounts. The accounts need to be approved so that the Banco Sabadell’s API REST can access the data on behalf of the user.
The user approves the access
The Banco Sabadell’s API REST returns a code to the client application in order to request an access token.
The client application stores the code and requests the token.
The Banco Sabadell’s API REST receives and validates the code. The data is correct and the Banco Sabadell’s API REST generates an access token and returns it to the client application with the associated characteristics.

Step 1: Detail of the request to integrate the Authentication and the EXPLICIT Authorization

The client application will redirect the user to the following URL (new lines have been inserted to facilitate reading).

https://api_bs_host/AuthServerBS/oauth/authorize? 
response_type=code& 
state=8ffdeaf9-bb78-421c-a639-491095352e77& 
redirect_uri=http://app_app_cliente_host/RESTClient/index.jsp& 
client_id=client1& 
scope=read write delete 

Detail of the request of Authentication and Authorization

Name Observations Type Restrictions
response_type Type of response returned by the authentication screen. It must contain the “code” value String Compulsory
client_id Client identifier used by the Banco Sabadell’s API REST to detect that the access is requested through the client application String Compulsory
state A random string. Used to protect from cross-site request falsification attacks. It must have a minimum length of 16 positions String Compulsory
redirect_uri Direction through which the Banco Sabadell’s API REST will return the data (in this case, the code) to the client application String Optional
scope Scope separated by a space. For example, “read write” String Optional


Step 2: Detail of the response to obtain the code

If everything is correct, the Banco Sabadell’s API REST will return a redirect to the user’s browser with the URL {redirect_uri} established in the request.

https://app_cliente_host/CLIENTE/page.jsp? 
code=i2PrWA& 
state=8ffdeaf9-bb78-421c-a639-491095352e77

Detail of the request of Authentication and Authorization

Name Observations Type Restrictions
code String which represents the code that will allow the user to request a valid access token to use the resources String Compulsory
state A random string. Used to protect from cross-site request falsification attacks. It will be the same state which appeared during the request and the client application will need to validate it String Compulsory

Step 3: Detail of the request of an access token by code

The call from the client application must be by POST and will be made through the following URL.

https://api_bs_host/AuthServerBS/oauth/token? 
grant_type=authorization_code& 
code=NVGor6UiAcGB9JShA6J2ec& 
redirect_uri=http%3A%2F%2Fvdidesa0009%3A8080%2FClientServerBS%2Fmovimiento%2Fhola 

Even if the request is POST, below you will find the query string parameters.

*Detail of the request of Authentication and Authorization *

Name Observations Type Restrictions
code String which represents the code that will allow the user to request a valid access token to use the resources String Compulsory
Grant_type Type of permission the client needs to request the access token by code. It must have “authorization_code” value String Compulsory
redirect_uri Address through which the Banco Sabadell’s API REST will return the data to the client application. This URL must be the same used when the authorization was requested String Optional
scope Scopes separated by “/” String Optional

In addition to the data showed in the URL, the header specifies the authentication of the client application within the parameter “Authorization: Basic…”. See section 5.1 Authentication of the client application using a OAuth server.

It is nos possible to send client_id and client_secret via POST and, therefore, an error will appear.

The user must specify that the format of the response needs to be JSON. In order to do it, it is necessary to insert “Accept” in the header with the value “application/json”.

Step 4: Detail of the response to obtain an access token

If everything is correct, the Banco Sabadell’s API REST will return the access token with JSON format. JSON will be returned as a part of the body of the response.

JSON would be the following (new lines have been inserted to facilitate reading).

{ 
    "access_token":"f0992f25-9c05-4e6e-b7bf-602c37c386a2bbd79d48-07f9-4522-9b25-fb326d93e99465a2b965-9e4f-4d5f-9fd9-526f43fd034e", 
    "token_type":"bearer", 
    "refresh_token":"933826eb-0efa-4727-8a0f-6a651cf5982c", 
    "expires_in":99, 
    "scope":"read write", 
    "client_id":"client1" 
}

Detail of the request of Authentication and Authorization

Name Observations Type Restrictions
access_token String which represents the valid access token to use the resources String Compulsory
token_type Type of token that is being used. In this case, the value is “bearer”. String Compulsory
refresh_token String which represents the refresh token needed to negotiate a new access token with an OAuth server. It cannot appear if it is not allowed for the client String Optional
expires_in Value in seconds which indicates the time during which the token will be valid to access the resources String Compulsory

Authentication Screen

In the Authentication screen, the user will insert its username and password and will indicate if he/she accesses as an individual (Personal) or a company (Business).

Once the login is successful, there will be the following possibilities:

Authorization Screen

Once the user has logged in and the authentication is successfully created, he/she has to pass the authorization screen in order to allow or deny the Banco Sabadell’s API REST to access the resources on his/her behalf.

The user can access the Account Settings through the authorization screen.

Once the user accepts the authorization, the Banco Sabadell’s API REST will return the code to the URL provided by the client application and the process to obtain a valid OAuth token will start.

If the user denies the authorization, the Banco Sabadell’s API REST will return the refusal to the URL provided by the client application, as defined in the OAuth 2.0 standard (access denied).

Refresh Token

The Banco Sabadell’s API REST allows to refresh the tokens following the standard established by RFC6749 in section 6. This mechanism permits to obtain a new valid token once it expires through a refresh_token.


The call from the client application will be made through the following URL.

https://api_bs_host/AuthServerBS/oauth/token

In the same request, the following parameters will be sent by POST.

grant_type=refresh_token& 
refresh_token=valor_de_refresh_token

Detail of the request of Authentication and Authorization

Name Observations Type Restrictions
grant_type It must have “refresh_token” value. String Compulsory
refresh_token The refresh_token from which to obtain a new access_token and a refresh_token (if needed) String Compulsory

In addition to the data showed in the URL, the header specifies the authentication of the client application within the parameter “Authorization: Basic…”. See section 5.1 Authentication of the client application using a OAuth server.

Even if the OAuth 2.0 standard allows to send the client_id and client_secret parameters by POST also to authenticate the client application, the Banco Sabadell’s API REST will not permit it and will return an error as if nothing had been sent.

Banco Sabadell will be able to deny the use of the refresh_token while working in the production period with client applications. In this case, the process to obtain an access_token will not return the refresh_token associated and the client application will need to request the authorization again once the access token expires.

Permissions Settings

The account setting is the process in which the user authorizes the Banco Sabadell’s API REST to obtain the data of his/her accounts on his/her behalf.

This process can not be accessed explicitly from the client account, it is implied in the authentication and authorization process. It will be accessed in the following cases:

  1. The authentication process detects that it is the first time the user accesses the Banco Sabadell’s API REST (main flow).

  2. In the authorization process there is a link to access the account settings (Alternative 1).

If the client application does not request access to products (because it is not going to use any functionality which requires products), the user will not find the account settings option during the authentication/authorization process.

Use case  Account settings
Actors   User, client application, Banco Sabadell’s API REST, BS
Description Configure user accounts within the Banco Sabadell’s API REST
Pre-Conditions  The user is registered in the client application and BS
The user has one or more BS accounts
Post-Conditions The Banco Sabadell’s API REST registers in its system the settings of the authorization to access accounts
Main flow 
A user with access to the client application and BS makes a request to access a resource, for example, to obtain account activity.
The client application detects that there is not an access token to obtain the requested resources or is invalid. The client application requests the authentication and authorization to the Banco Sabadell’s API REST.
The client application verifies that there is not an existing session and requests the user’s login showing an authentication screen.
The user inserts his/her BS authentication details and validates the information.
The Banco Sabadell’s API REST validates the details and that it is the first time the user accesses the system.
Alternatives 1
A user with access to the client application and BS makes a request to access a resource (For example, obtain account activity).
The client application detects that there is not an access token to obtain the requested resources or is invalid. The client application requests the authentication and authorization to the Banco Sabadell’s API REST.
The Banco Sabadell’s API REST verifies that there is an existing session and shows an authorization screen to access the accounts. The user needs to approve the accounts so that the Banco Sabadell’s API REST can access the data on his/her behalf. The user can access the account settings following a link which can be found in the upper side of the screen.

Account settings screen

In the account settings screen, the user can indicate which accounts wishes to authorize, so that the Banco Sabadell’s API REST can access his/her resources on his/her behalf.

If the user modifies the accounts settings and saves the changes, a new screen to sign the transaction with BS credentials (code card) will appear.

The “Continuar” button validates the user’s signature. If the validation is incorrect, the same screen will appear.

Connectivity and Environment

Below, you will find the data related to the environments available within the Banco Sabadell’s API REST.

api_bs_host: it refers to the URL needed to use the services provided by the Banco Sabadell’s API REST.

app_cliente_host: it refers to the address to which the Banco Sabadell’s API REST will return the data to the client application. This host will be defined by the client application.

Environments

Developer environment

api_bs_host: developers.bancsabadell.com
client_secret: it will be sent by Banco Sabadell"

Production environment

api_bs_host: You will be notified by Banco Sabadell once the application is reviewed.
Client_secret: It will be generated by Banco Sabadell and will be reported to the technical manager of the application.

REST Resources

Below, you will find the description of the currently existing services (also known as resources) and everything related to their functioning and proper use.

OAuth. Scopes and resources

As defined in the OAuth 2.0 protocol, all the services are associated with a scope of operations. It will be documented to which scope of operations belongs each resource and, therefore, which scope must authorize users so that clients can access it.  

Existing scopes

These are the currently existing scopes:

Versioning

For example, if we want to access the account inquiry service using version V1.0.0, the call would be:

https://developers.bancsabadell.com/ResourcesServerBS/oauthservices/v1.0.0/cuentasvista

API Versioning

The version number must be specified in all the requests to the API. All services include the version number in which they are available.

The current version of the API is v1.0.0  

HeadResponse con campo warnCode=“WARN-API-DEPRECATED”

Deprecated versions of the API

The API will support deprecated versions although the same waning code WARN-API-DEPRECATED will appear in the HeadResponse.

Non-existent versions of the API

If we access the API with non-existent versions, an error will appear in the HeadResponse header.

Initial version of the availability of services

All services offered by the API include the version number in which they are available. If we try to access a service in a newer version than the one in which it is available, an error will appear in the HeadResponse header.

Delegated Login Service (ID number and name)

This service allows the user to confirm that he/she is registered in BS and to obtain its basic personal information. The client application is able to delegate its login to Banco Sabadell through this service.

Use case Query
Actors The user is registered in BS.
Description The user is client of BS Online. He/she uses the client application and it delegates the login management to the Banco Sabadell’s API REST.
Pre-conditions The client application obtains the URL to which redirect the user with its login details.
Post-conditions Carries out the user confirmation in BS and queries basic information.
Main flow
A user with access to the client application and BS wants to access as a registered user. The client application request to the Banco Sabadell’s API REST the client confirmation process to give him/her access.
The client application must have a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested data.
The Banco Sabadell’s API REST receives the call and validates that the access token and the authorization are correct.
The Banco Sabadell’s API REST obtains the data and returns it to the client application.
Once it has received the data, the client application will confirm the identification.
Alternatives 1
A user with access to the client application and BS wants to access as a registered user. The client application request to the Banco Sabadell’s API REST the client confirmation process to give him/her access.
The client application has an access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested data.
The Banco Sabadell’s API REST receives the call and indicates that the access token is invalid.
The Banco Sabadell’s API REST informs the client application that the transaction is not authorized.
The client application can not confirm the identification.

Details of the request: Query client’s basic data (ID number and name)

The call from the client application will be made through the following URL:

https://api_bs_host/ResourcesServerBS/oauthservices/{versionApi}/customerverification

REST request Metadata

Method: GET

OAuth scope: auth

Available in version: v1.0.0

Parameters not needed for this service. The request will be made using GET. In addition to the data contained in the request, in order to use the resource (access token), the information related to OAuth 2.0 protocol needs to be sent through the mechanisms detailed in RFC6749.

Detail of the response to: Query client’s basic data (ID number and name)

The response is composed of a general structure with information about the transaction (HeadResponse) and, on the other hand, a specific structure of the transfer simulation surrounded by another one specific to “auth” transactions (Data<ElementosOperacion<UsuarioBase>>). It returns in UTF-8 codification.

Below you can find each element of the response detailed: ServiceOauthResponse: entity which contains the response.

Name Observations Type Restrictions
HeadResponse Client identifier of the client application String Compulsory

Data <T>

Identifier of the entity code String Compulsory

HeadResponse: entity which represents the general information of the response.

Name Observations Type Restrictions
codigoServicio “SERV_CBS001” String Compulsory
fechaOperacion Date of transaction. Format [yyyy-MM-dd HH:mm:ss] Date Compulsory [yyyy-MM-dd HH:mm:ss]
error* Error code String Optional
descripcionError Error description String Optional
warn Warn code String Optional
informacionAdicional Additional information String Optional

* Errors can be:

General Codes

Code Description
OK Correct result
KO Unexpected general error

An example of JSON response:

{ 
    "data": 
        { 
            "datosOperacion": 
                { 
                    "id": 1430,
                    "numeroPersonal": 12345678,
                    "nif": "00000001R",
                    "nombre": "&JNOMBRE W01481544 &RPRIAPE J0"
                }
        },
    "head":
        {
            "fechaOperacion": "2014-09-02 14:50:18",
            "codigoServicio": "SERV_CBS001" 
        } 
} 

Data: entity which represents information referring to the request made by the client. In this case, it follows a ElementosOperación structure type UsuarioBase with the data entered by the user, commissions, a unique code to identify the transaction and the URL to redirect the user.

Data< ElementosOperacion< UsuarioBase >>

Name Observations Type Restrictions
id User ID in API BS Long Compulsory
nif USER ID number String Compulsory
numeroPersonal Personal number String Compulsory
nombre Nombre String Compulsory

Get User’s Products

The client application would be able to obtain information on user’s products. The Banco Sabadell’s API REST will return as a result of this transaction information about the products the API REST has been authorized to access on behalf of the user.

Use case Query
Actors The user, the client application, the Banco Sabadell’s API REST
Description Obtain global position
Pre-conditions The user is registered in the client application and BS
The user has one or more accounts in BS
Post-conditions The client application receives the information about the accounts authorized from the Banco Sabadell’s API REST
Main flow
A user with access to the client application and BS requests to obtain the products to which he/she has given access from the client application. This flow can also be started by own initiative from the client application (for example, to show the user a pull-down menu with his/her products in order to query the list of transactions of one of them).
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested data.
The Banco Sabadell’s API REST receives the call and validates that the access token and the authorization are correct.
The Banco Sabadell’s API REST obtains the authorized accounts and returns them to the client application.
The client application receives the information about the authorized accounts.
Alternatives
A user with access to the client application and BS requests to obtain the products to which he/she has given access from the client application. This flow can also be started by own initiative from the client application (for example, to show the user a pull-down menu with his/her products in order to query the list of transactions of one of them).
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested data.
The Banco Sabadell’s API REST receives the call and indicates that the access token is invalid.
The Banco Sabadell’s API REST informs the client application that the transaction is not authorized.
The client application will initiate an authentication and authorization process to obtain a valid access token.

Service request to obtain all the products

The call from the client application will be made through the following URL:

https://api_bs_host/ResourcesServerBS/oauthservices/{versionApi}/productos

In addition to the data contained in the request, in order to use the resource (access token), the information related to OAuth 2.0 protocol needs to be sent through the mechanisms detailed in RFC6749.

REST request Metadata

Method: GET

OAuth scope: read

Available in version: v1.0.0


Service request to obtain only accounts

The call from the client application will be made through the following URL:

https://api_bs_host/ResourcesServerBS/oauthservices/{versionApi}/cuentasvista

REST request metadata

Method: GET

OAuth scope: read

Available in version: v1.0.0

In addition to the data contained in the request, in order to use the resource (access token), the information related to OAuth 2.0 protocol needs to be sent through the mechanisms detailed in RFC6749.


Service request to obtain only credit cards

The call from the client application will be made through the following URL:

https://api_bs_host/ResourcesServerBS/oauthservices/{versionApi}/tarjetas

In addition to the data contained in the request, in order to use the resource (access token), the information related to OAuth 2.0 protocol needs to be sent through the mechanisms detailed in RFC6749.

REST request metadata

Method: GET

OAuth scope: read

Available in version: v1.0.0

Services response to products query

The response is composed of a general structure with information about the transaction (HeadResponse) and another with specific information on the products (Data<List<CuentaControllerJB>>). The response to all the services of products query has the same format. It returns in UTF-8 codification.

ServicioOauthResponse

Name Observations Type Restrictions
HeadResponse Client identifier of the client application String Compulsory
Data<T> Identifier of the entity code String Compulsory

HeadResponse

Name Observations Type Restrictions
codigoServicio “SERV_CUE01” String Compulsory
fechaOperacion Date of transaction. Format [yyyy-MM-dd HH:mm:ss] Date Compulsory
errorCode * Error code String Optional
descripcionError Description of the error String Optional
warn Warn code String Optional
informacionAdicional Additional information String Optional


* errorCode can be:

General Codes

Code Description
OK Correct result
KO Unexpected general error

Data<List<CuentaControllerJb>>

An example of JSON response:

{ 
    "data":[ 
        { 
            "propietario":"&UPJURID - &LPJURID", 
            "disponibilidad":null, 
            "descripcion":"CUENTA CORRIENTE", 
            "usuario":"00000001R", 
            "iban":"ES00810000000000000000", 
            "balance":"123.915,06", 
            "producto":"CC", 
            "numeroProducto":"00810000000000000000",
            "numeroProductoCodificado":"00810000000000000000" 
        }, 
        { 
            "propietario":"&RNOMBRE &DPRIAPE I &. &MPRIAPE",
            "disponibilidad":null, 
            "descripcion":"CUENTA EXPANSIÓN", 
            "usuario":"00000001R ", 
            "iban":"ES00810000000000000001", 
            "balance":"27.912,74", 
            "producto":"CC",
            "numeroProducto":"00810000000000000000",
            "numeroProductoCodificado":"00810000000000000000"
        }
    ], 
    "head":
        { 
            "fechaOperacion":"2014-03-25 11:00:05",
            "descripcionError":null, 
            "informacionAdicional":null, 
            "codigoServicio":"SERV_CUE01", 
            "errorCode":null, 
            "warnCode":null 
        } 
}
Name Observations Type Restrictions
propietario Name and surname or business name of the account owner String Compulsory
usuario ID number of the account owner    
disponibilidad Type of availability of the account (TOTAL, QUERY…)  String Compulsory
descripción Description of the account String Optional
Iban International identifier of a bank account String Compulsory
balance Available balance String Compulsory
currency Currency code in ISO4217. For example, Euro = “EUR” String Compulsory
numeroProducto Product number. It is the unique product code to use the resources associated with the product. For example, this field indicates a unique code in cards. String Compulsory
numeroProductoCodificado Codified product number. It is the product number which can be shown to the users of the client application. For example, for accounts it would be CCC (20 digits) and for cards it is the one associated with the card, as shown in BS Online (1234_________1234). String Compulsory
producto  “TC”: CARDS
“PR”: LOANS
“CR”: CREDITS
“CC”: SIGH_ACCOUNTS
“ITF”: FIX_TERM_DEPOSITS
“VA”: VALUES
“VR”: FINANCIAL_ASSETS
“FN”: INVESTMENT_FUNDS
“VF”: INTERNATIONAL_INVESTMENT_FUNDS
“SGx”: INSURANCES
“PP”: PENSION_PLAN
“HP”: LIFE_INSURANCE_SAVINGS
String Compulsory

Account Activity

Using the client application, the user can import the activity of his/her BS accounts. According to the reported parameters, it is possible to sort the activities we want to obtain (the current month, from X date to X date, from X amount to X amount…).

Use case Obtain client’s account activity
Actors The user, the client application, the Banco Sabadell’s API REST, BS
Description Obtain the activity of a user’s BS account through the client application
Pre-conditions The user is registered in the client application and BS
The user has a BS account or more
Post-conditions The client application receives the activity of the account requested by the user
Main flow
A user with access to the client application and BS requests the activity of a specific account through the client application.
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested data.
The Banco Sabadell’s API REST receives the call and validates that the access token and the authorization are correct.
The Banco Sabadell’s API REST obtains the account activity and returns it to the client application. 
The client application receives the account activity.
Alternatives 1
A user with access to the client application and BS requests the activity of a specific account through the client application.
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested data.
The Banco Sabadell’s API REST receives the call and indicates that the access token is incorrect.
The Banco Sabadell’s API REST informs the client application that the transaction is not authorized.
The client application will initiate an authentication and authorization process to obtain a valid access token.

Detail REST service to obtain account activity by date

The call from the client application will be made through the following URL:

https://api_bs_host/ResourcesServerBS/oauthservices/{versionApi}/cuentasvista/{CCC}/movimientos

Filtering by date:

https://api_bs_host/ResourcesServerBS/oauthservices/{versionApi}/cuentasvista/{CCC}/movimientos ? 
fechaDesde=dd-mm-yyyy& 
fechaHasta=dd-mm-yyyy

The following call will also be available:

https://api_bs_host/ResourcesServerBS/oauthservices/{versionApi}/cuentasvista/{CCC}/movimientos ? 
fechaDesde=dd-mm-yyyy& 
fechaHasta=dd-mm-yyyy& 
importeDesde=100& 
importeHasta=200& 
tipoCargo=C& 
concepto=00& 
referencia=0

Request to obtain account activity

This call will return the account activity for the current month. In addition to this call, there are different optional parameters which can be implemented when needed.

REST request metadata

Method: GET

OAuth scope: read

Available in version: v1.0.0

Name  Observations Type Restrictions
cuenta It is necessary to specify the account to get its activity. It is a 20-digit account code which can be found in the output of products query, with product type “CC” and field “numeroProducto” String Compulsory
fechaDesde Desired start date to obtain account activity String {dd-mm-yyyy} Optional
fechaHasta Desired end date to obtain account activity String {dd-mm-yyyy} Optional
importeDesde Amount from (it must be positive with two decimals). Format 00000,00 String Optional
importeHasta Amount to (it must be positive with two decimals and greater than importeDesde). Format 00000,00 String Optional
tipoCargo Transaction type (“C” Charge/“A” Credit) String Optional
concepto Concept (00 will be sent automatically) String Optional
referencia  Reference (0 will be sent automatically) String Optional

Possible **concepto* values can be:

Value Description
00 Any concept
02 NOTES - DELIVERIES - INCOME
05 AMORTIZATION OF LOANS, CREDITS, ETC
98 ENTRY CANCELLATIONS - CORRECTIONS
11 ATM
10 GASOLINE CHEQUES
14 REFUNDS AND NON-PAYMENTS
08 COUPON DIVIDENDS – COMITTEE BONUS - AMORTIZATIONS
03  DIRECT DEBIT - INVOICES – INSTALMENT CONTRACT – ACCOUNT PAYMENTS
04 BANK GIRO - TRANSFERS – TRANSFER FEE - CHEQUES
17 INTEREST RATE - COMMISSIONS – SAFE-KEEPING - EXPENSES AND TAXES
03 PAYSLIPS – SOCIAL INSURANCE
09 STOCK MARKET OPERATIONS AND/OR BUYING /SELLING OF SHARES
13 FOREIGN TRANSACTIONS
06  BILL OF EXCHANGE REMITTANCE
07  SUBSCRIPTIONS – CAPITAL CALL - EXCHANGES
01 CHEQUES - REPAYMENTS
12 CREDIT CARDS – DEBIT CARDS
16  REVENUE STAMP - BROKERAGE – TAX STAMP
99 OTHERS

Furthermore, the data regarding the requested resource must be entered in the header of the HTTP request:

Accept:application/json, text/javascript, */*; q=0.01 Authorization:Bearer 2f56c622-4fb2-4948-bbd9-f40ccc84f92f (valor access_token)

Details of the response: account activity query

The response (ServiceOauthResponse) is composed of a header (HeadResponse) and of the data included in the response (Data). In this case, Data is a list of “Movimientos”. It returns in UTF-8 codification.

Each element of the response is detailed below:

ServiceOauthResponse: entity which contains the response.

ServiceOauthResponse

Name  Observations Type Restrictions
head Order number of transaction HeadResponse Compulsory
data Date of transaction  List<Movimiento> Compulsory

HeadResponse: entity which represents general data of the response.

HeadResponse

Name  Observations Type Restrictions
codigoServicio Code which identifies the type of service and access to the resource.
Can have three values:
SERV_MOV01 -> By data. Current month
SERV_MOV02 -> Next page
SERV_MOV03 -> With advanced filters
String Compulsory
fechaOperacion Date of transaction. Format [yyyy-MM-dd HH:mm:ss] Date Compulsory
errorCode* Error code during service Boolean Optional
descripcionError Description of the error occurred during the service String Optional
warnCode Warn code Boolean Optional
InformacionAdicional Additional information gathered during the service String Optional

Possible **errorCode* can be:

General Codes

Code  Description
OK Correct result
KO  Unexpected general error

Data: entity which represents the data referring to the requests made by the client. In this case, it is an activity list.

Activity

Name  Observations Type Restrictions
numOrden Order number of transaction String Compulsory
fechaOperacion  Date of transaction. Format YYYY-MM-DD HH:MM:SS Date Compulsory
fechaValor  Date of transaction value. Format YYYY-MM-DD HH:MM:SS  Date  Compulsory
importe  Cost of the activity. Format [-] 0.000,00  Double Compulsory
divisa Currency of the activity  String   Compulsory
saldo Final balance of the account after the transaction. Format 0.000,00  Double  Compulsory
concepto Activity concept  String Optional
codigoConcepto Concept code. See above the table of possible values for the concept  String  Optional

Request for pagination of activity:

If in the response header (HeadResponse) appears the field warnCode with the value “WARN-MOV-001”, it means that there are more activities to show than the ones requested. In this case, the client can make a request to obtain the activity page in the following way:

https://api_bs_host/ResourcesServerBS/oauthservices/{versionApi}/cuentasvista/{CCC}/movimientos ? page=next

As it can be observed, it is not necessary to translate the filter parameters again, as we are paginating the query associated with the host session corresponding to the previous request.

Card Activity

The user can import his/her BS cards activity through the client application.

Use case Obtain account activity
Actors  User, client application, Banco Sabadell’s API REST, BS
Description Obtain the card activity of a BS user in the client application
Pre-conditions  The user is registered in the application and BS
The user has a BS card or more
Post-conditions The client application receives the card activity requested by the user
Main flow  
A user with access to the client application and BS requests the activity of a specific card through the client application.
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested data.
The Banco Sabadell’s API REST receives the call and validates that the access token and the authorization are correct.
The Banco Sabadell’s API REST obtains the card activity and returns it to the client application.
The client application receives the card activity.
Alternatives 1 
A user with access to the client application and BS requests the activity of a specific card through the client application.
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested data.
The Banco Sabadell’s API REST receives the call and indicates that the access token is incorrect.
The Banco Sabadell’s API REST informs the client application that the transaction is not authorized.
The client application will initiate an authentication and authorization process to obtain a valid access token.

Detail of the REST service to obtain the card activity

The call from the client application will be made through the following URL:

https://api_bs_host/ResourcesServerBS/oauthservices/{versionApi}/tarjetas/{cardNumber}/movimientos? 
order={A/D}

Detail of the request to obtain the card activity

REST request metadata

Method: GET

OAuth scope: read

Available in version: v1.0.0

Name  Observations Type Restrictions
cardNumber It is necessary to specify the card identifier to get its activity. It is a code which can be found in the output of products query, with product type “TC” and field “numeroProducto” String Compulsory
order  Optional. Organized by date. If it is not defined, the activity will be classified in descending order String {‘A’: Ascendente; ’D’: Descendente} Optional

Furthermore, the data regarding the requested resource must be entered in the header of the HTTP request:

Accept:application/json, text/javascript, */*; q=0.01 Authorization:Bearer 2f56c622-4fb2-4948-bbd9-f40ccc84f92f (valor access_token)

Detail of the response to obtain the card activity

The response (ServiceOauthResponse) is composed of a header (HeadResponse) and the data included in the response (Data). In this case, Data is a “Tarjeta” structure with a list including the details of each transaction. It returns in UTF-8 codification.

Each element of the response is detailed below:

ServiceOauthResponse: entity which contains the response.

ServicioOauthResponse

Name  Observations Type Restrictions
HeadResponse Client identifier in the client application  String Compulsory
Data<T> Entity identifier code String  Compulsory

HeadResponse: entity which represents the general data of the response.

HeadResponse

Name  Observations Type Restrictions
codigoServicio Code which identifies the type of service and access to the resource. “SERV_MTA01” String Compulsory
fechaOperacion Date of transaction. Format [yyyy-MM-dd HH:mm:ss] Date Compulsory
errorCode*  Error code during the service  Boolean  Optional
descripcionError Description of the error occurred during the service String  Optional
warnCode  Warn code  Boolean   Optional
InformacionAdicional  Additional information gathered during the service  String  Optional

*Possible errorCode can be:

General Codes

Code  Description
OK  Correct result
KO Unexpected general error
{ 
    "data" : [
        { 
            "contrato" : "00000000000009", 
            "cuentaRelacionada" : "00810000000000000002", 
            "estado" : "", 
            "fechaLiquiActual" : "2014-02-14 00:00:00", 
            "fechaProxiLiquidacion" : "2014-04-05 00:00:00", 
            "formaPargoMensual" : "03", 
            "ibanBic" : " / ", 
            "importeTotal" : "1.647,62", 
            "importeTotalLiquidar" : "1.647,62", 
            "limiteAutorizado" : "300,00", 
            "limiteCredito" : "1.700,00", 
            "operPeriodActual" : "1.647,62", 
            "saldoAplazadoAnterior" : "0,00", 
            "saldoDisponible" : "1.674,75", 
            "saldoDispuesto" : "325,25", 
            "totalOperPendLiquiActual" : "1.647,62",
            "totalOperPendProxiLiquidacion" : "0,00", 
            "totalOperProximLiquidacion" : "0,00", 
            "detalleMesActual" : [
                { 
                    "concepto" : "XXXXXXXXXXXXX", 
                    "fecha" : "2013-12-02 00:00:00", 
                    "importe" : "12,25", 
                    "poblacion" : "OFICINA 0901" 
                },
                { 
                    "concepto" : "XXXXXXXXXXXXX", 
                    "fecha" : "2013-11-29 00:00:00", 
                    "importe" : "88,00", 
                    "poblacion" : "OFICINA 0901"
                }
            ]
        }
    ], 
    "head" : [
        { 
            "fechaOperacion" : "2014-02-19 12:37:02", 
            "descripcionError" : null, 
            "informacionAdicional" : null, 
            "codigoServicio" : "SERV_MTA01", 
            "errorCode" : null, 
            "warnCode" : null 
        } 
    ]   

} 

Data: entity which represents the data referring to the request made by the client. In this case, it is a “Tarjeta” structure (with a list of transactions):

Data<Tarjeta>

Name Observations Type Restrictions
contrato Contract number String  Compulsory
cuentaRelacionada Associated account String  Compulsory
ibanBic IBAN / BIC String  Compulsory
limiteCredito Limit of credit. Format 0.000,00 String Compulsory
limiteAutorizado Authorized limit. Format 0.000,00  String   Compulsory
formaPagoMensual Monthly payment method String  Compulsory
Estado Card status  String Compulsory
fechaLiquiActual Date of current liquidation  Date Compulsory [yyyy-MM-dd HH:mm:ss]
totalOperPendLiquiActual Total of transactions to liquidate  String Compulsory
fechaProxiLiquidacion Date of next liquidation  Date  Compulsory [yyyy-MM-dd HH:mm:ss]
totalOperPendProxiLiquidacion Total of transactions pending in the next liquidation String Compulsory
saldoDispuesto Drawn balance. Format 0.000,00  String  Compulsory
saldoDisponible Available balance. Format 0.000,00  String  Compulsory
operPeriodActual Transaction in the current period  String   Compulsory
importeTotal Total amount. Format 0.000,00  String  Compulsory
saldoAplazadoAnterior Previous deferred balance. Format 0.000,00  String Compulsory
importeTotalLiquidar Total amount to liquidate. Format 0.000,00 String Compulsory
totalOperProximLiquidacion Total of transactions in the next liquidation. Format 0.000,00  String  Compulsory

List<DetalleMovTarjeta>

Name Observations Type Restrictions
fecha Date of transaction. Format YYYY-MM-DD HH:MM:SS String Compulsory
concepto Transaction concept String Compulsory
poblacion City/Country String Compulsory
importe Transaction amount. Format [-] 0.000,00. A negative amount indicates a reimbursement, not an expense String Compulsory

Transfers

This group of services allow the user to prepare (precharge) a transfer for its execution through the client application:

The user can import his/her BS cards activity through the client application.

Use case  Prepare a transfer
Actors User, client application, Banco Sabadell’s API REST, BS
Description  The client application prepares and simulates a transfer with the details provided by the user
Pre-conditions  The user is registered in the application and BS
The user has a BS card or more
Post-conditions  The client application simulates a transfer with the details provided by the user. The user needs to confirm the precharged transaction through the BS Móvil application
Main flow
A user with access to the client application and BS makes a request to order a transfer specifying the target account, the source account, the beneficiary’s name, the concept, his/her personal number as payer, his/her ID number and the amount.
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested data.
The Banco Sabadell’s API REST receives the call and validates that the access token and the authorization are correct.
The Banco Sabadell’s API REST obtains the data of the simulation, stores it and returns it to the client application jointly with a unique code to identify the transaction.
Alternatives 1
A user with access to the client application and BS requests to receive the payers of a specific account through the client application.
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested data.
The Banco Sabadell’s API REST receives the call and indicates that the access token is incorrect.
The Banco Sabadell’s API REST informs the client application that the transaction is not authorized.
The client application will initiate an authentication and authorization process to obtain a valid access token.

Obtain Payers

It is necessary to send information about the payer of the source account to precharge a transfer. To obtain these details it is necessary to use the following resource.

A specific account can have different payers. The client application will give the option to choose one payer (if there is more than one).

The user can obtain information about the payers of a specific account through the client application.

Use case Obtain payers
Actors  User, client application, Banco Sabadell’s API REST, BS
Description Obtain the list of payers for a specific account through the client application
Pre-conditions The user is registered in the application and BS
The user has a BS card or more
Post-conditions The client application receives the requested list of payers
Main flow
A user with access to the client application and BS requests information about the payers of a specific account through the client application.
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested information.
The Banco Sabadell’s API REST receives the call and validates that the access token and the authorization are correct.
The Banco Sabadell’s API REST obtains information about the payers and sends it to the client application.
The client application receives the information about the payers of the account.
Alternatives 1
A user with access to the client application and BS requests to receive the payers of a specific account through the client application.
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested data.
The Banco Sabadell’s API REST receives the call and indicates that the access token is incorrect.
The Banco Sabadell’s API REST informs the client application that the transaction is not authorized.
The client application will initiate an authentication and authorization process to obtain a valid access token.

The call from the client application will be made through the following URL:

https://api_bs_host/ResourcesServerBS/oauthservices/{versionApi}/transferencias/nacional/{accountNumber}/ordenantes/

Detail of the request to obtain the payers of a specific account

REST request metadata

Method: GET

OAuth scope: contable

Available in version: v1.0.0

Name Observations Type Restrictions
accountNumber It is necessary to specify the account to obtain its payers. It is a 20-digit account code which can be found in the output of products query, with product type “CC”  String Compulsory

In addition to the data contained in the request, in order to use the resource (access token), the information related to OAuth 2.0 protocol needs to be sent through the mechanisms detailed in RFC6749.


Detail of the response to obtain the payer of a specific account

The response (ServiceOauthResponse) is composed of a general structure with information about the transaction (HeadResponse) and another one with specific information about the payers (Data<List<OrdenanteRespuesta>>). It returns in UTF-8 codification.

Each element of the response is detailed below:

ServiceOauthResponse: entity which contains the response.

ServicioOauthResponse

Name Observations Type Restrictions
HeadResponse Client identifier in the client application String Compulsory
Data<T> Entity identifier code String  Compulsory

HeadResponse: entity which represents the general data of the response.

HeadResponse

Name Observations Type Restrictions
codigoServicio “SERV_ORD01” String Compulsory
fechaOperacion Date of transaction. Format [yyyy-MM-dd HH:mm:ss]  Date Compulsory
error* Error code String Optional
descripcionError Description of the error String Optional
warn Warn code String Optional
informacionAdicional Additional information String Optional

*Possible error can be:

General Codes

Code Description
OK Correct result
KO Unexpected general error
{ 
    "data": [
        { "nombre": "%26RNOMBRE+C01481544", 
        "apellido1": "%26DPRIAPE+Q01481544", 
        "apellido2": "%26CSEGAPE+G01481544", 
        "nombreCompleto": "%26RNOMBRE+C01481544+%26DPRIAPE+Q01481544+%26CSEGAPE+G01481544", 
        "nif": "46000003X", 
        "numPers": "000000044" 
        },
        { 
            "nombre": "%26ANOMBRE+G01396699", 
            "apellido1": "%26MPRIAPE+V01396699", 
            "apellido2": "%26ISEGAPE+O01396699", 
            "nombreCompleto": "%26ANOMBRE+G01396699+%26MPRIAPE+V01396699+%26ISEGAPE+O01396699", 
            "nif": "43000007X", 
            "numPers": "000000099" 
        }
    ], 
    "head": 
        { 
            "fechaOperacion": "2014-05-21 13:25:20", 
            "descripcionError": null, 
            "informacionAdicional": null, 
            "codigoServicio": "SERV_ORD01", 
            "errorCode": null, 
            "warnCode": null 
        }       
}   

Data: Entity which represents the data referring to the request made by the client. In this case, it is a list of payers.

Data<List<OrdenanteRespuesta>>

Name Observations Type Restrictions
nombre Payers’ name  String Compulsory
apellido1 Payer’s first surname  String Compulsory
apellido2 Payer’s second surname String Compulsory
nombreCompleto Payer’s full name String Compulsory
nif Payer’s ID number String Compulsory
numPers Personal number which identifies the payer univocally String Compulsory

Prepare Transfers

The call from the client application will be made through the following URL:

https://api_bs_host/ResourcesServerBS/oauthservices/{versionApi}/transferencias/nacional/


REST request metadata

Method: POST

OAuth scope: contable

Available in version: v1.0.0

An example with JSON parameters:

https://api_bs_host/ResourcesServerBS/rest/transferencias/nacional/ POST 
Content-Type: application/json 
Accept: application/json 
{ 
    "cuentaBeneficiario":"0081____________9623", 
    "nombreBeneficiario":"Cfddgedfss+Fswrsw", 
    "cuentaOrdenante":"0081____________5881", 
    "numPersOrdenante":"0081000001", 
    "idFiscalOrdenante":"21111111N", 
    "importeTransferencia":"10,00", 
    "concepto":"Concepto+de+la+transferencia" 
} 
Name Observations Type Restrictions
cuentaBeneficiario Target account. It is a 20-digit numeric account code String Compulsory
cuentaOrdenante Source account. It is a 20-digit account code which can be found in the output of products query, with product type “CC” String Compulsory
nombreBeneficiario Beneficiary’s name. Name + Surnames String Compulsory
numPersOrdenante Payer’s personal number. It can be obtained in the call String Compulsory
idFiscalOrdenante Payer’s ID number. It can be obtained in the call String Compulsory
concepto Concept of the transfer String Compulsory
importe Amount of the transfer. Amount with the following format 00000,00 String Compulsory

The call parameters using POST are established with JSON.

In addition to the data contained in the request, in order to use a resource (access token), the information related to OAuth 2.0 protocol needs to be sent through the mechanisms detailed in RFC6749.

Detail of the response to prepare a transfer

The response (ServiceOauthResponse) is composed of a general structure with information about the transaction (HeadResponse) and, on the other hand, of a specific transfer simulation structure surrounded by another one of accounting transactions (Data<ElementosOperacion<SimularTransferencia>>). It returns in UTF-8 codification.

Each element of the response is detailed below:

ServiceOauthResponse: entity which contains the response.

ServicioOauthResponse

Name Observations Type Restrictions
HeadResponse Client identifier in the client application String Compulsory
Data<T> Entity identifier code String Compulsory

HeadResponse: entity which represents general information of the response.

HeadResponse

Name Observations Type Restrictions
codigoServicio “SERV_TRA001” String Compulsory
fechaOperacion Date of transaction Date Compulsory [yyyy-MM-dd HH:mm:ss]
error* Error code String Optional
descripcionError Description of the error String Optional
warn Warn code String Optional
informacionAdicional Additional information String Optional

*Possible error values can be:

General codes

Code  Description
OK Correct result
KO Unexpected general error

Data: entity which represents the data referring to the request made by the client. In this case, it is a ElementosOperacion structure type SimularTransferencia with the data entered by the user, commissions, unique transaction identifier code and URL.

ElementosOperacion

Name Observations Type Restrictions
url Not usable. Reserved for a future URL gathering information about the service String Compulsory
codigo Unique transaction code String Compulsory [yyyy-MM-dd HH:mm:ss]
datosOperacion Returned transaction data SimularTransferencia Optional

An example of JSON response:

{ 
    "data": 
    { 
        "url": null, 
        "codigo": "2hwnc14006OJ9ns7601660100zjE7Scl9", 
        "datosOperacion": 
            { 
                "ordenanteBanco": "0081", 
                "ordenanteOficina": "0000", 
                "ordenanteDC": "00", 
                "ordenanteCuenta": "0000000003", 
                "nombreBeneficiario": "Cjtsinms Mdfeqsz", 
                "beneficiarioBanco": "0082", 
                "beneficiarioOficina": "0000", 
                "beneficiarioDC": "00", 
                "beneficiarioCuenta": "0000000002", 
                "importeTransferencia": "3,00", 
                "comisionesTransf": 
                    { 
                        "affectsChanges": "NO", 
                        "currencyOrd": "EUR", 
                        "totalComygastDiv": "0", 
                        "totalComygastEur": "0" 
                    } 
            } 
    }, 
    "head": 
        { 
            "fechaOperacion": "2014-05-21 14:40:11", 
            "descripcionError": null, 
            "informacionAdicional": null, 
            "codigoServicio": "SERV_TRA001", 
            "errorCode": null, 
            "warnCode": null 
        } 
} 

Data<ElementosOperacion<SimularTransferencia>>

Name Observations Type Restrictions
ordenanteBanco Payer’s bank String Compulsory
ordenanteOficina Payer’s office String Compulsory
ordenanteDC Payer’s control digit String Compulsory
ordenanteCuenta Payer’s account String Compulsory
nombreBeneficiario Beneficiary’s name String Compulsory
beneficiarioBanco Beneficiary’s bank String Compulsory
beneficiarioOficina Beneficiary’s office String Compulsory
beneficiarioDC Beneficiary’s control digit String Compulsory
beneficiarioCuenta Beneficiary’s account String Compulsory
importeTransferencia Amount. Format 0.000,00 String Compulsory
comisionesTransf Commissions Comisiones Compulsory

Comisiones

Name Observations Type Restrictions
affectsChanges Affects changes String Compulsory
currencyOrd Payer’s currency String Compulsory
totalComygastDiv Contains dividends including total commission expenses String Compulsory
totalComygastEur Total commission expenses in Euros String Compulsory

Prepare Instant Money

This service allows the user to precharge an Instant Money transaction through the client application. This precharge will permit to sign and confirm a transaction using BS Móvil.

Use case  Prepare a transfer
Actors User, client application, Banco Sabadell’s API REST, BS
Description The client application prepares and simulates an Instant Money transaction with the data provided by the user
The user is registered in the application and BS
The user has a BS account or more as well as a card associated with one of them
Pre-conditions The client application receives data of the simulation and a unique code to make the transaction using the Banco Sabadell’s API REST
Post-conditions The client application simulates an Instant Money transaction using the data provided by the user
Main flow
A user with access to the client application and BS makes a request to simulate an Instant Money transaction providing card and telephone number, amount and concept.
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested information.
The Banco Sabadell’s API REST receives the call and validates that the access token and the authorization are correct.
The Banco Sabadell’s API REST obtains the data of the simulation, stores it and returns it to the client application jointly with a unique code to identify it.
Alternatives 1
A user with access to the client application and BS requests to simulate an Instant Money transaction providing card and telephone number, amount and concept.
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested data.
The Banco Sabadell’s API REST receives the call and indicates that the access token is incorrect.
The Banco Sabadell’s API REST informs the client application that the transaction is not authorized.
The client application will initiate an Authentication and Authorization process to obtain a valid access token.

The call from the client application will be made through the following URL:

https://api_bs_host/ResourcesServerBS/oauthservices/{versionApi}/instantmoney/

Detail of a request to prepare an Instant Money transaction


REST request Metadata

Method: POST

OAuth scope: contable

Available in version: v1.0.0

An example with JSON parameters:

https://api_bs_host/ResourcesServerBS/rest/instantmoney/ POST 
Content-Type: application/json 
Accept: application/json 
{ 
    "idTarj":"365", 
    "telfMovil":"600000001", 
    "importe":"20,00", 
    "concepto":"prueba instant money" 
}
Name Observations Type Restrictions
idTarj It is necessary to specify the card identifier. It is a code which can be found in the output of products query, with product type “TC” and field “numeroProducto” String Compulsory
telfMovil Mobile number which will receive a message with the code to withdraw money from an ATM String Compulsory
importe Amount. Format 00000,00. It must be multiple of 20 and 50 (to withdraw it from an ATM) String Compulsory
concepto Concept of the Instant Money transaction String Compulsory


The request of this service will be made by POST. The call parameters using POST are established with JSON.

In addition to the data contained in the request, in order to use a resource (access token), the information related to OAuth 2.0 protocol needs to be sent through the mechanisms detailed in RFC6749.

Detail of the response to prepare an Instant Money transaction

The response (ServiceOauthResponse) is composed of a general structure with information about the transaction (HeadResponse) and, on the other hand, of a specific transfer simulation structure surrounded by another one of accounting transactions (Data<ElementosOperacion<SimularIM>>). It returns in UTF-8 codification.

Each element of the response is detailed below:

ServiceOauthResponse: Entity which contains the response.

ServicioOauthResponse

Name Observations Type Restrictions
HeadResponse Client identifier in client application String Compulsory
Data<T> Entity identifier code String Compulsory

HeadResponse: entity which represents general information of the response.

Name Observations Type Restrictions
codigoServicio “SERV_INM001” String Compulsory
fechaOperacion Date of transaction Date Compulsory [yyyy-MM-dd HH:mm:ss]
error* Error code String Optional
descripcionError Description of the error String Optional
warn Warn code String Optional
informacionAdicional Additional information String Optional

*Possible error values can be:

General Codes

Code Description
OK  Correct result
KO Unexpected general error

Data: entity which represents the data referring to the request made by the client. In this case, it is a ElementosOperacion structure type SimularIM with the data entered by the user, commissions, unique transaction identifier code and URL.

ElementosOperacion

Name Observations Type Restrictions
url Not usable. Reserved for a future URL gathering information about the service String Compulsory
codigo Unique transaction code String Compulsory [yyyy-MM-dd HH:mm:ss]
datosOperacion Returned transaction data SimularIM Optional

An example of JSON response:

{ 
    "data": 
        { 
            "url": null, 
            "codigo": "E6Ev814006nms7L7662202024mplLybbn", 
            "datosOperacion": 
                { 
                    "tarjeta": "4106000000000002", 
                    "telefono": "600000001", 
                    "concepto": "Pruebas IM", 
                    "importe": "20,00",
                    "comisiones": [
                        { 
                            "divisa": "EUR", 
                            "importe": "3,00", 
                            "interesTxt": "1" 
                        }, 
                        { 
                            "divisa": "EUR", 
                            "importe": "0,00", 
                            "interesTxt": "2" 
                        }, 
                        { "divisa": "EUR", 
                        "importe": "0,00", 
                        "interesTxt": "3" 
                        }
                    ] 
                } 
        }, 
    "head": 
        { 
            "fechaOperacion": "2014-05-21 14:50:13", 
            "descripcionError": null, 
            "informacionAdicional": null, 
            "codigoServicio": "SERV_INM001", 
            "errorCode": null, 
            "warnCode": null 
        } 
} 

Data<ElementosOperacion<SimularIM>>

Name Observations Type Restrictions
tarjeta Funds will be deducted from this card. It will provide a code after making the request String Compulsory
teléfono Mobile number which will receive the message with a code to withdraw money from an ATM String Compulsory
importe Amount. Format 000,00 String Compulsory
concepto Concept of the Instant Money transaction  String Compulsory
comisiones Commission  List<ComisionIM>  Compulsory

ComisionIM

Name Observations Type Restrictions
divisa Currency of the returned commission String Compulsory
importe Commission amount. Format 00000,00 String Compulsory
interesTxt Field including number of commission  String Compulsory

Make a Transfer

This service allows the user to make a transfer to his/her own account through the client application.

Use case Make a transfer
Actors User, client application, Banco Sabadell’s API REST, BS
Description The user makes a transfer without signature between his/her own accounts
Pre-conditions The user is registered in the application and BS
The user has a BS account or more
Post-conditions  The client application receives the lists of payers of the account requested by the user
Main flow
A user with access to the client application and BS makes a request to make a transfer between his/her own accounts.
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested information.
The Banco Sabadell’s API REST receives the call and validates that the access token and the authorization are correct.
The Banco Sabadell’s API REST makes the transfer and returns the data to the client application.
The client application shows receives the data.
Alternatives 1 
A user with access to the client application and BS makes a request to make a transfer between his/her own accounts.
The client application has a valid access token to obtain the requested resources.
The client application calls the Banco Sabadell’s API REST to obtain the requested data.
The Banco Sabadell’s API REST receives the call and indicates that the access token is incorrect.
The Banco Sabadell’s API REST informs the client application that the transaction is not authorized.
The client application will initiate an authentication and authorization process to obtain a valid access token.

REST service to make a transfer

The call from the client application will be made through the following URL:

https://api_bs_host/ResourcesServerBS/oauthservices/{versionApi}/traspasos/aportacion/

Detail of the request to prepare a transfer

REST request metadata

Method: POST

OAuth scope: traspaso

Available in version: v1.0.0

An example with JSON parameters:

https://api_bs_host/ResourcesServerBS/rest/traspasos/aportacion/ POST 
Content-Type: application/json 
Accept: application/json 
{ 
    "cuentaDestino":"00811234567002222222", 
    "cuentaOrigen":"00811234567001111111", 
    "concepto":"Concepto de la aportacion", 
    "importe":"10,00" 
} 
Name Observations Type Restrictions
cuentaDestino Target account String Compulsory
cuentaOrigen Source account String Compulsory
concepto Transfer concept String Compulsory
importe Transfer amount String Compulsory


The request for this service will be made by POST. The call parameters using POST are established with JSON.

In addition to the data contained in the request, in order to use a resource (access token), the information related to OAuth 2.0 protocol needs to be sent through the mechanisms detailed in RFC6749.

Detail of the response to make a transfer

The response (ServiceOauthResponse) is composed of a general structure with information about the transaction (HeadResponse) and, on the other hand, of a specific transfer simulation structure surrounded by another one of accounting transactions (Data<Traspaso>). It returns in UTF-8 codification.

ServiceOauthResponse: entity which contains the response.

ServicioOauthResponse

Name Observations Type Restrictions
HeadResponse Client identifier in client application String Compulsory
Data<T> Entity identifier code String Compulsory

HeadResponse: entity which represents general data of the response.

HeadResponse

Name Observations Type Restrictions
codigoServicio “SERV_TSP001” String Compulsory
fechaOperacion Date of transaction Date Compulsory [yyyy-MM-dd HH:mm:ss]
error* Error code String Optional
descripcionError Description of the error String Optional
warn Warn code String Optional
informacionAdicional Additional information String Optional

*Possible error values can be:

General Codes

Code Description
OK Correct result
KO Unexpected general error

An example of JSON response:

{ 
    "data": 
        { 
            "cuentaDestino":"00811234567002222222", 
            "cuentaOrigen":"00811234567001111111", 
            "importe":"10,00", 
            "numOperacion":"9999MIA30238" 
        }, 
    "head": 
        { 
            "fechaOperacion": "2014-05-21 14:40:11", 
            "descripcionError": null, 
            "informacionAdicional": null, 
            "codigoServicio": "SERV_TSP001", 
            "errorCode": null, 
            "warnCode": null 
        } 
} 

Data: entity which represents the data referring to the request made by the client. In this case, it is a Traspaso structure with the data entered by the user and the unique identifier code of the transaction.

Data<Traspaso>

Name Observations Type Restrictions
cuentaDestino Target account String Compulsory
cuentaOrigen Source account String Compulsory
importe Transferred amount String Compulsory
numeroOperacion Number of transaction after the transfer String Compulsory

Test Environment

Introduction

There is a tests environment available for developers. In this section you will find the user details you will need to carry out tests and indications about how to simulate some transactions.

User

Developers will get a username to access BS Online as individuals in order to test the OAuth’s authorisation process. This information will be available within the section ‘My profile’.

Available products

There will be different products available to operate with the API. Each developer will have data for tests at his/her disposal (accounts, credit cards, transactions, etc.). The data will be presented as in the following example (oriented to transactions inquiry):

Example Test Data

The number associated to each product (product column) will be modified and a specific number will be assigned to each developer. This information will allow developers to test the Banco Sabadell’s OAuth services available for them.

OAuth authorisation. Signature to set up accounts

Developers will need to insert a password in order to sign using the signature display available in the tests environment. To simulate a codes card, even amounts will be validated whereas odd amounts will appear as invalid.

Transfers simulation

The BS Móvil app is not available within the development environment to confirm a transaction. Therefore, it will be automatically confirmed and implemented if the amount is even.

Instant Money simulation

The BS Móvil app is not available within the development environment to confirm an Instant Money transaction. Therefore, it will be automatically confirmed and implemented if the amount is even.

Errors

When using resources, the Banco Sabadell’s API REST will be able to return errors in two different ways (omitting errors originated in the OAuth protocol described above). We can set different types or error levels:

Semantic errors

Product permission errors (use a resource in a product to which the access is unauthorized). The most important are:

Invalid Token

HTTP Code Error: 401 (Unauthorized)

More information: apart from the OAuth validation standard (which will return the invalid token error as detailed in RFC6479), this error can appear if the Banco Sabadell’s API REST is not able to finalize token validations.

Acces Token by Request

HTTP Code Error: 400

More information: although the definition of OAuth 2.0 allows to send the access_token by query_string, the Banco Sabadell’s API REST, for security reasons, will not permit it (it will only accept tokens by Authorization). If the token is sent by query_string (http://url_recurso/path/recurso?access_token=XXXX) the following error will appear.

Invalid Scope

HTTP Code Error: 403

More information: if the resources the token can access differ from the potential resources the application would be able to access. For example, the token can access “A,B,C” resources, but the application has parameterized constraints to access “C”. This can occur due to changes in the parameter of the client application.

Disabled Application

HTTP Code Error: 403

More information: if the client application is disabled by Banco Sabadell, all the requests to resources will receive this error code.

HTTP Code Error: 403

More information: there is a management policy for the use of resources. If the client application tries to use a resource surpassing the quota, the following error will appear jointly with a descriptive message.

Inexistent Product or not Belonging to a User

HTTP Code Error: 401

More information: the product does not exist or does not belong to the user or has not been authorized.

Denied Access to the Resource

HTTP Code Error: 401

More information: the client application does not have access to the requested resource.

Operation errors

These errors are specific to the operation (for example: an incorrect parameter) or used resource and appear in the HeadResponse of the operation (error code).