1 1. Introduction
- 1.1 1.1 Context
2 2. Request Handling
- 2.1 2.1 Parameters
- 2.2 2.2 Resource Identifiers
3 3. Success Responses
4 4. Error Responses
- 4.1 4.1 Integration Test Errors
- 4.2 4.2 Passthrough Errors
- 4.3 4.3 Generic Errors

1. Introduction

Ozone Connect is an API description provided by Ozone that facilitates integration between the API Hub and LFIs. In practical terms implementing Ozone Connect means implementing the APIs defined by the standard and ensuring that the API Hub can invoke them successfully.

This page provides guidance on the implementation of Ozone Connect from the perspective of ensuring robust and consistent interaction between the API Hub and an LFI.

1.1 Context

The integration between the API Hub and Ozone Connect is implemented to provide a consistent mechanism for requesting data or initiating services at a given LFI.

The diagram below puts this in the context of a sequence diagram, showing the interaction between the API Hub and Ozone Connect implemented at the LFI.

High-level Overview of Ozone Connect Flow

To annotate the diagram:

The TPP makes a call to the LFI Resource Server to request a given resource.
The consent associated with the Access Token is checked (not shown) and then used to inject parameters that will be used in the call to the Ozone Connect API.
The API call is made, which is serviced by the LFI based on their implementation.
The LFI creates the appropriate success or failure response and returns this to the API Hub.
The API Hub then prepares the appropriate response based on the HTTP status code and the content of the response message.

The high-level flows described above following accepted paradigms for API, save for several core principles that guide how Ozone Connect is used and provides an effective mechanism for communications between the API Hub and Ozone Connect.

The design principles for Ozone Connect are outlined below.

	Principle	Rationale	Notes

	Principle	Rationale	Notes
1	The modus operandi is a successful response.	Provides stability in implementation. Reduces edge cases and error conditions.	Ozone Connect is design to facilitate consistent success conditions being returned by the implementation. Errors returned by the implementation are therefore only standardised in certain cases, as described below.
2	Success response payloads reuse definitions from the standards.	Supports consistency in implementation. Provides consistent source-of-truth.	The best approach to supporting standards adoption is to reuse them. Ozone Connect therefore reuses standards payloads, overlaying them with request handling as described below to help facilitate a consistent, success response.
3	HTTP status codes are the primary indicator for error conditions.	Allows coarse-grained error handling for the majority of errors.	The API Hub will interpret most responses based on a HTTP status code, and introspect the response to relay the correct information back to the TPP. Having a representative HTTP response code this therefore important to allows this to happen correctly.
4	Error codes are prescribed in exceptional cases.	Allows implementers to use Ozone tooling for testing purposes. Allows reuse of existing error codes for implementers. Avoids close-coupling across implementations by different implementers and versions.	Ozone only mandates error codes in exceptional cases as, for the most part, a stable, well-tested connection is expected and error handling is not prescribed. Mandated error codes are described in the relevant sections below.

The following sections provide further details request handling, success and error responses.

2. Request Handling

2.1 Parameters

The Ozone Connect standard provides several parameters that provide information to the LFI about the consent and customer to which the API call is related.

Please refer to the OpenAPI description for each API for details on the parameters supported for each operation.

2.2 Resource Identifiers

Resource identifiers are used to retrieve a specific resource. For example, to retrieve an account with the resource identifier a1f1b06b-8495-4709-95ca-806eac2c95f2 a TPP would call get /accounts/{accountId}.

All resource identifiers are defined by the LFI and returned from Ozone Connect. These are passed through to the TPP as-is, without modification or remapping at the API Hub.

Please refer to the OpenAPI description for each API for details on the resource identifiers supported for each operation. Resource identifiers are defined as Parameter Object in the OpenAPI Specification, with the type set to path.

3. Success Responses

Success responses are described by the Ozone Connect standard and prescribes what data must be returned by the LFI.

Ozone Connect prescribes the shape of a success response through an OpenAPI Response Object. This comprises the following information:

