Torfx APIs Torfx APIs NAV Navbar
Shell JavaScript Python

Third-Party Service Provider

Abstract

Open Banking is the name of a secure set of technologies and standards which allow customers to give companies other than their payment service provider permission to securely access their accounts. This means customers can, if they choose, easily use financial services from different types of regulated companies without the need to share credentials with any third parties. They may, for example, choose to aggregate a view of all of their accounts through one provider or allow a company to analyse their account data to offer automated tax returns, budgeting advice or cheaper overdrafts.

Note: Every company using Open Banking to deliver their services has to be authorised by the Financial Conduct Authority (FCA) or another European Regulator.

Introduction

With the increasing use of distributed web services and cloud computing, third-party applications can benefit from access to these server-hosted resources.

In the traditional client-server authentication model, the client requests an access-restricted resource (protected resource) on the server by authenticating with the server using the end user’s credentials. In order to provide third-party applications access to restricted resources, the end user shares their credentials with the third party. This creates several problems and limitations:

Open Banking provides a standard method for resource owners (an end-user) to delegate access of protected financial data to a third-party client without sharing their credentials. This client (acting on behalf of the user) can then request access to resources controlled by the resource owner, but hosted on our servers using different credentials than those of the resource owner. This is an access token – a string denoting a specific scope, lifetime, and other access attributes

Our servers will verify the resource owner authorization, and the identity of the client making the request.

Terminology

Term Definition
Third-Party Service Provider The Third Party application that wants to access the protected information.
Resource server API or system which holds the data. An HTTP server capable of accepting authenticated requests.
Authorization server The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.
Protected resource An access-restricted resource that can be obtained from the server using an OAuth-authenticated request.
Resource owner End user who owns the data that the application wants to get to.
Credentials Credentials are a pair of a unique identifier and a matching shared secret. OAuth defines three classes of credentials: client, temporary, and token, used to identify and authenticate the client making the request, the authorization request, and the access grant, respectively.
Access token A unique identifier issued by the server and used by the client to associate authenticated requests with the resource owner whose authorization is requested or has been

Example

Jane, an end-user (resource owner) can grant an accountancy service (client) access to her private statements stored at an account information sharing service (server), without sharing her username and password with the account information service. Instead, she authenticates directly with the account information service which issues the accountancy service delegation-specific credentials.

Jane wants to do her tax return and has a lot of information stored on www.torfx.com (server). She would like to use the accountancy.example.com website (client) to calculate the tax on her currency transactions. Typically, Jane signs into www.torfx.com using her username and password.

However, Jane does not wish to share her username and password with the accountancy.example.com website, which needs her statements’ data in order to do the calculations. In order to provide its users with better service, accountancy.example.com has signed up for a set of www.torfx.com client credentials ahead of time:

The complete process involves the following steps:

Sequence Diagram

  1. Jane logs in to her accountancy.example.com account and asks to collate her tax return. She specifies that she wants to include data from Torfx. The client responds with a request to link to our service.
  2. Before accountancy.example.com can ask Jane to grant it access to her Torfx account, it must first request a one time token to identify the delegation request. To do so, the client sends the following HTTPS request to the server:

    POST /token HTTP/1.1

    Host: www.api.currenciesdirect.com

    grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}&scope={{scope}}&callback_url="http%3A%2F%2Faccountancy.example.com%2Fready"

  3. The Authorisation Server replies to the client with a redirect_url to the login page (on our consent server) and the one_time_token in the body of the HTTP response:

    HTTP/1.1 200 OK

    Content-Type: application/x-www-form-urlencoded

    redirect_url="https%3A%2F%2Fwww.currenciesdirect.com%2Fauthorize%3Fone_time_token%3Dhh5s93j4hdidpola"

  4. The Third-Party Service Provider sends a redirect response to the Browser, with the one_time_token as a parameter

  5. The Browser makes a request for the Consent Server login page, over TLS/HTTPS, and passes the one_time_token.

  6. To obtain Jane’s approval for accessing her account information the Consent server presents the login page to the Browser, and sets a session cookie. For instance:

    https://online.torfx.com/CustomerPortal/login.htm?one_time_token=hh5s93j4hdidpola

    The Browser renders the login page and requests Jane sign in using her username and password.

  7. Jane enters her login credentials for Torfx, and clicks enter.

  8. The Browser submits the login request to the Consent Server, and includes the session cookie.

  9. If successful, the Consent Server sends a consent page which asks Jane to approve granting accountancy.example.com access to her account information. The Browser renders the Consent page and requests Jane select which the scope of her consent.

  10. Jane approves the request

  11. The Browser sends the consent as a request to the Consent Server and includes the session cookie.

  12. The Consent server sends a redirect to the browser together with the consent_id.

  13. The Browser redirects to the Third-Party Service Provider’s callback_url, including the consent_id as a parameter. E.g:

    http://accountancy.example.com/ready?one_time_token=hh5s93j4hdidpola&consent_id=hfdp7dh39dks9884

  14. The callback request informs the client that Jane completed the authorization process. The Third-Party Service Provider extracts the consent_id a.

  15. The Third-Party Service Provider makes a POST request to the Authorisation Server to get an API access token using its client credentials:

    POST /token HTTP/1.1 Host: www.api.currenciesdirect.com Authorization: Basic ZThiMDE4NmNmYmZlOmU0NGM3MjYxLTNjNmMtNDRhYS05MTg5LTU0ZWNkNWYwYjFjOA==, one_time_token="hh5s93j4hdidpola", consent_id="hfdp7dh39dks9884"

  16. The Authorisation server validates the request and replies with an API access token in the body of the HTTP response:

    HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded access_token=a815f20b-2132-48cb-9c81-d14a6835722f

    The Authorisation returns the access_token.

  17. The Third-Party Service Provider can now use the access_token to make a request to the protected resource server.

    GET customers/0202000005924291/statements/USD?page=1&limit=100 HTTP/1.1 Host: api.currenciesdirect.com Authorization: Basic ZThiMDE4NmNmYmZlOmU0NGM3MjYxLTNjNmMtNDRhYS05MTg5LTU0ZWNkNWYwYjFjOA==, access_token="a815f20b-2132-48cb-9c81-d14a6835722f"

  18. The Resource Server sends a request to the Authorisation Server to check the access_token is still valid and has the correct scope to view the requested information.

  19. The Authorisation Server responds to the Resource Server detailing whether the access_token and scope are valid for the Third-Party Service Provider’s request.

  20. The resource Server responds with the requested information. accountancy.example.com is able to continue accessing Jane’s information using the same set of token credentials for the duration of Jane’s authorization, or until Jane revokes access.

