Page Comparison

openapi: 3.0.1

info:
  title: Ozone Connect - Consent Event & Action APIs
  contact:
    name: Ozone Financial Technology Limited
  description: |
    This document provides the OAS3 specification for APIs that are called by Ozone Connect to inform a financial institution that a consent has been created or modified.

    These are also used to carry out actions to verify and augment a consent when it is being created.

    These APIs should be implemented by an financial institution.

    #### Document Structure
    The documentation contains a number of references of the form `XXX-999-999`. These are references
    to test case numbers in the Ozone Connect Test Harness that financial institutions may use to test their Ozone Connect implementations.

    #### Coming soon
    The following changes can be expected in the next release:
    - some enumeration and object definitions remain to be aligned with CBUAE specifications. These will be updated
    - specific changes expected in the next release have been marked as ***TODO*** in the document
    - query parameters for pagination will be introduced in alignment with CBUAE specifications
    - some additional query parameters for functional completeness will be introduced
    - the request and response object may be moved into `data` and `meta` objects for consistency

  version: Version 2024.31 for CBUAE

servers:
  - url: https://<your-ozone-connect-server>

tags:
  - name: consent-events
    description: |
      APIs that are called when a consent is created or modified.

  - name: consent-actions
    description: |
      APIs that are called to take actions on a consent

paths:

  /consent/event/{operation}:
    post:
      tags:
       - consent-events
      summary:  Called to inform a financial instituation that a consent has been created or modified
      description: |
        Used by financial institution to get a notification for updated consent.

      operationId: consentEvent
      parameters:
        # common header parameters that set context
        - $ref: "#/components/parameters/providerId"
        - $ref: "#/components/parameters/aspspId"
        - $ref: "#/components/parameters/callerOrgId"
        - $ref: "#/components/parameters/callerClientId"
        - $ref: "#/components/parameters/callerSoftwareStatementId"
        - $ref: "#/components/parameters/apiUri"
        - $ref: "#/components/parameters/apiOperation"
        - $ref: "#/components/parameters/consentId"
        - $ref: "#/components/parameters/callerInteractionId"
        - $ref: "#/components/parameters/ozoneInteractionId"
        - $ref: "#/components/parameters/psuIdentifier"

        # Path param definitions
        - name: operation
          in: path
          description: specifies whether this is a POST or PATCH operation
          required: true
          schema:
            type: string
            enum:
              - post
              - patch

      requestBody:
        description: |
          Sends an event indicating the created or updated consent to an financial institution.
          This consists of the entire consent as stored in the consent Manager.

        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/consent"

      responses:
        "204":
          description: |
            Indicates the successful notification response.
            The response does not have a body

        "400":
          description: |
            Indicates that the financial institution could not process the event.

            Ozone will ignore these errors.
            The notification *will not* be retried.

            The change to the consent *will not* be rolled back.

          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /consent/action/augment:
    post:
      tags:
        - consent-actions
      summary: Account action augumentation
      description: |
        The API is called by Ozone to allow a Financial Institution to augment additional information that may apply to the account consent

        The request body contains the entire consent record as stored in the Consent Manager.

      operationId: augmentAccountConsent

      parameters:
        # common header parameters that set context
        - $ref: "#/components/parameters/providerId"
        - $ref: "#/components/parameters/aspspId"
        - $ref: "#/components/parameters/callerOrgId"
        - $ref: "#/components/parameters/callerClientId"
        - $ref: "#/components/parameters/callerSoftwareStatementId"
        - $ref: "#/components/parameters/apiUri"
        - $ref: "#/components/parameters/apiOperation"
        - $ref: "#/components/parameters/consentId"
        - $ref: "#/components/parameters/callerInteractionId"
        - $ref: "#/components/parameters/ozoneInteractionId"
        - $ref: "#/components/parameters/psuIdentifier"

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/consent"

      responses:
        "200":
          description: |
            Indicates a successful operation

            The response consists of fields that must be augmented into the consent.

            These fields will be different for each consent type.

            •••TODO••• Specify the fields that must be augmented for CBUAE consents
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/augmentConsentResponse"
        "400":
          description: failed operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /consent/action/validate:
    post:
      tags:
        - consent-actions
      summary: Provides an opportunity for a financial institution to validate a consent before it is created
      description: |
        The API is called by Ozone to allow a financial institution to carry out additional validations before a consent is created.

        The request body contains the entire consent along with contextual information.

        Typically this could be used for situations like:
        - soft validation of the debtor account (e.g. to ensure that it is a debtor account managed by the financial institution)
        - populating charges and exchange rate information

        Note that a financial institution only need to implement this API where it needs to correlate information in the consent payload
        with data held in its systems. If this is not the case, "local" validations can be configured in Ozone that do not require a remote call.

        The financial institution must return a response that includes a status. If the status is set to `valid`, the consent is saved and processing continues.

        If the status is set to `invalid` the processing fails and an error response is sent to the TPP.

      operationId: validateConsent

      parameters:
        # common header parameters that set context
        - $ref: "#/components/parameters/providerId"
        - $ref: "#/components/parameters/aspspId"
        - $ref: "#/components/parameters/callerOrgId"
        - $ref: "#/components/parameters/callerClientId"
        - $ref: "#/components/parameters/callerSoftwareStatementId"
        - $ref: "#/components/parameters/apiUri"
        - $ref: "#/components/parameters/apiOperation"
        - $ref: "#/components/parameters/consentId"
        - $ref: "#/components/parameters/callerInteractionId"
        - $ref: "#/components/parameters/ozoneInteractionId"
        - $ref: "#/components/parameters/psuIdentifier"

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/consent"

      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/consentValidateResponse"
        '400':
          description: failed operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"


