Page Comparison

openapi: 3.0.1

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

info:
  title: Ozone Connect - Service Initiation APIs
  description: |
    This document provides an API description in [OpenAPI](https://spec.openapis.org/oas/v3.0.1.html)
     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

    ####### Changes in Release 2024.3746.0

    * AddedChanged `default``tpp` responseproperty toin each`post operation/payments` to aidprovide understandingmore ofinformation errorabout handlingthe requirements.
     * AddedTPP missingand `description`the propertiesClient throughsoftware thestatement
document.

    * Removed `additionalProperties: true` as not required and causes tooling issues `FollowingServiceLevel` enum from `CurrencyRequest.ChargeBearer`

    * Removed `PaymentSequenceNumber` from `instruction.PaymentSequenceNumber`

    #### Changes in VersionRelease 2024.3443.10

    * RemovedAdded propagateError field from the Error object.

    * Update exchangeRate and rateType properties
`OpenFinanceBilling` object to request and response body of POST Payments and in GET Payments.

   * Refactored#### SecurityChanges Schemein Objects to use common definitions across all API Hub APIs
    
    * Implemented the correct Security Requirements for this API description, reflecting security patterns available in API HubRelease 2024.37.0

    * Added `default` response to each operation to aid understanding of error handling requirements.

    * Added missing `description` properties through the document.

    * Removed `additionalProperties: true` as not required and causes tooling issues

    #### Changes in Version 2024.34.1

    * Introduced new endpoint Get /payment-consents/{consentId}/refundRemoved propagateError field from the Error object.

    * CosmeticUpdate changesexchangeRate -and RequestrateType Responseproperties
Changes
   contact: * Refactored Security Scheme name:Objects Ozoneto Financialuse Technologycommon Limiteddefinitions across all API version: 2024.37.0Hub APIs

tags:   - name:* paymentsImplemented the correct Security  description: Requirements for this API description, reflecting security patterns available in API Hub

    #### Changes in Version 2024.34

    * Introduced new endpoint Get /payment-consents/{consentId}/refund.

    * Cosmetic changes - Request Response Changes

  contact:
    name: Ozone Financial Technology Limited

  version: 2024.46.0

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

security:
  - {}
  - OzoneConnectApiKey: []
  - OzoneConnectClientCredentials: [
      "placeholder"
    ]
  - OzoneConnectJwtAuth: []

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"

      security:
        - {}
        - OzoneConnectApiKey: []
        - OzoneConnectClientCredentials: [
            "placeholder"
          ]
        - OzoneConnectJwtAuth: []
        - OzoneConnectServiceInitiationToken: []

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

      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AEPaymentIdResponse"
        '400':
          description: failed operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default: 
          $ref: "#/components/responses/Error"
  /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"
        - $ref: "#/components/parameters/paymentId"

      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AEPaymentIdResponse"
        '400':
          description: failed operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
           $ref: "#/components/responses/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"
        - $ref: "#/components/parameters/paymentId"

      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"
        default:
           $ref: "#/components/responses/Error"
  /payment-consents/{consentId}/refund:
    get:
      tags:
        - payments
      summary: Retrieve a Payment Consent
      description: |
        Ozone can call this API from Financial Institutions to retrieve payment information.
      operationId: getRefund
      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"

        - name: consentId
          in: path
          schema:
            type: string
          required: true
          description: |
            Identifies the consent by an id

      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RefundGetResponse"
        '400':
          description: failed operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
           $ref: "#/components/responses/Error"
components:
  responses:
    Error:
      description: Default error response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:

    PaymentPostRequest:
      description: The properties of a payment request
      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/AEPaymentAndFilePaymentRequest"

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

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

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

      required:
        - paymentType
        - request
        - requestHeaders
        - tpp

      additionalProperties: false

    AEPaymentAndFilePaymentRequest:
      description: The payment request body as received from the TPP
      oneOf:
        - $ref: "#/components/schemas/AEPaymentRequest"
        - $ref: "#/components/schemas/AEFilePaymentRequest"

    AEPaymentRequest:
      description: |
        Payment Request Schema
      type: "object"
      additionalProperties: false
      required:
        - "Data"
      properties:
        Data:
          description: Primary data for the request
          type: "object"
          additionalProperties: false
          required:
            - "ConsentId"
            - "Instruction"
            - "PersonalIdentifiableInformation"
            - "PaymentPurposeCode"
            - "OpenFinanceBilling"
          properties:
            ConsentId:
              $ref: "#/components/schemas/AEConsentId"
            Instruction:
              $ref: "#/components/schemas/AEPaymentInstruction"
            CurrencyRequest:
              $ref: "#/components/schemas/AECurrencyRequest"
            PersonalIdentifiableInformation:
              $ref: "#/components/schemas/AEJWEPaymentPII"
            PaymentPurposeCode:
              $ref: "#/components/schemas/AEPaymentPurposeCode"
            DebtorReference:
              $ref: "#/components/schemas/AEStructuredDebtorReference"
            CreditorReference:
              $ref: "#/components/schemas/AEStructuredCreditorReference"
     AEJWEPaymentPII:       typeOpenFinanceBilling:
string       description: |2-      $ref: "#/components/schemas/AEServiceInitiationOpenFinancePaymentBilling"

    AEServiceInitiationOpenFinancePaymentBilling:
A   JSON Web Encryption (JWE)type: object,
which encapsulates a JWS. The value isrequired:
a compact serialization      - Type
     of aproperties:
JWE, which is a string consisting of five base64url-encodedType:
parts joined by dots. It encapsulates encrypted content using JSON dataenum:
structures.            - Collection
The decrypted JWS content has the structure of the AEPaymentPII schema.  - LargeValueCollection
  AEConsentId:       type: string  - PushP2P
   minLength: 1       maxLength: 128- PullP2P
     description: >-      - Me2Me
 Unique identification assigned by the TPP to identify the consentdescription: The type payment for billing
   resource.       AEFilePaymentRequesttype: string
     description: |   MerchantId:
          description: "MerchantId"
File Payment Request Schema       type: "objectstring"
      additionalProperties: false   minLength: 8
  required:        maxLength: -20
"Data"       propertiesdescription: Billing parameters specified by the TPP for a Data:payment initiation
         descriptionadditionalProperties: Primaryfalse
data
for the request  AEServiceInitiationOpenFinancePaymentBillingGet:
        type: "object"
      required:
   additionalProperties:  false   - Type
      requiredproperties:
        NumberOfSuccessfulTransactions:
   - "ConsentId"      type: "integer"
     - "PaymentPurposeCode"    description: |
     properties:       Number of individual transactions successfully executed ConsentId:by the LFI.
            $ref: "#/components/schemas/AEConsentId"
            Instruction:This is returned by the LFI after the file is fully processed.
        Type:
         $ref enum: "#/components/schemas/AEFilePaymentConsent"
            - Collection
PaymentPurposeCode:            - LargeValueCollection
 $ref: "#/components/schemas/AEPaymentPurposeCode"          - PushP2P
 DebtorReference:           - PullP2P
  $ref: "#/components/schemas/AEStructuredDebtorReference"      AEFilePaymentConsent:   - Me2Me
  type: "object"       description: |The type payment for billing
    A file based payment consent.  type: string
      A Consent definitionMerchantId:
for defining Multi Payments       requireddescription: "MerchantId"
       -   type: "FileTypestring"
         - "FileHash"minLength: 8
       - "NumberOfTransactions"  maxLength: 20
     - "ControlSum"
      properties:
  description: Billing parameters specified by the TPP for a payment initiation
      FileTypeadditionalProperties: false

    AEJWEPaymentPII:
   $ref: "#/components/schemas/AEFileType"   type: string
      description: |2-
 FileHash:           $ref: "#/components/schemas/AEFileHash"
        FileReference:
    A JSON Web Encryption (JWE) object, which encapsulates a JWS. The value is a compact serialization
     $ref: "#/components/schemas/AEReference"      of a JWE, NumberOfTransactions:which is a string consisting of five base64url-encoded parts joined by $ref: "#/components/schemas/AEFileNumberOfTransactions"
        ControlSum:dots. It encapsulates encrypted content using JSON data structures.

           $ref: "#/components/schemas/AEControlSum"
  The decrypted JWS content has the structure of the AEPaymentPII schema.

    AEConsentId:
      type: string
      minLength: 1
      maxLength: 128
      RequestedExecutionDate:description: >-
        Unique identification assigned by the TPP to identify  $ref: "#/components/schemas/AERequestedExecutionDate"the consent
        resource.

    AEFilePaymentRequest:
      description: |
        File Payment Request Schema
      type: "object"
      additionalProperties: false
      required:
        - "Data"
      properties:
        Data:
          description: Primary data for the request
          type: "object"
          additionalProperties: false
          required:
            - "ConsentId"
            - "PaymentPurposeCode"
          properties:
            ConsentId:
              $ref: "#/components/schemas/AEConsentId"
            Instruction:
              $ref: "#/components/schemas/AEFilePaymentConsent"
            PaymentPurposeCode:
              $ref: "#/components/schemas/AEPaymentPurposeCode"
            DebtorReference:
              $ref: "#/components/schemas/AEStructuredDebtorReference"

    AEFilePaymentConsent:
      type: "object"
      description: |
        A file based payment consent.
        A Consent definition for defining Multi Payments
      required:
        - "FileType"
        - "FileHash"
        - "NumberOfTransactions"
        - "ControlSum"
      properties:
        FileType:
          $ref: "#/components/schemas/AEFileType"
        FileHash:
          $ref: "#/components/schemas/AEFileHash"
        FileReference:
          $ref: "#/components/schemas/AEReference"
        NumberOfTransactions:
          $ref: "#/components/schemas/AEFileNumberOfTransactions"
        ControlSum:
          $ref: "#/components/schemas/AEControlSum"
        RequestedExecutionDate:
          $ref: "#/components/schemas/AERequestedExecutionDate"
      additionalProperties: false

    AERequestedExecutionDate:
      description: |
        The date when the TPP expects the LFI to execute the payment.
        The date must be in the future and cannot be on the same day or a day in the past.
        The maximum date in the future that can be specified is 1 year from the day of the consent of the User to the TPP.
        All dates in the JSON payloads are represented in ISO 8601 date format.
      type: "string"
      format: "date"

    AEFileNumberOfTransactions:
      type: "integer"
      description: |
        Number of individual transactions contained in the payment information group.
    AEControlSum:
      description: |
        Total of all individual amounts included in the group, irrespective of currencies.
      type: "string"
      pattern: "^\\d{1,16}\\.\\d{2}$"
      example: "100.00"

    AEReference:
      description: |
        A reason or reference in relation to a payment.
        Reason or reference for the beneficiary regarding the Payment
      type: "string"
      minLength: 1
      maxLength: 120

    AEFileType:
      type: "string"
      description: "Specifies the payment file type"
      minLength: 1
      maxLength: 40
    AEFileHash:
      type: "string"
      description: "A base64 encoding of a SHA256 hash of the file to be uploaded."
      minLength: 1
      maxLength: 44

    AEStructuredCreditorReference:
      description: |
        A reason or reference in relation to a payment, set to facilitate a structured Creditor reference consisting of:

        * TPP ID and BIC for the Debtor Account, followed by freeform text to a maximum of 120 characters.

        The TPP ID value will match the organization ID value from the Trust Framework, and therefore will be a v4 UUID.

        A BIC is specific according to the standard format for ISO 20022, and can therefore be either 8 or 11 characters in length.

        If the value of the concatenated string exceeds 120 characters, the TPP must first omit or truncate the freeform element of the reference.
      type: "string"
      minLength: 1
      maxLength: 120
      pattern: "^TPP=[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12},BIC=[A-Z0-9]{4}[A-Z0-9]{2}[A-Z0-9]{2}([A-Z0-9]{3}){0,1}($|,.+$)"

    AEPaymentInstruction:
      type: "object"
      additionalProperties: false
      required:
        - "Amount"
      description: "The Initiation payload is sent by the initiating party to the LFI. It is used to request movement of funds from the debtor account to a creditor for a single payment."
      properties:
        Amount:
          $ref: "#/components/schemas/AEActiveCurrencyAmount"
    PaymentType:
      type: string
      description: |
        The type of the payment that is being created.

        Each LFI's instance may support a different set of payment types
        depending on the standards supported.

        For example,

          - cbuae-payment (Single Instant Payment, Multi Payment - Fixed and Variable Recurring Payment, Future Dated Payment etc)
          - cbuae-file-payment

    PaymentRequestHeaders:
      type: object
      description: |
        The entire set of HTTP request headers that was received by Ozone from the TPP

    tpp:
      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.
      type: object
      required:
        - clientId
        - orgId
        - softwareStatementId
        - tppId
        - tppName
        - decodedSsa
      properties:
        clientId:
          description: The client identifier for the TPP as issued by the Trust Framework
          type: string
          pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$'
      additionalProperties: false 
tppId:
   AERequestedExecutionDate:       description: |The identifier used by the API Hub to uniquely Theidentify date when the TPP
expects the LFI to execute the payment.    type: string
   The date must be in the future and cannot be on the same day or a day in the past.
        The maximum date tppName:
          description: The TPP name recorded in the futureTrust thatFramework
can be specified is 1 year from the day of thetype: consentstring
of the User to the TPP.   obieTppId:
     All dates in the JSON payloadsdescription: are represented in ISO 8601 date format.
      type: "string"
      format: "date"

    AEFileNumberOfTransactions:The UK market TPP identifier. This property is not used for CBUAE and is therefore 
        type: "integer"   marked as deprecated.
 description: |        type: Numberstring
of individual transactions contained in the payment information group.  deprecated: true
 AEControlSum:       descriptionsoftwareStatementId:
|         Total ofdescription: allThe individualsoftware amountsstatement includedidentifier infor the group,Client.
 irrespective of currencies.       type: "string"
        pattern: "^\\d{1,16}\\.\\d{2}$"obieSoftwareStatementId:
          exampledescription: "100.00"The UK market software statement identifier. AEReference:This property is not used for  description:CBUAE
|         A reason or referenceand inis relationtherefore tomarked aas paymentdeprecated.
         Reason ortype: referencestring
for the beneficiary regarding the Payment     deprecated: true
type: "string"       minLengthobieSoftwareStatementName:
1       maxLength: 120  description: The UK market AEFileType:software statement name. This property is not type: "string"
 used for CBUAE and 
   description: "Specifies the payment file type"    is therefore marked minLength:as 1deprecated.
      maxLength: 40   type: string
AEFileHash:       type: "string"  deprecated: true
   description: "A base64 encoding of adirectoryRecord:
SHA256 hash of the file to be uploaded."   type: string
  minLength: 1       maxLengthdescription: 44The latest copy of the TPP AEStructuredCreditorReference:directory record retrieve from the CBUAE Trust description:Framework |
        A reason or reference indirectory, relationencoded toas a payment,Base set64 tostring
facilitate a structured Creditor reference consisting of:    format: base64
    * TPP ID and BICssa:
for the Debtor Account, followed by freeform text to a maximumdescription: ofThe 120encoded characters.Software Statement Assertion. This property is not used for CBUAE Theand TPPis
ID value will match the organization ID value from the Trust Framework, and therefore willmarked be a v4 UUIDas deprecated.
         A BICtype: isstring
specific according to the standard format for ISO 20022, and can thereforedeprecated: betrue
either 8 or 11 characters in length.  decodedSsa:
       If the value of the concatenated string exceeds 120 characters, the TPP must first omit or truncate the freeform element of the reference.
      type: "string"$ref: "#/components/schemas/softwareStatementProperties"
        orgId:
          description: The organization identifier for the TPP
      minLength: 1   type: string
  maxLength: 120       pattern: "^TPP='^[0-9a-fA-fF]{8}-[0-9a-ffA-F]{4}-4[0-9a-fA-fF]{43}-[0-9a-f]{4}-89abAB][0-9a-f]{12},BIC=[A-Z0-9]{4}[A-Z0-9]{2}[A-Z0-9]{2}([A-Z0-9fA-F]{3}){0,1}($|,.+$)"-[0-9a-fA-F]{12}$'
  
    AEPaymentInstructionsoftwareStatementProperties:
      typedescription: "object"
      additionalProperties: false
 |
        The decoded software statement retrieved from the Trust Framework that provides 
    required:    the properties of the Client.
- "Amount"       
 - "PaymentSequenceNumber"      Please descriptionnote: "The Initiation payload is sent by the initiating party to the LFI. It is used to request movement of funds from the debtor account to a creditor for a single payment."
      properties:


          - The JSON payload will contain other properties in addition to those listed 
            here. The properties listed here are considered most relevant for activities 
      Amount:      such as TPP logo retrieval $ref: "#/components/schemas/AEActiveCurrencyAmount"
and JWS verification.
       PaymentSequenceNumber:   - The content reflects elements of discovery metadata, $ref: "#/components/schemas/AEPaymentSequenceNumber"
which in generally
    AEPaymentSequenceNumber:       type: "string"defined as a file rather than an description:API. |Providing constraints such as
     This indicates the underlying sequence of the recurring`minLength` paymentand that`maxLength` is beingimpractical instructed.in this context

     For example:  The full software statement record is also *available 1in canthe representTrust theFramework. first
payment instruction       Please also *refer 12the canRegistration representFramework thepage twelfthin payment instructionthe CBUAE standards for
   minLength: 1    additional guidance on maxLength:these 10properties.
      patterntype: "^[1-9]\\d*$"object
      PaymentTypeproperties:
      type  redirect_uris:
string       description: |  description: The redirect URIs registered by the TheTPP typeat of the paymentTrust thatFramework
is being created.        type: array
Each LFI's instance may support a different set of payment typesitems:
        depending on the standards supported.type: string
        For example,client_name:
          description:  -Name cbuae-payment (Single Instant Payment, Multi Payment - Fixed and Variable Recurring Payment, Future Dated Payment etc)of the Client to be presented to the End-User.
          type: string
     - cbuae-file-payment  client_uri:
   PaymentRequestHeaders:       typedescription: objectURL of the home page of  description: |the Client.
          type: Thestring
entire set of HTTP request headers that was receivedlogo_uri:
by Ozone from the TPP      tppdescription: URL of the Client logo.
  type: object       descriptiontype: |string
        Thejwks_uri: TPP
record as held by Ozone.      description: URL of the IfClient OzoneJSON TPPWeb ConnectKey hasSet been(JWKS) integratedat intothe aTrust directory,Framework.
the `directoryRecord` provides the TPP's directory record as held by Ozone intype: basestring
64 encoded format.      client_id: 
required:         - clientIddescription: Unique Client Identifier.
     - orgId    type: string
   - softwareStatementId    roles:
    - tppName     description: The roles properties:under which the organization is registered at the Trust clientId:Framework.
          type: stringarray
          descriptionitems: The
clientId for the TPP as issued by Ozone     type: string
   orgId:     sector_identifier_uri:
     type: string    description: URL using the https scheme to description:be Theused organizationin idcalculating forPseudonymous theIdentifiers TPP
         softwareStatementId:   by the OP. Allows redirect URI values to type:be stringgrouped, easing registration
        description: The organization id for themanagement.
TPP          tppNametype: string
         application_type: string
          description: TheClient name of the TPPapplication type.
          directoryRecordtype: string
        organisation_id: type: string
          description: TheOrganization latestidentifier copyfor oforganization thethat TPP directory record if owns the TPPClient.
has registered with a directory        additionalPropertiestype: falsestring

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


    AEPaymentIdResponse:
      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.
      type: "object"
      additionalProperties: false
      required:
        - "data"
      properties:
        data:
          type: "object"
          description: "Required fields are common for all the payments including file payment. Apart from that, paymentTransactionId is required for all payments except file payments"
          additionalProperties: false
          required:
            - "id"
            - "status"
            - "statusUpdateDateTime"
            - "creationDateTime"
            - "paymentPurposeCode"
          properties:
            id:
              description: An API specific unique identification as assigned by the LFI to identify the domestic Payment resource.
              type: string
            consentId:
              description: Unique identification assigned by the TPP to identify the consent resource.
              type: string
            paymentTransactionId:
              description: |
                This is an end-to-end identifier that is generated by the underlying payment rails when it is sent from an Originating LFI to a Receiving LFI.
                For IPP transactions, this is the IPP generated identifier.

                        This property is not the same as the `transactionId` in the Bank Data Sharing Transactions API.
    

                   The `paymentTransactionId` must be populated if the payment is processed by the LFI, and updated at the Consent Manager Payment Log API using the `patch` operation.
              type: string
            status:
              description: |
                Specifies the status of the payment information group
                * Pending: Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed.
                * Rejected: The payment initiation has been rejected
                * AcceptedSettlementCompleted: Settlement of the Debtor's account has been completed
                * AcceptedCreditSettlementCompleted: When the Creditor account has been credited with the funds of the payment initiated via the TPP
                * AcceptedWithoutPosting:  When the Recipient Bank has accepted the payment but has not applied the credit to the Creditor account yet.
              type: string
              enum:
                - "Pending"
                - "AcceptedSettlementCompleted"
                - "AcceptedCreditSettlementCompleted"
                - "AcceptedWithoutPosting"
                - "Rejected"
                - "Received"
            statusUpdateDateTime:
              description: Date and time at which the resource status was updated.
              type: string
              format: date-time
            creationDateTime:
              description: Date and time at which the message was created.
              type: string
              format: date-time
            charges:
              $ref: "#/components/schemas/AECharges"
            exchangeRate:
              $ref: "#/components/schemas/AEExchangeRateInformation"
            currencyRequest:
              $ref: "#/components/schemas/AECurrencyRequest"
            instruction:
              $ref: "#/components/schemas/AEPaymentInstruction"
            paymentPurposeCode:
              $ref: "#/components/schemas/AEPaymentPurposeCode"
            debtorReference:
              $ref: "#/components/schemas/AEStructuredDebtorReference"
            openFinanceBilling:
              $ref: "#/components/schemas/AEServiceInitiationOpenFinancePaymentBillingGet"
        meta:
          $ref: "#/components/schemas/Meta"

    AECharges:
      description: List of charges associated with the payment request
      type: "array"
      items:
        type: "object"
        additionalProperties: false
        description: |
          Set of elements used to provide details of a charge for the payment initiation.
          * For Payments, these Charges are on the Debtor.
        required:
          - "chargeBearer"
          - "type"
          - "amount"
        properties:
          chargeBearer:
            $ref: "#/components/schemas/AEChargeBearerType1Code"
          type:
            $ref: "#/components/schemas/AEExternalPaymentChargeTypeCode"
          amount:
            $ref: "#/components/schemas/AEActiveCurrencyAmount"

    AEChargeBearerType1Code:
      description: "Specifies which party/parties will bear the charges associated with the processing of the payment transaction."
      type: "string"
      enum:
        - "BorneByCreditor"
        - "BorneByDebtor"
        - "FollowingServiceLevel"
        - "Shared"

    AEExternalPaymentChargeTypeCode:
      description: "Charge type, in a coded form."
      type: "string"
      enum:
        - "VAT"
        - "Fees"

    AEActiveCurrencyAmount:
      description: |
        The Currency and Amount relating to the Payment, Refund or Request to Pay
      type: "object"
      required:
        - "amount"
        - "currency"
      properties:
        amount:
          $ref: "#/components/schemas/AEActiveOrHistoricAmount"
        currency:
          $ref: "#/components/schemas/AEActiveOrHistoricCurrencyCode"

    AEActiveOrHistoricAmount:
      description: "A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217."
      type: "string"
      pattern: "^\\d{1,16}\\.\\d{2}$"
      example: "100.00"

    AEActiveOrHistoricCurrencyCode:
      description: "A 3 character alphabetic code allocated to a currency under an international currency identification scheme, as described in the latest edition of the international standard ISO 4217 'Codes for the representation of currencies and funds'."
      type: "string"
      pattern: "^[A-Z]{3,3}$"
      example: "AED"

    AEExchangeRateInformation:
      type: "object"
      additionalProperties: false
      required:
        - "unitCurrency"
        - "exchangeRate"
        - "rateType"
      description: "Further detailed information on the exchange rate that has been used in the payment transaction."
      properties:
        unitCurrency:
          description: "Currency in which the rate of exchange is expressed in a currency exchange. In the example 1GBP = xxxCUR, the unit currency is GBP."
          type: "string"
          pattern: "^[A-Z]{3,3}$"
        exchangeRate:
          description: "The factor used for conversion of an amount from one currency to another. This reflects the price at which one currency was bought with another currency."
          type: "number"
        rateType:
          description: "Specifies the type used to complete the currency exchange."
          type: "string"
          enum:
            - "Actual"
            - "Agreed"
            - "Indicative"
        contractIdentification:
          description: "Unique and unambiguous reference to the foreign exchange contract agreed between the initiating party/creditor and the debtor agent."
          type: "string"
          minLength: 1
          maxLength: 256
        expirationDateTime:
          description: "Specified date and time the exchange rate agreement will expire.All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone. An example is below:\n2017-04-05T10:43:07+00:00"
          type: "string"
          format: "date-time"

    AECurrencyRequest:
      description: |
        The details of the non-local currency or FX request that has been agreed between the User and the TPP.
        The requested ChargeBearer and ExchangeRateInformation are included in this object may be overwritten by the LFI in the returned Consent object.
      type: "object"
      additionalProperties: false
      required:
        - "currencyOfTransfer"
      properties:
        instructionPriority:
          description: "Indicator of the urgency or order of importance that the instructing party would like the instructed party to apply to the processing of the instruction."
          type: "string"
          enum:
            - "Normal"
            - "Urgent"
        extendedPurpose:
          description: "Specifies the purpose of an international payment, when there is no corresponding 4 character code available in the ISO20022 list of Purpose Codes."
          type: "string"
          minLength: 1
          maxLength: 140
        chargeBearer:
          $ref: "#/components/schemas/AEChargeBearerType1Code"
        currencyOfTransfer:
          description: "Specifies the currency of the to be transferred amount, which is different from the currency of the debtor's account."
          type: "string"
          pattern: "^[A-Z]{3,3}$"
        destinationCountryCode:
          description: "Country in which Credit Account is domiciled. Code to identify a country, a dependency, or another area of particular geopolitical interest, on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code)."
          type: "string"
          pattern: "[A-Z]{2,2}"
        exchangeRateInformation:
          type: "object"
          additionalProperties: false
          required:
            - "unitCurrency"
            - "rateType"
          description: "Provides details on the currency exchange rate and contract."
          properties:
            unitCurrency:
              description: "Currency in which the rate of exchange is expressed in a currency exchange. In the example 1GBP = xxxCUR, the unit currency is GBP."
              type: "string"
              pattern: "^[A-Z]{3,3}$"
            exchangeRate:
              description: "The factor used for conversion of an amount from one currency to another. This reflects the price at which one currency was bought with another currency."
              type: "number"
            rateType:
              description: "Specifies the type used to complete the currency exchange."
              type: "string"
              enum:
                - "Actual"
                - "Agreed"
                - "Indicative"
            contractIdentification:
              description: "Unique and unambiguous reference to the foreign exchange contract agreed between the initiating party/creditor and the debtor agent."
              type: "string"
              minLength: 1
              maxLength: 256


    AEPaymentPurposeCode:
      description:  A category code that relates to the type of services or goods that corresponds to the underlying purpose of the payment. The code must conform to the published AANI payment purpose code list.
      type: "string"
      minLength: 1
      maxLength: 4
      pattern: "^[A-Z]{3}$"

    AEStructuredDebtorReference:
      description: |
        A reason or reference in relation to a payment, set to facilitate a structured Debtor reference consisting of:

        * For payments to Merchants: TPP ID, Merchant ID, BIC for the Creditor Account, followed by freeform text to a maximum of 120 characters.

        * For other payments: TPP ID and BIC for the Creditor Account, followed by freeform text to a maximum of 120 characters.

        The TPP ID value will match the organization ID value from the Trust Framework, and therefore will be a v4 UUID.

        The Merchant ID wil be as per the existing IPP rules for the Merchant identification, and will incorporate the Trade License number for the Merchant.

        A BIC is specific according to the standard format for ISO 20022, and can therefore be either 8 or 11 characters in length.

        If the value of the concatenated string exceeds 120 characters, the TPP must omit or truncate the freeform element of the reference.
      oneOf:
        - description: Merchant-initiated payment, containing Merchant identifier
          type: "string"
          minLength: 1
          maxLength: 120
          pattern: "^TPP=[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12},Merchant=[A-Z0-9]{3}-[A-Z]{4}-TL.+-[0-9]{4},BIC=[A-Z0-9]{4}[A-Z0-9]{2}[A-Z0-9]{2}([A-Z0-9]{3}){0,1}($|,.+$)"
        - description: Non-merchant payment, containing TPP ID, BIC, and free form text
          type: "string"
          minLength: 1
          maxLength: 120
          pattern: "^TPP=[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12},BIC=[A-Z0-9]{4}[A-Z0-9]{2}[A-Z0-9]{2}([A-Z0-9]{3}){0,1}($|,.+$)"

    RefundGetResponse:
      description: Response to a request to the Debtor details for a given payment, in order to initiate a refund. Requires the consent of the Debtor to be retrieved, enforced at the API Hub.
      type: object
      properties:
        data:
          $ref: "#/components/schemas/RefundGetResponseBody"
        meta:
          $ref: "#/components/schemas/Meta"

    RefundGetResponseBody:
      description: Primary data for the response
      type: object
      required:
        - refundAccount
      properties:
        consentId:
          description: |
            Unique identification assigned by the TPP to identify the consent resource.
          type: "string"
          minLength: 1
          maxLength: 128
        refundAccount:
          $ref: "#/components/schemas/AEDebtorAccount"

    AEDebtorAccount:
      description: "Unambiguous identification of the account of the debtor to which a debit entry will be made."
      type: "object"
      required:
        - "schemeName"
        - "identification"
        - "name"
      properties:
        schemeName:
          description: "Name of the identification scheme, in a coded form as published in an external list."
          type: "string"
          enum:
            - "IBAN"
            - "AccountNumber"
        identification:
          description: |
            Identification for the account assigned by the LFI based on the Account Scheme Name.
            This identification is known by the User account owner.
          type: "string"
          minLength: 1
        name:
          $ref: "#/components/schemas/AEName"

    AEName:
      type: "object"
      description: |
        The Account Holder Name is the name or names of the Account owner(s) represented at the account level
      properties:
        en:
          type: "string"
          description: "English value of the string"
          maxLength: 70
        ar:
          type: "string"
          description: "Arabic value of the string"
          maxLength: 70
      additionalProperties: false

    #
    # Common types
    #
    Meta:
      description: Metadata relevant to the resource.
      type: object
      additionalProperties: false

    Error:
      description: Default error response payload structure for Ozone Connect
      type: object
      properties:
        errorCode:
          type: string
          description: Error code identifying the problem that occurred
        errorMessage:
          type: string
          description: Message describing what problem has occurred

  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: true
      description: An identifier for the organization calling the API

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

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

    callerInteractionId:
      name: o3-caller-interaction-id
      in: header
      schema:
        type: string
      required: true
      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.

    paymentId:
      name: paymentId
      description: The identifier for a given payment instruction
      in: path
      required: true
      schema:
        type: string

  securitySchemes:
    OzoneConnectApiKey:
      description: Communications between the API Hub and the LFI Ozone Connect implementation are secured using an API Key, which is a secret shared between the API Hub and the LFI.
      type: apiKey
      in: header
      name: Authorization
    OzoneConnectClientCredentials:
      type: oauth2
      description: |
        Communications between the API Hub and the LFI Ozone Connect implementation are secured using a Client Credentials grant type.

                LFIs must host an OAuth 2.0 Authorization Server to utilise this security pattern. Scope values are set during the onboarding process, and represented by a placeholder in this API description.
      flows:
        clientCredentials:
          tokenUrl: "https://example.lfi.ae/token"
          scopes:
            placeholder: Placeholder for scopes, which are set by the LFI during onboarding
    OzoneConnectJwtAuth:
      description: | 
        Communications between the API Hub and the LFI Ozone Connect implementation are secured using the "JWT Auth" mechanism, where the Client presents a signed JSON Web Token as a credential.


               The Server MUST verify the signature in order to authenticate the Client.

        Please note that the value of the `scheme` parameter is not a registered HTTP Authentication Scheme, to indicate it is specific to Ozone Connect. Please refer to API Hub documentation for further details.
      type: http
      scheme: Ozone-Connect-JWT-Auth
    OzoneConnectServiceInitiationToken:
      description: |
         Communications between the API Hub and the LFI Ozone Connect implementation are secured using a Service Initiation Token.
       

        The API Hub will set an Access Token based on a value set by the LFI, which has been patched onto the associated consent. The value will be transmitted in the `Authorization` header, which is represented as a `Bearer` in this Security Scheme Object.

      type: http
      scheme: Bearer