Authenticate a TSP

Request an Access Token to Authenticate. This is a modified version of the Token resource used for other APIs.

Get an OAuth Access Token

Code samples

# You can also use wget
curl -X POST https://sandbox.currenciesdirect.com/auth/oauth/v2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json'

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://sandbox.currenciesdirect.com/auth/oauth/v2/token',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

r = requests.post('https://sandbox.currenciesdirect.com/auth/oauth/v2/token', params={

}, headers = headers)

print r.json()

POST /auth/oauth/v2/token

To access any of the other API resources you will first need to obtain a token. Make a POST request to this Resource. OAuth2 Request Sequence Diagram Figure: Authentication If you provided all the Request Body parameters, you should receive an Access Token in the response body.

Body parameter

grant_type: client_credentials
client_id: l7323441a8e72a4dd48a70b0e7d7b42437
client_secret: aeade0da50175619b6f269928a088abc
scope: external

Parameters

Name In Type Required Description
grant_type body any true The type of authorisation code being requested. For our purposes it will be an Access Token request, so this will be client_credentials.
client_id body any true The client_id provided when you requested access to the API from Torfx.
client_secret body any true The client_secret associated with your client_id.
scope body any true Should be set to the external scope.

Example responses

200 Response

{
  "access_token": "dadadb2c-1ae2-48a2-a5dc-506e0432067b",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "external"
}

Responses

Status Code 200

Ok. The response body will contain the token you need to make requests to the other resources.

Name Type Description
access_token string(guid) This GUID is a token that you should use to make the Bearer {access_token} Authorisation HTTP header required to call other resources.
token_type string Bearer
expires_in number(int32) Expiry time in seconds.
scope string Scope of access. This should be external.

Scope of TSP Access Tokens

There are two types of Third-Party Service Provider.

APIs

Code samples

# You can also use wget 
 curl -X POST https://sandbox.currenciesdirect.com/v1/tsp/invitation \ 
   -H 'Content-Type: application/json' \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 