components:
  schemas:
    augmentConsentResponse:
      description: |
        Fields to be added to the consent

        ***TODO***: Specify the fields that must be augmented for CBUAE consents
      type: object
      additionalProperties: true

    consent:
      description: |

        A consent in its current state.

        If the consent has been authorised, then it can be expected that the financial institution would have patched in `accountIds` and `psuIdentifier` fields.

        Additionally, the financial institution may also patch in an arbitrary set of fields along with consent in the `supplementaryInformation` field.

        •••TODO••• Import the schemas for the consent from the CBUAE specification

      allOf:
        - $ref: "#/components/schemas/newConsent"
        - $ref: "#/components/schemas/patchedConsent"

    newConsent:
      type: object
      properties:
        id:
          type: string
          description: |
            A unique identifier for the consent in uuid-v4 format.

        consentGroupId:
          type: string
          description: |
            A unique identifier for the consent group in uuid-v4 format.
            The consent group id is used to group together consents that are related to each other.

        requestUrl:
          type: string
          format: url
          description: |
            The request url of Http request that was received by Ozone from the TPP

        consentType:
          type: string
          description: |
            The type of the consent that is being created.

            Each financial institution's instance may support a different set of consent types
            The Consent Manager supports the creation of consents of different consent types depending on the standards supported.

            •••TODO••• Specify the consent types supported for CBUAE

        status:
          type: string
          description: |
            The current status of the consent

            The Consent Manager ensures that this field is synchronised with the status of the consent body (the disposition of that field depending on the underlying standard)

            •••TODO••• Specify the consent statuses supported for CBUAE

        request:
          type: object
          description: |
            The entire Http request body that was received by Ozone from the TPP to create the consent.

            The Consent Manager uses the consent type to identify the schema
            that should be used to validate the request. (These schemas are defined by the
            underlying standard)
          additionalProperties: true

        requestHeaders:
          type: object
          description: |
            The entire set of Http request headers that was received by Ozone from the TPP
          additionalProperties: true

        consentBody:
          $ref: "#/components/schemas/cbuaeConsentBody"

        interactionId:
          type: string
          description: |
            The heimdall interaction id that this consent is associated with.

        tpp:
          $ref: "#/components/schemas/tpp"

        ozoneSupplementaryInformation:
          type: object
          additionalProperties: true

        updatedAt:
          type: number

      required:
        - id
        - consentType
        - request
        - requestHeaders
        - tpp
      additionalProperties: true

    patchedConsent:
      type: object
      properties:
        psuIdentifiers:
          $ref: "#/components/schemas/psuIdentifiers"

        accountIds:
          type: array
          items:
            type: string
          minItems: 1
          description: |-
            An array of account ids associated with the consent. The array must be populated once consent has been authorised.
            For payment consents, the array must always have one element - the debtor account from which the payment will be made
            For CBPII consents, the array must always have one element - the account for which CoF requests will be answered
            For AIS requests, the array may contain multiple values, representing each of the payment accounts for which an AIS service will be provided.

        supplementaryInformation:
          description:
            Contains additional information at the discretion of the financial institution.

          type: object
          additionalProperties: true

        interactionId:
          type: string
          description: The heimdall interaction id that this consent is associated with. This is updated by heimdall and must not be set by financial institutions.

        paymentContext:
          type: object
          additionalProperties: true

        ConnectToken:
          type: string
          description: A bearer token that will be sent as the `Authorization` header for calls to Ozone Connect made under this consent.
      additionalProperties: true

    tpp:
      type: object
      description: |
        The TPP record as held by Ozone.

        If Ozone TPP Connect has been integrated into a directory, the `directoryRecord` provides the TPP's directory record as held by Ozone in base 64 encoded format.

      required:
        - clientId
        - orgId
        - softwareStatementId
        - tppName

      properties:
        clientId:
          type: string
          description: The clientId for the TPP as issued by Ozone

        orgId:
          type: string
          description: The organization id for the TPP

        softwareStatementId:
          type: string
          description: The organization id for the TPP

        tppName:
          type: string
          description: The name of the TPP

        directoryRecord:
          type: string
          description: The latest copy of the TPP directory record if the TPP has registered with a directory

      additionalProperties: false

    cbuaeConsentBody:
      type: object
      description: |
        An object representing the current state of the consent.
        This includes the entire request, augmented by additional computed properties
        (e.g. ids, charges etc)

        The Ozone Consent Manager caters to consents from various standards. The actual schema for each consentBody would be determined by the underlying standard.

        •••TODO••• Import the schemas for the consentBody from the CBUAE specification

      additionalProperties: true

    psuIdentifiers:
      type: object
      description: |
        The PSU that is associated with this consent.

        The `PSUIdentifiers` object may have artitrary custom fields that an financial institution may use to
        identify the PSU.

        However, all `PSUIdentifiers` must have a mandatory `userId` field that provides a unique
        user id for the PSU.

        The consent is initially created without a PSU identified.

        The value must be specified once the consent is authorised.
      properties:
        userId:
          type: string
      required:
        - userId
      additionalProperties: true

    ValidateResponseStatusEnum:
      type: string
      enum:
        - valid
        - invalid

    consentValidateResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            status:
              $ref: "#/components/schemas/ValidateResponseStatusEnum"
            code:
              type: string
            description:
              type: string

        meta:
          $ref: "#/components/schemas/Meta"

    Meta:
      type: object
      additionalProperties: false

    Error:
      type: object
      properties:
        errorCode:
          type: string
          description: Error code identifying the problem occured
        errorMessage:
          type: string
          description: Message describing what problem has occured
        propogateError:
          type: boolean
          description: optional field if error want to propogate

  parameters:
    aspspId:
      name: o3-aspsp-id
      in: header
      schema:
        type: string
      required: true
      deprecated: true
      description:
        Identifier for the financial institution that the request is targetted to.
        This header is deprecated and will be removed in a future version of Ozone Connect. Use `o3-provider-id` instead.

    providerId:
      name: o3-provider-id
      in: header
      schema:
        type: string
      required: true
      description: Identifier for the financial institution that the request is targetted to

    callerOrgId:
      name: o3-caller-org-id
      in: header
      schema:
        type: string
      description: An identifier for the organization calling the API

    callerClientId:
      name: o3-caller-client-id
      in: header
      schema:
        type: string
      description: An identifier for the OIDC clientId calling the API

    callerSoftwareStatementId:
      name: o3-caller-software-statement-id
      in: header
      schema:
        type: string
      description: An identifier for the software statement calling the API

    apiUri:
      name: o3-api-uri
      in: header
      schema:
        type: string
      required: true
      description: The parameterised URL of the API being called by the caller

    apiOperation:
      name: o3-api-operation
      in: header
      schema:
        type: string
      required: true
      description: The API operation carried out by the caller (e.g. GET, POST, PUT, DELETE, PATCH)

    consentId:
      name: o3-consent-id
      in: header
      schema:
        type: string
      description: The consentId for which this call is being made

    callerInteractionId:
      name: o3-caller-interaction-id
      in: header
      schema:
        type: string
      description: The interaction ID passed in by the caller, if any

    ozoneInteractionId:
      name: o3-ozone-interaction-id
      in: header
      schema:
        type: string
      required: true
      description: An interaction ID generated by Ozone if the caller did not send in one. If the callerInteractionId is specified, this takes the same value.

    psuIdentifier:
      name: o3-psu-identifier
      in: header
      schema:
        type: string
      required: true
      description: A Base64 encoded representation of the psuIdentifier JSON object.

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT