NAV

Introduction

API endpoint

https://openbanking.piplatform.io

Examples in this documentation are written using httpie for clarity.
To install httpie on macOS run brew install httpie

Welcome to the Dozens OpenBanking API! You can use our API to access Dozens OpenBanking API endpoints, which interacts with user's accounts. We offer only REST API.

Authentication

The Dozens OpenBanking API implements OAuth 2.0 to allow users to log in to applications without exposing their credentials. The process involves several steps:

  1. Acquire an access token, and optionally a refresh token
  2. Use the access token to make authenticated requests

Acquire an access token

Acquiring an access token is a three-step process:

  1. Redirect the user to Dozens to authorise your app
  2. Dozens redirects the user back to your app with an authorization code
  3. Exchange the authorization code for an access token.

This access token doesn't have any permissions until your user has approved access to their data in the Dozens app.

Redirect the user to Dozens

"https://openbanking.piplatform.io/oauth2/authorize?
    client_id=$client_id&
    redirect_uri=$redirect_uri&
    request=$request&
    response_type=$response_type&
    scope=$scope&
    state=$state"

Send the user to Dozens in a web browser, where they will log in and grant access to their account.

URL arguments
Parameter Description
client_id
Required
Your client ID.
redirect_uri
Required
A URI to which users will be redirected after authorising your app.
request
Required
Signed JWS.
response_type
Required
The response type that will be used ('code id_token', 'code id_token token' or 'code').
scope
Required
The requested scope.
state
An unguessable random string used to protect against cross-site request forgery attacks.

Dozens redirects back to your app

"https://your.example.com/callback?
    code=$authorization_code&
    scope=$scope&
    state=$state&
    id_token=$id_token"

If the user allows access to their account, Dozens redirects them back to your app.

URL arguments
Parameter Description
code A temporary authorization code which will be exchanged for an access token in the next step.
scope The requested scope.
state The same string you provided as state when sending the user to Dozens. If this value differs from what you sent, you must abort the authentication process.
id_token The identity token.

Exchange the authorization code

$ http --form POST "https://openbanking.auth.piplatform.io/oauth2/token" \
    "grant_type=authorization_code" \
    "scope=$scope" \
    "redirect_uri=$redirect_uri" \
    "code=$authorization_code"
{
    "access_token": "access_token",
    "scope": "accounts",
    "token_type": "Bearer",
    "expires_in": 3600,
}

When you receive an authorization code, exchange it for an access token. The resulting access token is tied to both your client and an individual Dozens user, and is valid for several hours.

Account Initiation Services API

The Account Information Services API lets authorised Account Information Service Providers access balances and transactions for our customers.

Getting Access

To get access to our Open Banking APIs, see the Dynamic Client Registration section below.

Well-Known Endpoints

We've described the paths of our well-known endpoints for the Sandbox and Production environments below.

Environment Path
Sandbox https://openbanking-stage.piplatform.io/.well-known/openid-configuration
Production https://openbanking.piplatform.io/.well-known/openid-configuration

Base URLs

We've included the Base URLs for our Sandbox and Production environments below.

Base URLs
Environment Base URL
Sandbox https://openbanking-stage.piplatform.io/api/v1/open-banking/pisp
Production https://openbanking.piplatform.io/api/v1/open-banking/pisp

Dynamic Client Registration

We have implemented the POST /register endpoint in version 3.2 of the Open Banking Dynamic Client Registration specification. You can find the full specification here.

You can find the appropriate URL and supported configuration in our well-known endpoints for each environment.

Authentication

As per the Open Banking specification, we use OAuth 2 and OpenID connect for authentication. We have implemented the redirect flow, with authentication taking place in the customer's Dozens app.

Accounts

We’ve implemented version 3.1.2 of the Open Banking accounts specification.

Once you have a consent for a customer, you’ll be able to see their:

If the account has been closed, it will still be returned in the response, but with an updated Status.

Balances

We’ve implemented version 3.1.2 of the Open Banking balances specification.

When you query this endpoint, you’ll see the customer’s balance. This is the same real-time balance that our customers see in the Dozens app, and it includes pending and settled transaction

Transactions

We’ve implemented version 3.1.2 of the Open Banking transactions specification.

Your consent needs to have either the ReadTransactionsBasic or ReadTransactionsDetail permissions to access this endpoint.

When you query this endpoint, you’ll receive all of the transactions that the customer made in the date range specified in the request.

Transaction amounts can change after the transaction is first created, and you can use the Status field to help identify transactions that are still pending.

You’ll only be allowed to fetch transactions that were made in the range defined by TransactionFromDateTime and TransactionToDateTime in your consent. If you try to access transactions outside this range, it won’t work.

Payment Initiation Services API

The Payment Initiation Services API lets authorised Payment Initiation Service Providers make outbound payments from the accounts of our customers.

Getting Access

To get access to our Open Banking APIs, see the Dynamic Client Registration section below.

Well-Known Endpoints

We've described the paths of our well-known endpoints for the Sandbox and Production environments below.

Environment Path
Sandbox https://openbanking-stage.piplatform.io/.well-known/openid-configuration
Production https://openbanking.piplatform.io/.well-known/openid-configuration

Base URLs

We've included the Base URLs for our Sandbox and Production environments below.

Base URLs
Environment Base URL
Sandbox https://openbanking-stage.piplatform.io/api/v1/open-banking/pisp
Production https://openbanking.piplatform.io/api/v1/open-banking/pisp

Dynamic Client Registration

We have implemented the POST /register endpoint in version 3.2 of the Open Banking Dynamic Client Registration specification. You can find the full specification here.

You can find the appropriate URL and supported configuration in our well-known endpoints for each environment.

Authentication

As per the Open Banking specification, we use OAuth 2 and OpenID connect for authentication. We have implemented the redirect flow, with authentication taking place in the customer's Dozens app.

Domestic Payments

We've implemented version 3.1.2 of the Open Banking Domestic Payments specification.

You can only make payments in GBP. We don't support other currencies.