Pockit has partnered with tell.connect to provide Third Party Providers (“TPPs”) with access to consumer account information and payment initiation in line with regulatory requirements.
This guide outlines the process for registration, authorising and accessing consumer information as an AISP, and initiating payments as a PISP. The detailed API specification can be found in the spec section of the website.
All TPPs must register on the Example Bank developer portal.
When your register on our portal, you will be issued a unique "Client ID" & "Client Secret". These credentials will be used in authorisation API calls and must be stored securely.
In order to register you only need to provide basic user and company information and you will be able to start accessing the Sandbox immediately. In order to access the Production environment, you will be asked to provide further information relating to your TPP status, including details of registration with your National Competent Authority.
A TPP may operate multiple applications with different requirements and security certification.
For each application, you will be asked to provide a “Redirect URL” (the location we will return a user to after providing consent) and you will need to attach a certificate. Don’t worry if you haven’t created your redirect script yet – the system creates a default holding page which will allow you to test and integrate with the service, and you can replace this with your applications URL before going live.
API endpoints are secured with use of certificates. You can upload individual certificates for each application, or you can reuse a certificate across multiple applications. For Production access, we will verify that the certificate is valid, but you can use non-validated certificates in the Sandbox.
Pockit provides two separate environments:
The Production environment allows access to real user data. As you would expect, this data is highly sensitive so we are required to perform a higher level of due diligence for applications which are to be moved into Production.
The Sandbox environment is broadly identical to Production but rather than connecting to live systems, it provides stubbed data. Some of the tighter usage restrictions are also eased in Sandbox, such as the need for unique requests IDs (this is described in more detail below).
In order to provide a TPP with a user’s data or to initiate a payment on their behalf, the user is required to grant permission to the TPP for a period of up to 90 days.
The first step in obtaining a user’s authorisation is the generation of an "intent-id". To do this, the TPP should POST a request to the tell.connect authorisation server endpoint indicating the details of the authorisation being requested.
The body of the request should include:
aspsp | A unique reference for the ASPSP, in this case 8ddb14f1-fecd-41fe-90b7-f8fbda9494ac |
uuid | A unique identifier that the TPP should generate. It is used for tracking a user’s authorisation end to end. The uuid value needs to be in a UUIDv4 format. NB uniqueness is not enforced in the Sandbox environment |
scope | The type of authorisation being requested; aisp or pisp |
sandbox_sca | A flag, set to true or false, indicating that the authorisation request should be automatically accepted by the ASPSP without the need for a user to perform SCA. This is only valid in Sandbox and is in place to enable a TPP to test and integrate in a frictionless manner. This flag is ignored in Production even if provided in the request. |
Sandbox URL | https://auth-sandbox.tell.money/v1/authorise |
Production URL | https://auth.tell.money/v1/authorise |
Method | POST |
Headers |
"Content-Type": "application/json"
"Authorization": Basic client_id:client:secret (base64 encoded) "x-jws-signature": A valid signed JWT is required – see “JWT Signing” for details |
Body |
{
"aspsp": "8ddb14f1-fecd-41fe-90b7-f8fbda9494ac", "uuid": "c0fd407d-134b-4091-8e04-ab49a98db217", "scope": "aisp", "sandbox_sca": true } |
{ "intent-id": "a077e84b-a815-4ed3-81c0-8f85d55e7c47", "location": "https://auth.tell.money/v1/authorise/a077e84b-a815-4ed3-81c0-8f85d55e7c47" }
You should now redirect the user to the location provided in the response, where they will be prompted to perform SCA, review and accept the authorisation request.
If you have specified that “sandbox_sca” is “true” (sandbox only), the user will automatically be considered to have approved the request and will be automatically returned to your Redirect URL.
When the user has completed the SCA and authorisation process, we will redirect them back to the Redirect URL provided when you registered the application.
If you have not yet provided your own Redirect URL in the Sandbox environment, requests will be returned to our stubbed page, which presents a textual version of the response including the outcome and authorisation code, allowing you to manually proceed.
The URL we redirect to will contain the following parameters:
intent-id | The value we created as part of the initial authorisation request |
uuid | The value you created to identify the request on your application |
authorisation_code | If a value is provided, this indicates that the authorisation was successful and you may use this code to proceed to the next stage. If authorisation was unsuccessful (user declined or was unable to authenticate themselves) then this value will be null |
https://{{your redirect url}}?intent-id=a077e84b-a815-4ed3-81c0-8f85d55e7c47&uuid=c0fd407d-134b-4091-8e04-ab49a98db217&authorisation_code=7cfa670a-959c-43d0-bedd-28d744233151
With the authorisation code returned, your application can now request an Access Token which can in turn be used to access the account resource information or initiate a payment.
The authorisation code is valid for 60 seconds, so your application must exchange it for an Access Token within that timeframe or the consent authorisation will need to be repeated. In Sandbox, the code is valid for 10 minutes in order to assist development and testing.
To obtain an Access Token you should call the access-token endpoint, providing the authorisation code and specifying the “grant_type” as “authorization_code”.
The Access Token returned will permit access to the consumer data / payment initiation endpoint for a maximum of 1 hour at which point the access token will need to be refreshed.
Sandbox URL | https://auth-sandbox.tell.money/v1/access-token |
Production URL | https://auth.tell.money/v1/access-token |
Method | POST |
Headers |
"Content-Type”: “application/x-www-form-urlencoded”
“Authorization”: Basic client_id:client:secret (base64 encoded) “x-jws-signature”: A valid signed JWT is required – see “JWT Signing” for details |
Body |
“grant_type”: “authorization_code”
“code”: the value we returned as “authorisation_code” |
{ "access_token": {{Your new access token}}, "refresh_token": {{Your new refresh token}}, "token_type": "Bearer", "expires_in": 3600, "scope": "balance:read,product:read,accounts:read,beneficiaries:read" }
The values returned are:
access_token | An access token that can be used to make requests for this user / consent |
refresh_token | A refresh token that should be stored securely and used to refresh the access token when it expires |
token_type | Will always be “Bearer” |
expires_in | The duration in minutes that the access_token will be valid for (will typically be 3600) |
scope | This contains a set of permissions associated with the consent. It is a comma-separated list in the format: balance:read,product:read,accounts:read,beneficiaries:read |
When an access token has expired, you can utilise the stored refresh token to generate a new access token using the refresh token grant. Refresh tokens expire automatically after 90 days and new refresh tokens are issued after each use of the refresh token grant.
Sandbox URL | https://auth-sandbox.tell.money/v1/access-token |
Production URL | https://auth.tell.money/v1/access-token |
Method | POST |
Headers |
"Content-Type”: “application/x-www-form-urlencoded”
“Authorization”: Basic client_id:client:secret (base64 encoded) “x-jws-signature”: A valid signed JWT is required – see “JWT Signing” for details |
Body |
“grant_type”: refresh_token
“refresh_token” the refresh_token provided initially |
The response object is the same as per the Access Token request above.
With a valid consent and access token of type “aisp”, you can now start retrieving information from Pockit accounts.
Requests directly initiated by user activity (i.e. from your website or mobile application) must include the user’s IP address in a “x-user-ip” header. Requests initiated directly from your application (e.g. automated data sweeps, where the user has not manually instigated the task) should omit the “x-user-ip” header. Requests that are not initiated by the user are restricted to a maximum of 4 per endpoint per day.
With a valid consent and access token of type “pisp”, you can now submit a single payment initiation on behalf of the user.
A user may choose to revoke consent at any time. We do not proactively inform TPPs of revoked consents.
In order to ensure secure communications between TPPs and the tell.connect platform, all API calls must include a valid and correctly signed JSON Web Token (JWT) in the “x-jws-signature” header. For general information on the correct creation and formatting of JWTs, visit https://jwt.io.
A valid JWT is comprised of a header, a payload and signature.
The header is a JSON object comprised of:
alg | Default to HS256 |
typ | Default to JWT |
app | The id of the calling application (this is available in the portal) |
path | The path, excluding host name and version, of the API call being made. For example, a GET balance request path may be “/accounts/12345678/balance” |
iat | The time the JWT was issued |
This object is then Base64 encoded to form the full header string.
The payload is a JSON object comprised of each of the request. Where the request requires a JSON object, the payload should contain the same data in the same format. Where the request requires form data (i.e. the content is application/x-www-form-urlencoded), you should convert the form fields to a JSON object.
This object is then Base64 encoded to form the full payload string.
As per JWT requirements, the Signature is made up of a hash of the header, payload and “secret”. In this case, the “secret” is the certificate uploaded via the portal and assigned to the application from which the request is being sent.
When you’re ready to move into Production, simply log into the portal, select the application and click “request go-live”. Our team will carry out a series of checks and may be in touch if we require any further information or testing, after which, we will release your application access into Production.
Metric | AISP | PISP | CBPII |
---|---|---|---|
Uptime | 100.00% | 100.00% | 100.00% |
Average Request Time | N/A | N/A | N/A |
Error Rate | 0.00% | 0.00% | 0.00% |
Date | AISP | PISP | CBPII |
---|---|---|---|
10/1/2024 | 100.00% | 100.00% | 100.00% |
10/2/2024 | 100.00% | 100.00% | 100.00% |
10/3/2024 | 100.00% | 100.00% | 100.00% |
10/4/2024 | 100.00% | 100.00% | 100.00% |
10/5/2024 | 100.00% | 100.00% | 100.00% |
10/6/2024 | 100.00% | 100.00% | 100.00% |
10/7/2024 | 100.00% | 100.00% | 100.00% |
10/8/2024 | 100.00% | 100.00% | 100.00% |
10/9/2024 | 100.00% | 100.00% | 100.00% |
10/10/2024 | 100.00% | 100.00% | 100.00% |
10/11/2024 | 100.00% | 100.00% | 100.00% |
10/12/2024 | 100.00% | 100.00% | 100.00% |
10/13/2024 | 100.00% | 100.00% | 100.00% |
10/14/2024 | 100.00% | 100.00% | 100.00% |
10/15/2024 | 100.00% | 100.00% | 100.00% |
10/16/2024 | 100.00% | 100.00% | 100.00% |
10/17/2024 | 100.00% | 100.00% | 100.00% |
10/18/2024 | 100.00% | 100.00% | 100.00% |
10/19/2024 | 100.00% | 100.00% | 100.00% |
10/20/2024 | 100.00% | 100.00% | 100.00% |
10/21/2024 | 100.00% | 100.00% | 100.00% |
10/22/2024 | 100.00% | 100.00% | 100.00% |
10/23/2024 | 100.00% | 100.00% | 100.00% |
10/24/2024 | 100.00% | 100.00% | 100.00% |
10/25/2024 | 100.00% | 100.00% | 100.00% |
10/26/2024 | 100.00% | 100.00% | 100.00% |
10/27/2024 | 100.00% | 100.00% | 100.00% |
10/28/2024 | 100.00% | 100.00% | 100.00% |
10/29/2024 | 100.00% | 100.00% | 100.00% |
10/30/2024 | 100.00% | 100.00% | 100.00% |
10/31/2024 | 100.00% | 100.00% | 100.00% |
11/1/2024 | 100.00% | 100.00% | 100.00% |
11/2/2024 | 100.00% | 100.00% | 100.00% |
11/3/2024 | 100.00% | 100.00% | 100.00% |
11/4/2024 | 100.00% | 100.00% | 100.00% |
11/5/2024 | 100.00% | 100.00% | 100.00% |
11/6/2024 | 100.00% | 100.00% | 100.00% |
11/7/2024 | 100.00% | 100.00% | 100.00% |
11/8/2024 | 100.00% | 100.00% | 100.00% |
11/9/2024 | 100.00% | 100.00% | 100.00% |
11/10/2024 | 100.00% | 100.00% | 100.00% |
11/11/2024 | 100.00% | 100.00% | 100.00% |
11/12/2024 | 100.00% | 100.00% | 100.00% |
11/13/2024 | 100.00% | 100.00% | 100.00% |
11/14/2024 | 100.00% | 100.00% | 100.00% |
Date | AISP | PISP | CBPII |
---|---|---|---|
10/1/2024 | N/A | N/A | N/A |
10/2/2024 | N/A | N/A | N/A |
10/3/2024 | N/A | N/A | N/A |
10/4/2024 | N/A | N/A | N/A |
10/5/2024 | N/A | N/A | N/A |
10/6/2024 | N/A | N/A | N/A |
10/7/2024 | N/A | N/A | N/A |
10/8/2024 | N/A | N/A | N/A |
10/9/2024 | N/A | N/A | N/A |
10/10/2024 | N/A | N/A | N/A |
10/11/2024 | N/A | N/A | N/A |
10/12/2024 | N/A | N/A | N/A |
10/13/2024 | N/A | N/A | N/A |
10/14/2024 | N/A | N/A | N/A |
10/15/2024 | N/A | N/A | N/A |
10/16/2024 | N/A | N/A | N/A |
10/17/2024 | N/A | N/A | N/A |
10/18/2024 | N/A | N/A | N/A |
10/19/2024 | N/A | N/A | N/A |
10/20/2024 | N/A | N/A | N/A |
10/21/2024 | N/A | N/A | N/A |
10/22/2024 | N/A | N/A | N/A |
10/23/2024 | N/A | N/A | N/A |
10/24/2024 | N/A | N/A | N/A |
10/25/2024 | N/A | N/A | N/A |
10/26/2024 | N/A | N/A | N/A |
10/27/2024 | N/A | N/A | N/A |
10/28/2024 | N/A | N/A | N/A |
10/29/2024 | N/A | N/A | N/A |
10/30/2024 | N/A | N/A | N/A |
10/31/2024 | N/A | N/A | N/A |
11/1/2024 | N/A | N/A | N/A |
11/2/2024 | N/A | N/A | N/A |
11/3/2024 | N/A | N/A | N/A |
11/4/2024 | N/A | N/A | N/A |
11/5/2024 | N/A | N/A | N/A |
11/6/2024 | N/A | N/A | N/A |
11/7/2024 | N/A | N/A | N/A |
11/8/2024 | N/A | N/A | N/A |
11/9/2024 | N/A | N/A | N/A |
11/10/2024 | N/A | N/A | N/A |
11/11/2024 | N/A | N/A | N/A |
11/12/2024 | N/A | N/A | N/A |
11/13/2024 | N/A | N/A | N/A |
11/14/2024 | N/A | N/A | N/A |
Date | AISP | PISP | CBPII |
---|---|---|---|
10/1/2024 | 0.00% | 0.00% | 0.00% |
10/2/2024 | 0.00% | 0.00% | 0.00% |
10/3/2024 | 0.00% | 0.00% | 0.00% |
10/4/2024 | 0.00% | 0.00% | 0.00% |
10/5/2024 | 0.00% | 0.00% | 0.00% |
10/6/2024 | 0.00% | 0.00% | 0.00% |
10/7/2024 | 0.00% | 0.00% | 0.00% |
10/8/2024 | 0.00% | 0.00% | 0.00% |
10/9/2024 | 0.00% | 0.00% | 0.00% |
10/10/2024 | 0.00% | 0.00% | 0.00% |
10/11/2024 | 0.00% | 0.00% | 0.00% |
10/12/2024 | 0.00% | 0.00% | 0.00% |
10/13/2024 | 0.00% | 0.00% | 0.00% |
10/14/2024 | 0.00% | 0.00% | 0.00% |
10/15/2024 | 0.00% | 0.00% | 0.00% |
10/16/2024 | 0.00% | 0.00% | 0.00% |
10/17/2024 | 0.00% | 0.00% | 0.00% |
10/18/2024 | 0.00% | 0.00% | 0.00% |
10/19/2024 | 0.00% | 0.00% | 0.00% |
10/20/2024 | 0.00% | 0.00% | 0.00% |
10/21/2024 | 0.00% | 0.00% | 0.00% |
10/22/2024 | 0.00% | 0.00% | 0.00% |
10/23/2024 | 0.00% | 0.00% | 0.00% |
10/24/2024 | 0.00% | 0.00% | 0.00% |
10/25/2024 | 0.00% | 0.00% | 0.00% |
10/26/2024 | 0.00% | 0.00% | 0.00% |
10/27/2024 | 0.00% | 0.00% | 0.00% |
10/28/2024 | 0.00% | 0.00% | 0.00% |
10/29/2024 | 0.00% | 0.00% | 0.00% |
10/30/2024 | 0.00% | 0.00% | 0.00% |
10/31/2024 | 0.00% | 0.00% | 0.00% |
11/1/2024 | 0.00% | 0.00% | 0.00% |
11/2/2024 | 0.00% | 0.00% | 0.00% |
11/3/2024 | 0.00% | 0.00% | 0.00% |
11/4/2024 | 0.00% | 0.00% | 0.00% |
11/5/2024 | 0.00% | 0.00% | 0.00% |
11/6/2024 | 0.00% | 0.00% | 0.00% |
11/7/2024 | 0.00% | 0.00% | 0.00% |
11/8/2024 | 0.00% | 0.00% | 0.00% |
11/9/2024 | 0.00% | 0.00% | 0.00% |
11/10/2024 | 0.00% | 0.00% | 0.00% |
11/11/2024 | 0.00% | 0.00% | 0.00% |
11/12/2024 | 0.00% | 0.00% | 0.00% |
11/13/2024 | 0.00% | 0.00% | 0.00% |
11/14/2024 | 0.00% | 0.00% | 0.00% |