openapi: 3.0.1

servers:
  - url: https://{your-cm-server}
    description: Consent manager for the tenant

info:
  title: Ozone Connect - Service Initiation APIs
  description: |
    This document provides the OAS3 specification for Service Initiation APIs for Ozone Connect.

    These APIs should be implemented by a Financial Institution so that Ozone can deliver Service Initiation capabilities to TPPs

    #### 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
    - review support for `SupplementaryInformation` field and remove if required

  contact:
    name: Ozone Financial Technology Limited

  version: Release 2024.31

tags:
  - name: payments
    description: |
      APIs that should be implemented by Financial Institutions to expose Service Initiation capability to TPPs.

paths:
  /payments:
    post:
      tags:
        - payments
      summary: Make a payment
      description: |
        This API is called by Ozone Connect to instruct a Financial Institution to initiate a payment once it has received a payment
        instruction from a TPP that has passed all local validations.

        The Financial Institution must process the payment and indicate a failure response (if the payment fails technical validation) or a
        success response (if the payment passess technical validation and is submitted to the payment rails for processing)

        The Financial Institution must generate a unique `PaymentId` that can be sent on to the TPP as a reference for the payment.

        If the underlying consent has been patched with a `bankConnectToken`, then the token is passed in as the authorization header.

      operationId: makePayment
      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/PaymentPostRequest"

      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentPostResponse"
        '400':
          description: failed operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - bearerAuth: []

  /payments/:paymentId:
    get:
      operationId: getPayment
      tags:
        - payments
      summary: Get a payment
      description: |
        Ozone can call this API from Financial Institutions to retrieve payment information.
      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"

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

  /payments/:paymentId/report-file:
    get:
      tags:
        - payments
      summary: report file for bulk payments
      description: |
        This API is called by Ozone Bank Connect to get a report file for a set of bulk payments

      operationId: reportFile
      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"


      responses:
        '200':
          description: successful operation
          content:
            '*/*':
              schema:
                type: string
                description: Any content type.

        '400':
          description: failed operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - bearerAuth: []


components:
  schemas:

    PaymentPostRequest:
      type: object
      properties:
        requestUrl:
          type: string
          description: |
            The (Ozone) URL at which the TPP requested for the payment

        paymentType:
          $ref: "#/components/schemas/PaymentType"

        request:
          $ref: "#/components/schemas/PaymentRequestBody"

        requestHeaders:
          $ref: "#/components/schemas/PaymentRequestHeaders"

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

        supplementaryInformation:
          $ref: "#/components/schemas/SupplementaryInformation"

      required:
        - paymentType
        - request
        - requestHeaders
        - tpp

      additionalProperties: false

    PaymentRequestBody:
      type: object
      description: |
        The entire HTTP request body that was received by Ozone from the TPP.

        The type can be used to identify the schema
        that should be used to validate the request.

        •••TODO•••: This field will be updated in the next release to include the CBUAE payment request schema.
      additionalProperties: true

    PaymentRequestHeaders:
      type: object
      description: |
        The entire set of HTTP request headers that was received by Ozone from the TPP
      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

    SupplementaryInformation:
      type: object
      description: |
        The `SupplementaryInformation` object may have arbitrary custom fields that a Financial Institution may use

      additionalProperties: true

    PaymentType:
      type: string
      description: |
        The type of the payment that is being created.

        ***TODO***: This field will consist of the enumeration of payment types supported by CBUAE. This will be updated in the next release.

    PaymentPostResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/CbuaePaymentPostResponseBody"
        meta:
          $ref: "#/components/schemas/Meta"

    CbuaePaymentPostResponseBody:
      description: |
        The payment response to be passed on to the TPP.

        The structure of this response is aligned to the structure of the response for the CBUAE payment initiation API.

        ***TODO***: This field will be updated in the next release to include the CBUAE payment response schema.
      type: object
      additionalProperties: true

    PaymentGetResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/PaymentGetResponseBody"
        meta:
          $ref: "#/components/schemas/Meta"

    PaymentGetResponseBody:
      description: |
        A descriptor for a Payment.

        The structure of this response is aligned to the structure of the response for the CBUAE payment initiation API.

        ***TODO***: This field will be updated in the next release to include the CBUAE payment response schema.
      type: object
      additionalProperties: true

    #
    # Common types
    #
    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
        propagateError:
          type: boolean
          description: optional field if error want to propagate

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

    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.

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

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

    callerSoftwareStatementId:
      name: o3-caller-software-statement-id
      in: header
      schema:
        type: string
      required: false
      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
      required: false
      description: The consentId for which this call is being made

    callerInteractionId:
      name: o3-caller-interaction-id
      in: header
      schema:
        type: string
      required: false
      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: false
      description: A Base64 encoded representation of the psuIdentifier JSON object.

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