The HTTP status code that indicates success (typically, but not exclusively 200 OK)
The media type by which the data must be encoded (typically application/json)
The format of the response, described using a Schema Object.

A separate Response Object is provided for each operation.

LFIs should observe the follow guidelines when implementing the Ozone Connect standard.

	Guideline	Rationale

	Guideline	Rationale
1	Ensure you return all the data visible to your customer in your online channels.	Provides a consistent user experience for consumers across the open finance ecosystem.
2	Return all other available data in the response to an API operation.	Provides the opportunity an for enriched experience for consumers.
3	Observe the required HTTP status codes described in the OpenAPI description documents.	Prevents unwarranted failure scenarios being experienced at the API Hub.

4. Error Responses

Errors are defined in three ways:

Integration Test Errors: Errors that LFIs can use to support integration testing in pre-production.
Passthrough Errors: Errors that must be supported by the LFI to ensure successful integration between the API Hub and LFI.
Generic Errors: Errors that are returned by the LFI and are not prescribed in the Ozone Connect specification.

These are expanded upon in the sections below.

4.1 Integration Test Errors

Integration Test Errors are errors that are prescribed by Ozone and can be supported to help with pre-production integration tests of Ozone Connect.

Implementation of Integration Test Errors is optional. Implementers of Ozone Connect must refer to each OpenAPI description for information on test cases error codes, which are detailed under each HTTP response code section.

4.2 Passthrough Errors

Passthrough Errors are errors that are prescribed by Ozone and must be supported to ensure the integration between the API Hub and Ozone Connect is correctly implemented.

Authoritative Errors are a composite of:

The HTTP status Code.
The value of the errorCode property in the response payload.

Passthrough errors are used to drive a specific response behaviour when the response is played back to a Client, and are defined in exceptional cases.

LFIs implementing Ozone Connect must implement the Passthrough Errors below to support the successful integration with API Hub.

The errorDescription that is provided will be passed on to the TPP who may subsequently display the error to end-users. LFIs must ensure that the error description contains a message that is meaningful to the end-user.

Group	Operation	HTTP Status Code	Error Code	Description

Group	Operation	HTTP Status Code	Error Code	Description
Bank Service Initiation	`POST /payments`	400	`Consent.AccountTemporarilyBlocked`	The LFI must return this error if the account from which the payment is to be initiated has been temporarily blocked. If the account status should not be communicated to the TPP for operational or security reasons (for example, to prevent “sounding off” when the account is under investigation) the LFI may return the more generic `Consent.TransientAccountAccessFailure` message as stated below. This error indicates to a TPP that a retry in the future may result in a successful outcome once the transient failure has passed.
Bank Service Initiation	`POST /payments`	400	`Consent.PermanentAccountAccessFailure`	The LFI must return this error if the account related to the payment consent is no longer accessible. Scenarios include if the account has been closed, the account holder is under liquidation or for any similar reasons. The error indicates to a TPP that a retry in the future will not result in a successful outcome. Please note the LFI may carry out house-keeping on consents and move consents related to such accounts into a Revoked status. In such a situation, the OFP will fail the TPP request before an Ozone Connect call is made.
Bank Service Initiation	`POST /payments`	400	`Consent.TransientAccountAccessFailure`	The LFI must return this error when the consented account for a service initiation cannot be accessed due to a transient reason. The error indicates to a TPP that a retry in the future may result in a successful outcome once the transient failure has passed.
Bank Service Initiation	`POST /payments`	400	`Consent.BusinessRuleViolation`	The LFI must return this error when a payment request fails as a result of some business rule failure that is enforced by the LFI. A textual description of the failed business rule must be provided in the `errorDescription` field. An example of a business rule violation would be when a payment exceeds the daily limit for an account, when an account balance is not available or the payment is failed due to some other operational reason such as a lien on the account.
Bank Data Sharing	All (other than `GET accounts`)	400	`Consent.AccountTemporarilyBlocked`	The LFI must return this error code when data is requested for an account that has been temporarily blocked. If the account status should not be communicated to the TPP for operational or security reasons (for example, to prevent “sounding off” when the account is under investigation) the LFI may return the more generic `Consent.TransientAccountAccessFailure` message as stated below. This error indicates to a TPP that a retry in the future may result in a successful outcome once the transient failure has passed. Calls to `GET /accounts` must return ALL consented accounts. The `data.status` of the account must indicate the status of the account.
Bank Data Sharing	All (other than `GET accounts`)	400	`Consent.PermanentAccountAccessFailure`	The LFI must return this error if the account related to the consent is no longer accessible. Scenarios include if the account has been closed, the account holder is under liquidation or for any similar reasons. This error indicates to a TPP that a retry in the future will not result in a successful outcome. Calls to `GET /accounts` must return ALL consented accounts. The `data.status` of the account must indicate the status of the account. Please note: The LFI may carry out house-keeping on consents and remove such accounts from the consent. The LFI may move the consent into Revoked status when the last account is removed. In such a situation, the OFP will fail the TPP request before an Ozone Connect call is made.
Bank Data Sharing	All (other than `GET accounts`)	400	`Consent.TransientAccountAccessFailure`	The LFI must return this error when the consented account cannot be accessed due to a transient reason. This error indicates to a TPP that a retry in the future may result in a successful outcome once the transient failure has passed. Calls to `GET /accounts` must return ALL consented accounts. The `data.status` of the account must indicate the status of the account.
Consent Event & Actions	`POST /consent/action/validate`	See description	`See description`	The `validate` API call has the following behaviour: If the LFI completes processing of the `validate` call, it must return a `200` to indicate that it processed the call. The `status` should be set to `valid` if all validation rules passed The `status` should be set to `invalid` if the LFI found a validation failure. When the LFI returns an `invalid` status, it must return a `code` from following list their corresponding `description` is propagated to the TPP `Consent.TransientAccountAccessFailure Consent.AccountTemporarilyBlocked, Consent.PermanentAccountAccessFailure, Consent.BusinessRuleViolation, Consent.FailsControlParameters, JWE.DecryptionError JWE.InvalidHeader GenericRecoverableError GenericError` If the LFI returns an `invalid` status with a code not in the list above, the specific code is not propagated to the TPP and a `500` error is returned (this is considered unexpected response from the LFI) If the LFI is unable to complete processing due to an unexpected error (such as a badly formatted input), it should return a `400` error code. This is treated as a generic error and a `500` error is sent to the TPP.

4.3 Generic Errors

Generic Errors are errors that are not prescribed by Ozone.

Like Passthrough Errors, Generic Errors are a combination of HTTP status code and errorCode value. Ozone will, however, use the GenericError label in their response to TPPs and will not attempt to transpose any error information in the response. The API Hub will in most cases a 5xx error, indicating a downstream error to the TPP.

LFIs should observe the following guidelines when implementing Generic Errors.

	Guideline	Rationale	Notes

	Guideline	Rationale	Notes
1	User the `Error` Response Object to describe your error response payloads consistently.	The API Hub will readily parse this format, simplifying logging, auditing, and debugging.	Please refer to the Ozone Connect API descriptions, which implement the OpenAPI `default` response to indicate the expected format for anything that is not a `2xx` response.
2	Use consistent and deterministic `errorCode` values for failures.	Consistent and deterministic `errorCode` values will simplify debugging error cases.	Providing consistent error codes will result in better management of the LFI instance on the API Hub.
3	Observe the relevant HTTP status codes for the error condition.	The API Hub will be able to transpose the error in the response to the TPP more effectively.	As with the guidance on success responses, sending a `2xx` HTTP status code with the `Error` response will be misleading and cause an incorrect response to the TPP by the API Hub.

API Hub Documentation v5

This space is deprecated and no longer supported. Please use the latest available version here.

Ozone Connect Implementation Guide