Getting started

Our Open Banking APIs

The sections below provide information on the Open Banking APIs Yorkshire Building Society have implemented.

These APIs provide a secure, coherent set of capabilities that you can use within your applications to deliver value to customers. 

 

Developer Portal Services

The purpose of the Developer Portal is to help developers of client applications understand the APIs implemented by the YBS Group and to support developers in building applications that use these APIs.

To that end, the Developer Portal provides the following services:

 

Category

Service

Description

Operational

Registration

You have to register with Open banking website to get access for the Sandbox API.

Support

API Documentation

You will find detailed technical specifications of our APIs in this section.

Developer Support

Developer Portal provides overview of our API's and FAQs. Please use the Contact Us page for suggestions on improvements or queries on our Developer Portal or Testing Interface offering.

  

 

Overview of YBS APIs

Our initial implementation focused on PSD2 regulatory compliance for AISP and PISP.  

We have adopted the UK Open Banking specification standards for our APIs. A key aspect of these standards is the adoption of the open authorisation model based on FAPI 2.0 in addition to adherence to the OWASP REST API guidelines.

In the sandbox environment we only support FAPI 2.0 and in the production environment we currently support FAPI 2.0 and Client Secret Basic Token Endpoint Method.

There is an Authorisation Mock Page in the Sandbox that acts as the Authorisation Server website that a human-user interacts with to authenticate and authorise the access request.

It responds with an Authorisation Code when supplied with valid input parameters; authorisation is implicit and guaranteed for all valid input.

This enables TPPs to automate the end-to-end flow without the need for managing additional credentials to authenticate or additional human intervention to manually authorise the access request. 

For information about API releases and alignment with UK Open Banking, please refer to the FAQ section.

 

Discovery and Application Registration

The Open Banking specification for enrolling with the Open Banking Directory (Directory Specification) and registering with Yorkshire Building Society and other Account Servicing Payment Service Providers (ASPSPs) is available on the central Open Banking website.

The sandbox hostname for YBS and CBS brand is ob-ybs.sandbox.ybs.co.uk and ob-che.sandbox.ybs.co.uk respectively.

The production hostname for YBS and CBS brand is ob-ybs.api.ybs.co.uk and ob-che.api.ybs.co.uk respectively.

Yorkshire Building Society supports the following to enable discovery and registration for Open Banking with us:

GET /.well-known

Brand

Environment

URL

YBS

Sandbox

https://sandbox.ybs.co.uk/open-banking/v1.0/.well-known/ybs/openid-configuration

CBS

Sandbox

https://sandbox.ybs.co.uk/open-banking/v1.0/.well-known/che/openid-configuration

YBS

Production

https://api.ybs.co.uk/open-banking/v1.0/.well-known/ybs/openid-configuration

CBS

Production

https://api.ybs.co.uk/open-banking/v1.0/.well-known/che/openid-configuration

POST /register

Brand

Environment

URL

YBS

Sandbox

https://ob-ybs.sandbox.ybs.co.uk/open-banking/v3.1/tpp-client/register

CBS

Sandbox

https://ob-che.sandbox.ybs.co.uk/open-banking/v3.1/tpp-client/register

YBS

Production

https://ob-ybs.api.ybs.co.uk/open-banking/v3.1/tpp-client/register

CBS

Production

https://ob-che.api.ybs.co.uk/open-banking/v3.1/tpp-client/register
  • Use of this functionality is described in the ‘Register an application with an ASPSP using APIs’ section of the open banking Directory Specification.
  • We support TPP on-boarding application via Registration API and do not provide this capability via a manual process.

 

Certification

We support the following certificate types for identification:

  • OBWAC – Open Banking QWAC-like certificates
  • OBSEAL – Open Banking QSEAL-like certificates
  • OB non-eIDAS like certificates for transport and signing
  • eIDAS QWAC and QSEAL

As part of onboarding with us, a TPP must obtain a SSA (Software Statement Assertion) from the Open Banking directory.

