tell.
Integrate

Examples of how you communicate with the
tell.
connect gateway

TPP Onboarding

Registration of new TPPs

tell.connect will publish a branded API specification which you should include a link to on your website. When a TPP wishes to onboard, will be prompted to register with tell.connect.

We will manage the onboarding of each TPP, including validating their identity and setting them up on the system. We will inform you when a new TPP onboards, and you will be responsible for the final approval based on your due diligence policies.

Account Holder Consent

New Consent Request From TPPs

To begin the process, the TPP sends an Account Holder to our consent management endpoint (i.e. they redirect the Account Holder’s browser to us). tell.connect will verify TPP credentials, register the new request, log the TPP’s reference, generate a consent_id, and send the Account Holder on to you for authorisation (i.e. we will redirect the Account Holder’s browser to your website at a pre-agreed URL – optionally we can host this part of the service for your).

As part of this redirect, we will include:


- consent_id (our reference)
- scope (a list of permissions being requested, pre-agreed)
- TPP application name

For example,

https://yourwebsite.com/oauth?consent_id=c9a2dfa8-0167-43db-a71d-680503e9db7e&scope=balance:read,accounts:read&tpp_app={{TPP APP NAME}}

You will need to create a login page which asks the Account Holder to authenticate themselves using your existing security / SCA methodology.

When the Account Holder is validated, you should display the name of the TPP and the list of permissions being requested (i.e. the scope) and prompt them to accept or decline. For example:

“EXAMPLE TPP" has requested access to be granted to: - view your account details - view your balance Do you want to grant access?” (not real wording, just an example)

If they accept, you should perform 2 activities:

1. HTTP "POST" the outcome to us.


The body should contain our consent_id (the reference we provided in the initial redirect, a user_token (a reference generated on you which references the Account Holder and which we will use in future to identify the customer, and the outcome – pass or fail. You must also include basic authentication headers comprised of client_id:client_secret Base64 encoded. (We will provide you with client_id and client_secret at the set-up stage)

Example Request

Parameter Description
Method POST
Headers Content-Type: application/json
Authorization: Basic 0Xx1c3VhcmlvOnlsYWNsYXZ0
Headers: “Content-Type”: “application/x-www-form-urlencoded”
“Authorization”: Basic client_id:client:secret (base64 encoded)
Body: { "consent_id": "c9a2dfa8-0167-43db-a71d-680503e9db7e", "user_token": "106726572", "outcome": "pass" }

2. Redirect the Account Holder to our URL


Then redirect the Account Holder to our URL with consent_id appended (no other information) e.g.

https://oauth-connect.tell.money/sandbox/consent?consent_id=c9a2dfa8-0167-43db-a71d-680503e9db7e
We will update the tell.connect record, create the authorisation_code, access_token and refresh_tokens and other oauth elements.

No further action required by you. You do not need to store any information or authenticate the Account Holder again (unless / until the consent expires or is revoked).

tell.connect and the TPP then proceed to exchange authorisation code for access and refresh tokens, create time-bound consent assets and update authorisation engine. An access_token is valid for 1 hour.

A consent and its refresh_token are valid for 90 days and can be used to request a new access_token. tell.connect will manage this entire process – no need for your interaction at any point.

Review & Revoke Consents

Managing the TPP consents

The Account Holder must have the ability to revoke consent at any time. To do so, they should visit your website/app, view existing consents, and choose to remove/revoke one. You do not need to record or access any local data to achieve this (other than authenticating the customer).

Instead, you need to create a simple web page and utilise the following 2 API calls:

The Specifications

1. GET /oauth/consent/{user_token}

Example Request

URL https://api-connect.tell.money/sandbox/oauth/consent/{user_token}
Method GET
Headers Content-Type: application/json
Authorization: Basic 0Xx1c3VhcmlvOnlsYWNsYXZ0

Example Response

Content-Type application/json
Body:
[
{
"consent_id": "c9a2dfa8-0167-43db-a71d-680503e9db7e",
"tpp": "Yolt",
"status": "active",
"scope": "balance:read,accounts:read",
"granted": "2020:03:18 15:32:01",
"expires": "2020:06:18 15:32:01",
"revoked": ""
},
{
"consent_id": "1b486bdf-d566-4ac1-a07b-858057f68796",
"tpp": "Yolt",
"status": "revoked",
"scope": "balance:read,accounts:read",
"granted": "2020:01:18 15:32:01",
"expires": "2020:03:18 15:32:01",
"revoked": "2020:02:18 15:32:01"
}
]


This will enable you to populate a form / display a list.

2. DELETE /oauth/consent/{consent_id}

URL https://api-connect.tell.money/sandbox/oauth/consent/{consent_id}
Method DELETE
Headers Content-Type: application/json
Authorization: Basic 0Xx1c3VhcmlvOnlsYWNsYXZ0

NB as an alternative option, tell.connect can produce a simple user interface to allow the user to manage their consent without any development by you – you would simply redirect the Account Holder to us.

Access Resources

Accessing Your Account Data Resources

When the TPP has an access_token and refresh_token, they can begin making requests to access resources i.e. to read information from an account on behalf of an Account Holder. tell.connect will verify all requests from the TPP. We will continually validate the TPP as well as the access_token, including managing revokes, refreshes and expiries.

When a verified request is received by tell.connect. we will make an outgoing request to your (or your processor’s) API to retrieve information. We will identify the customer by means of the user_token provided to us by you at the point of consent. You does not need to carry out any further validation or authentication. In fact, the principle of PSD2 is that authority has now been delegated, so the ASPSP (you) must rely on that authority and return the data requested under the authenticated access_token.

You should provide tell.connect with connection to your API (or a new service). All calls from tell.connect will include basic authentication so you can ensure that the request is coming from us, as well as (optional) mutual TLS.

Some example API endpoints may look as follows (subject to what you already have available):

1. GET /accounts/{user_token}


You should return all “accounts” associated with an Account Holder. An “account” is a balance-bearing entity such, so could be a wallet, a card, an account etc, depending on how your account structure works. Each should have an account_id which is a unique reference of your choice.

Any other information you provide is optional. An example response may look like this (but the format is your choice):

[
 {
    "account_id": "acc10001",
    "nickname": "Dad"
 },
 {
    "account_id": "acc10087",
    "nickname": "Bob’s card"
 },
 {
    "account_id": "acc98721",
    "nickname": "Susan’s card"
 }
]


2. GET /balance/{accountId}

This should return the balance of the specified “account” e.g. /balance/acc10087 should return the balance of Bob’s card.

3. GET /transactions/{accountId}

This should return a list of transactions associated with the specified “account” e.g. /transactions/acc10087 should return the transactions for Bob’s card. The format of the response, and the level of data you provide, is your choice. However, you must include a transaction id.

All responses should contain 100 transactions (or less, if there are less than 100 transactions). By default, if no other parameters are defined, you should return the most recent transactions i.e. 100 transactions backwards from now.

If we include a to_transaction in the query string, you should return the 100 transactions preceding that transaction.

Example 1

GET /transactions/acc10087
[
    {
		"transaction_id": "99999",
		"amount": "12.50",
		"date": "2020-03-18"
	},
		…(98 more transactions)…
  	{
		"transaction_id": "99900",
		"amount": "9.99"
		"date": "2020-02-18"
	}
]

Example 2

GET /transactions/acc10087?to_transaction=99900
[
    {
		"transaction_id": "99899",
		"amount": "149.00",
		"date": "2020-02-17"
	},
		…(98 more transactions)…
  	{
		"transaction_id": "99800",
		"amount": "64.39"
		"date": "2019-11-03"
	}
]


The Specifications