var headers = { 
    'Content-Type':'application/json', 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/tsp/invitation', 
   method: 'post', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 
import requests 
 headers = { 
   'Content-Type': 'application/json', 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.post('https://sandbox.currenciesdirect.com/v1/tsp/invitation', params={ 

 }, headers = headers) 

 print r.json() 

 

POST /v1/tsp/invitation

Third party service provider (TSP) will call this api only in case when they don't have valid consent from the resource owner. TSP will provide redirect url in request body which will be used to pass resource owner's consent to TSP.

Body parameter

{ 
  "redirect_uri":"/v1/tsp/invitation" 
 } 
 
Name In Type Required Description
redirect_uri body string true Resource owner's consent will be passed to this endpoint.

Example responses

200 Response

{ 
     "invitation_id": "2fed3391-f03d-433f-be29-41441096a0d8", 
     "redirect_url": "http://uat.currenciesdirect.com/CustomerPortal/landingPage.htm?invitationId=2fed3391-f03d-433f-be29-41441096a0d8" 
 } 
 
Name Type Description
invitation_id string Unique id to identify consent invitation.
redirect_url string Login page url which will be presented to resource owner to login.

Initiate Payment Instructions

Code samples

# You can also use wget 
 curl -X POST https://sandbox.currenciesdirect.com/v1/tsp/payments \ 
    -H 'Content-Type: application/json' \ 
    -H 'Accept: application/json' \ 
    -H 'Authorization: Bearer {access-token}' 

 
var headers = { 
   'Content-Type':'application/json', 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/tsp/payments', 
   method: 'post', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 
import requests 
 headers = { 
   'Content-Type': 'application/json', 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.post('https://sandbox.currenciesdirect.com/v1/tsp/payments', params={ 

 }, headers = headers) 

 print r.json() 

 

TSP can initiate a transfer by calling Initiate Payment instruction with details of the Recipient's account and payment information, if all information is correct and valid then API will mark the request with a unique id and will redirect TSP to Torfx online portal login page.

To make a transfer, you'll need to add details of the Recipient's account. There are a number of parameters which you can use to specify this account, but generally, Recipient data objects consist of:

General Information

Recipient Bank Account Details

Recipient Bank Account Details vary for different countries. For example, the IBAN number is sufficient for most European and Nordic countries but you need Account Number, Routing Code Type, Routing Code Value and Bank Country Code to send money to the US.

In total there are four different variations of Recipient Bank Account Details possible. These are:

You will also need to provide the code for the currency of the bank account in ISO 4217 three letter format (e.g. GBP for UK pound).

Address Data

POST /v1/tsp/payments

This api will initiate customer payment ,for payment initiation customer need to provide payment information.

Body parameter

{  
 "recipient_details":{  
     "name":"David shlok",  
     "type":"Individual",  
     "country_code":"GBR",  
     "address":{  
         "address_line":"Bissonnet Street, Texas City",  
         "city":"London",  
         "state":"London",  
         "post_code":"TW3 4DF"  
         },  
     "recipient_bank_details":{  


 "account_number": "21135117",  
 "routing_code_value": "401517",  
 "routing_code_type": "SORT",  
 "bank_country_code": "GBR",  
 "currency": "GBP"  
         }  
     },  
  "payment_reference": "abc123",  
  "purpose_of_transaction": "EMIGRATION",  
  "amount": 50,  
  "redirect_uri":"/TSP/Payment/PaymentConfirmation",  
  "client_reference_id": "ABCDEFGHIJKLMNO"  
 } 

 

Parameters

Name In Type Required Description
name body string true Name of the Recipient.
type body string true Organisational type of a Recipient; whether an Individual or Corporate.
client_reference_id body string false A Reference Id that you can assign to this Recipient, for your records.
country_code body string true Three letter Country Code of the Recipient (as specified in ISO 3166-1 alpha-3).
address body object false Container for address details.
» address_line body string true First line of the postal address of the Recipient.
» city body string true Recipient's city, town, or village.
» state body string true Recipient's state, country, province or a prefecture.
» post_code body string true Recipient's postal code, zip code or pin code.
recipient_bank_details body object true Bank details of the Recipient.
» allOf
»» currency body string true Three letter Currency Code (as specified by ISO4217).
» and
»» oneOf
»»» iban body string true Recipient IBAN as per their bank records.
»» xor
»»» account_number body string true Recipient's bank account number as per their statement.
»»» swift_code body string true Swift Code of the Recipient's bank account.
»» xor
»»» account_number body string true Recipient's bank account number as per their statement.
»»» swift_code body string true Swift Code of the Recipient's bank account.
»»» routing_code_type body string true Recipient routing code type:
»»» routing_code_value body string true Routing Code of the Recipient's bank account.
»» xor
»»» account_number body string true Recipient's bank account number as per their statement.
»»» routing_code_type body string true Recipient routing code type:
»»» routing_code_value body string true Routing Code of the Recipient's bank account.
»»» bank_country_code body string true Recipient bank country code
payment_reference path string true Customer can send their payment reference(any related info).
redirect_uri body string true Redirect url for the payment initiate .

Example responses

200 Response

{ 
     "invitation_id": "5aecbcfc-e56f-40ae-81b7-7d98c90076c7", 
     "redirect_url": "https://test1.currenciesdirect.com/CustomerPortal/landingPage.htm?invitationId=5aecbcfc-e56f-40ae-81b7-7d98c90076c7" 
 } 
 

Responses

Name Type Description
invitation_id string Unique consent id to identify this consent request in process.
redirect_url string Redirect Url with consent id which can be redirect to landing page for next payment process