For TPPs who want to use an eIDAS certificate (QWAC or QSeal) directly with YBS we currently support the following QTSPs

  • Actalis S.p.A.
  • Budapest
  • Quovadis NTRNL-30237459
  • MULTICERT - Servios de Certificao Electrnica S.A.
  • InfoCert S.p.A.
  • D-Trust GmbH
  • Buypass AS-983163327
  • I.CA Qualified 2 CA/RSA 02/2016
  • I.CA SSL EV CA/RSA 10/2017
  • Firmaprofesional S.A.
  • ADACOM S.A.

If you require a new QTSP to be added please use the Contact Us form and the QTSP will be added. The SLA to add a new QTSP is 2 business days.

Please note, the sandbox environment is currently unable to support testing utilising either test or production eIDAS certificates. To access the YBS sandbox environment please use Open Banking e-IDAS-like test certs.

Security

The detailed Open Banking specification for the security model (Security Profile) is available on the central Open Banking website

The detailed FAPI 2.0 specification is available here

We support the following to set up and enable secure use of Open Banking functionality:

POST / token       Access token required to invoke APIs.

 

Supporting information for registration and security:

Client ID and Secret used to access our APIs are important credentials must be kept securely within your organisation, and must not be shared with other parties or lost.

 

Transport layer security mutual authentication (TLS MA)

We require Transport Layer Security Mutual Authentication (TLS MA) to all our API endpoints except:

GET /.well-known

 

Support of algorithms

We support the PS256 algorithm for any signed JWTs provided by a Third Party. OIDC tokens that we provide will be signed using the PS256 algorithm.

Note: JSON = JavaScript Object Notation, JWT = JSON Web Token, OIDC = OpenID Connect.

Authorisation expiry & new intents

Long lived consents can be authorised for a maximum of 90 days. Customers (PSU) need to be re-directed by their TPPs to re-authorise and extend their consent authorisations.

 

Deleting Consents

The Consent is an agreement between the Customer (PSU) and their TPP; we will only delete / revoke consents on receipt of an API request from Customers (PSU) via their TPP.

 

TPP De-Registration

On receipt of a TPP API request to delete their registration with us, all Customer (PSU) Consent / Authorisations with that TPP will be deleted, any subsequent requests made by the TPP will be rejected.

TPP can re-register with us at any time as long as registration checks are passed see Discovery and Application Registration

Note - All previous Customer Consents / Authorisations will need to be re-created and authorised by the Customer (PSU).

 

Token validity periods

Token life spans are as follows:

  • Authorization code (used to exchange ID Token by AISP and PISP): 10 minutes, not reusable – as per OAUTH2 specification
  • Access Token (are used to allow PISPs access to protected resources (APIs), the tokens are only valid for a short duration For Single AISP Intent ID): 30 minutes
  • Refresh Token (are required to obtain new access tokens when the current token becomes invalid or expires For Single AISP Intent ID): ~90 days expected (multi-use Refresh Token)
  • ID Token generated by YBS Identity API (For Single Immediate Payment): 24 hours – but payment submission only accepted within 1 hour of customer authorisation
  • ID Token for an Consent ID (AISP): 30 minutes
  • Please note these are not fixed and will change over time.

 

Exception Codes

In addition to the response codes detailed in the Open Banking API specifications, we will return the following exception code:
- HTTP 503 (services unavailable or too busy).

 

Transaction Processing

API Call Limits

We will only process four requests for data from a third party where the customer are not present within a 24hr period; there is no restriction on requests where the customer is present.

API access is unavailable during the early morning hours from 3:00 AM to 4:00 AM.

Pagination

To restrict the size of the data of transactions we will split the response messages into pages, pagination will operate with 100 rows per page.

 

About us

Yorkshire Building Society is a member of the Building Societies Association and is authorised by the Prudential Regulation Authority and regulated by the Financial Conduct Authority and the Prudential Regulation Authority. Yorkshire Building Society is entered in the Financial Services Register and its registration number is 106085. Head Office: Yorkshire House, Yorkshire Drive, Bradford BD5 8LJ.

References to 'YBS Group' or 'Yorkshire Group' refer to Yorkshire Building Society, the trading names under which it operates (Chelsea Building Society, the Chelsea, Norwich & Peterborough Building Society, N&P and Egg) and its subsidiary companies.