Accounts 1.0.0 guide

Guide: Accounts 1.0.0

Why not add Santander Accounts operations into your site? We enable your application to securely show Santander's accounts details and transactions.

Subscribe to

This is work in progress and neither Banco Santander, S.A. and/or its affiliates make any representation or warranty as to the completion or the release of the functionality.

Description

Accounts is an API that allows you access Santander accounts list and details like balances and transactions.

This functionality is useful to confirm customer account information and to show realtime balances and account transactions.

Requirements

Before initiating this process, you need to fulfil the following requirements:

1. Your application must be registered in our Developer Hub. You will so obtain a Client ID and Client Secret.

2. A valid redirect URI previously registered in the application to receive the answer to the authorization calls.

3. The application must be subscribed to the API "Accounts".

Data

Available account data you can retrieve includes the following:

Accounts list
Account basic data with balances
Account transactions
Account transaction details

Access level can be adjusted to match each need.

How to

Our Accounts API is protected under the Oauth2 protocol and requires to obtain authorization from the customer.

The authorization occurs in two steps:

1) Retrieve an authorization code. Get an authorization code associated to customer's authentication and consent so you can get an access token to call the Accounts API.

2) Get access token. That access token authorizes the subsequent API calls to access account data.

Once you have obtained a valid access token, you can use it to call the API and retrieve account data. Below you can see an overview of the process.

Depending on the scopes included on the first step, accesible API endpoints and account data may vary. Please ensure only required scopes are included on the request.

1. Retrieve Authorization Code

To obtain the authorization code that allows you to request the access token, it is necessary to make a call to the OAuth authorization server. Once customer authentication and consent process completes successfully, Santander will return the control of the flow to your application as a 302 redirection to the Redirect URI indicated by you in the configuration of the application associated with the Client ID used in the call. Your application will receive the answer to the request at the indicated URL authorization, which includes the authorization code.

Parameters

End Point	oauth/authorize		Mandatory
Parameters	QueryString client_id	Client identifier assigned in the API portal.	yes
	QueryString scope	ACCLIST.READ ACCDET.READ ACCTRAN.READ	yes
	QueryString user (Combo box)	User of the test case	no
	QueryString country	Identification code associated with the country to which the client belongs.	yes
	QueryString redirect_uri	URL to redirect the response.	yes
	QueryString response_type	Type of grant. It must be filled with code	yes
	QueryString state(optional)	It is used to maintain correlation between this request and the authorization server's response	recomended

Response

Response is a redirection with the following format:

https://partnerURL.com/?code=839a3d23-c3d5-4fc5-b6f9-3427b40ebc09&redirect_uri=https://www.partnerRedirectURI.es/

Error Handling

Errors can occur for several reasons.

Submit payment & check payment status

To successfully complete the payment submission process it is mandatory to check the payment status once.

Subsequent calls to check the payment status will return an up-to-date status.

Code	302	302	302	400	302	302	302	400	302	302	500	500
Message	ok	invalid_grant	invalid_grant	invalid_grant	invalid_grant	invalid_grant	invalid_grant	HttpSessionRequiredExceptio	invalid_grant	invalid_grant	Server error
Level		error	error	error	error	error	error	error	error	error	error	error
Description	ok	A client must have least one authorized grant type	A redirect_uri can only be used by implicit or authorization_code grant types	Cannot approve uninitialized authorization request	Cannot approve request when no redirect URI is provided	A redirect_uri must be supplied	Invalid redirect: [requestRedirectURI] does not match one of the registered values: [clientRedirectURIs]	Could not obtain authorization request from session	Bad client credentials	A client id must be provided	Server error	Server error
Remarks		The client does not have registered any grant	The client does not have registered the required grant type (authorization_code)	The user has approved scopes through consent page and the server does not have data from the original request to continue the flow. Possibly the session was deleted or modified	The user has approved the scopes by consent page and the client does not have a default redirect_uri and it was not specified in the request	The client does not have a default redirect_uri and it was not specified in the request	The redirect_uri specified in the request does not match with any of the redirect_uri's already	The information of the request is not available in the session	The specified client does not exist in the repository	It has not been provided a client on the request	Server error	Server error
Considerations				The Partner did not specified the redirect_uri in the API Portal		Different Redirect_URI in the Portal and in the parameter					Bad Country

2. Get access token

Once the request for access token is authorized, a call must be made to obtain it.

URI	LIVE: https://oauth.santander.com/oauth/token SANDBOX: https://api-sandbox.santander.com/santander/external/oauth/token
Method	POST

Parameters

End Point	oauth/token		Mandatory
Parameters	Header Authorization	Basic Base64(ClientID:Secret)	yes
	Body country	Country to use.	yes
	Body scope	ACCLIST.READ ACCDET.READ ACCTRAN.READ	yes
	Body grant_type	authorization_code	yes
	Body code	The code obtained in the authorization endpoint	no
	QueryString redirect uri	URL to redirect the response	yes

Response

{

'access_token': '9b678b10-cc8e-42ef-a479-1ceadbc2e176',

'token_type': 'bearer',

'expires_in': 43199,

'scope': 'acclist.read'

}

Error Handling

Errors can occur for several reasons.

Code	302	401	401	401	400	400	400	400	400	400	400	400	500	500
Message	ok	invalid_client	invalid_client	invalid_client	invalid_grant	invalid_grant	invalid_grant	invalid_request	invalid_request	invalid_scope	invalid_scope	Unsupported_grant_type
Level		error	error	error	error	error	error	error	error	error	error	error	error	error
Description	ok	Bad client credentials	Client ID mismatch	Unauthorized grant type: [grantType]	Invalid authorization code: [authCode]	Implicit grant type not supported from token endpoint	Redirect URI mismatch	An authorization code must be supplied	Missing grant type	Invalid scope: [scope]	Empty scope (either the client or the user is not allowed the requested scopes)	Unsupported grant type: [grantType]	error	Server error
Remarks		The specified client does not exist in the repository - Invalid client credentials	The specified client does not match the one used to request the code	The client is not authorized to perform the specified grant type	The specified code does not match with a previously generated code	Implicit grant type is not supported	The redirect_uri param was informed but its value does not match with previously value in the authorization endpoint	It was not specified an authorization code	It has not been specified a grant type	No scope included in the request has not been registered by the client	No scopes specified in the request and the client does not have registered any scope	The requested grant_type it is not enabled on the server	Internal Server Error	Server error
Considerations												Bad Country

3. Calling the API

From now on, calls to the API with access_token will be authorized during the effective time of the access token.