Page Comparison

openapi: 3.0.1

servers:
  - url: https://{server}/v2024.07
    description: Ozone Connect - Service Initiation APIs
    variables:
      server:
        default: rs1.*
        description: The server that the API is hosted on.

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 an LFI so that Ozone
    can deliver Service Initiation capabilities to TPPs

  version: Version 2.2 Release 2022.39.1

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

paths:
  /payment-consent/action/validate:
    post:
      tags:
        - payments
      summary: Payment action validation
      description: |
        The API is called by Ozone to allow an LFI to carry out additional validations
        before a payment consent is created.

        The request body contains the entire payment 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 LFI)
        - populating charges and exchange rate information (in future versions)

        Note that an LFI 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 LFI must return a `PaymentConsentValidateResponse` which 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: validatePaymentConsent

      parameters:
        # common header parameters that set context
        - $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/PaymentConsentValidateRequest"

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

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

        The LFI 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 LFI 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/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/PaymentRequest"

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

  /payments/:paymentId:
    get:
      tags:
        - payments
      summary: Get a payment
      description: |
        Ozone can call this API from LFIs to retrieve payment information.
      parameters:
        # common header parameters that set context
        - $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/details:
    get:
      tags:
        - payments
      summary: Get payment details
      description: |
        In situations where an API supports retrieval of detailed payment information,
        Ozone can call this API from LFIs to retrieve detailed information.

      parameters:
        # common header parameters that set context
        - $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/PaymentDetailsResponse"
        400:
          description: failed operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    PaymentConsentValidateRequest:
      type: object
      oneOf:
        - $ref: "#/components/schemas/ConsentGetResponse"

    ConsentGetResponse:
      type: object
      description: |

        A consent in its current state.

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

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

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

            This is distinct from the ConsentId that is communicated back to PSUs and TPPs.

        consentType:
          $ref: "#/components/schemas/ConsentType"

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

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

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

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

        psuIdentifiers:
          $ref: "#/components/schemas/PSUIdentifiers"

        accountIds:
          $ref: "#/components/schemas/AccountIds"

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

      additionalProperties: false

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

        Each LFI'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.

        For example, for the UK OBIE standards, the following consent types are available:
          - account-access-consents
          - domestic-payment-consents
          - future-dated-payment-consents
          - standing-order-consents
          - international-payment-consents
          - international-future-dated-payment-consents
          - international-standing-order-consents

    Request:
      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. (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:
      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.

      oneOf:
        - $ref: "#/components/schemas/OBIEConsentBody"

    OBIEConsentBody:
      type: object
      description: |
        A representation of a consent body for a consent from the OBIE RW-API standards.

        It should be noted that the entire content payload (not just the fields listed below) is stored.

        The list of fields below identifies the common fields across all OBIE consents.

      properties:
        Data:
          type: object
          properties:
            ConsentId:
              type: string
              description: |
                A ConsentId generated by the LFI for the consent.

                This is different from the top-level `id` field which is used by Consent Manager.

            CreationDateTime:
              type: string
              format: date-time
              description: An ISO date-time representing when the consent was created

            Status:
              $ref: "#/components/schemas/ConsentStatusEnum"

            StatusUpdateDateTime:
              type: string
              format: date-time
              description: An ISO date-time representing when the consent status was last updated

          required:
            - ConsentId
            - CreationDateTime
            - Status
            - StatusUpdateDateTime
          additionalProperties: true

      required:
        - Data
      additionalProperties: true

    ConsentStatusEnum:
      type: string
      enum:
        - AwaitingAuthorisation
        - Authorised
        - Consumed
        - Rejected
        - Revoked
      description: The current status of the consent

    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.
      properties:
        clientId:
          type: string
        orgId:
          type: string
        softwareStatementId:
          type: string
        directoryRecord:
          additionalProperties: true

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

        The `PSUIdentifiers` object may have artitrary custom fields that an LFI 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

    SupplementaryInformation:
      type: object
      description: |
        The `SupplementaryInformation` object may have artitrary custom fields that an LFI may use

      additionalProperties: true

    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.

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

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

    ValidateResponseStatusEnum:
      type: string
      enum:
        - valid
        - invalid

    PaymentRequest:
      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/Request"

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

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

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

      required:
        - paymentType
        - request
        - requestHeaders
        - tpp

      additionalProperties: false

    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,

        For the UK OBIE standards, the following payment types are available:
          - domestic-payment
          - domestic-scheduled-payment
          - domestic-standing-order
          - domestic-vrp
          - file-payment
          - international-payment
          - international-scheduled-payments
          - international-standing-order

    PaymentResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/Payment"
        meta:
          $ref: "#/components/schemas/Meta"

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

    Payment:
      type: object
      description: |
        A descriptor for a Payment.

        This is a composite object that may be expanded in the future to support
        additional payment types for new API standards and payment types.
      oneOf:
        - $ref: "#/components/schemas/GenericPaymentResponse"

    GetPayment:
      type: object
      description: |
        A descriptor for a Payment.

        This is a composite object that may be expanded in the future to support
        additional payment types for new API standards and payment types.
      oneOf:
        - $ref: "#/components/schemas/GenericGetPaymentResponse"

    GenericPaymentResponse:
      type: object
      properties:
        id:
          type: string
        endToEndId:
          type: string
        rejectionReason:
          $ref: '#/components/schemas/RejectionReason'
        status:
          $ref: "#/components/schemas/PaymentStatusEnum"
        creationDateTime:
          type: string
          format: date-time
        statusUpdateDateTime:
          type: string
          format: date-time
        refundAccount:
          $ref: "#/components/schemas/RefundAccount"
        transactionId:
          description: This is mandatory for KSA.
          type: string
        charges:
          $ref: "#/components/schemas/Charges"
        instruction:
          type: object
          description: The current status of the payment. This is mandatory for KSA. The data will be passed without any validations.
          oneOf:
            - $ref: "#/components/schemas/KSAOBRefundInitiationInstructionResponse"
            - $ref: "#/components/schemas/KSAOBRequestToPayInitiationInstructionResponse"
        transactionType:
          $ref: "#/components/schemas/TransactionType"
        debtorAgentStatus:
          $ref: "#/components/schemas/DebtorAgentStatus"
        creditorAgentStatus:
          $ref: "#/components/schemas/CreditorAgentStatus"

      required:
        - id
        - status
        - creationDateTime
        - statusUpdateDateTime
      additionalProperties: false

    GenericGetPaymentResponse:
      type: object
      properties:
        id:
          type: string
        endToEndId:
          type: string
        rejectionReason:
          $ref: '#/components/schemas/RejectionReason'
        status:
          $ref: "#/components/schemas/PaymentStatusEnum"
        creationDateTime:
          type: string
          format: date-time
        statusUpdateDateTime:
          type: string
          format: date-time
        paymentTransactionId:
          type: string
        paymentStatusDetails:
          $ref: "#/components/schemas/PaymentStatusDetail"
        transactionId:
          type: string
          description: This is mandatory for KSA.
        charges:
          $ref: "#/components/schemas/Charges"
        instruction:
          type: object
          description: The current status of the payment. This is mandatory for KSA. The data will be passed without any validations.
          oneOf:
            - $ref: "#/components/schemas/KSAOBRefundInitiationInstructionResponse"
            - $ref: "#/components/schemas/KSAOBRequestToPayInitiationInstructionResponse"
        transactionType:
          $ref: '#/components/schemas/TransactionType'
        debtorAgentStatus:
          $ref: '#/components/schemas/DebtorAgentStatus'
        creditorAgentStatus:
          $ref: '#/components/schemas/CreditorAgentStatus'

      required:
        - id
        - status
        - creationDateTime
        - statusUpdateDateTime
      additionalProperties: false

    RefundAccount:
      type: object
      required:
        - schemeName
        - identification
      properties:
        schemeName:
          type: string
        identification:
          type: string
        name:
          type: string
        secondaryIdentification:
          type: string

    PaymentDetails:
      type: object
      properties:
        id:
          type: string
        status:
          $ref: "#/components/schemas/PaymentStatusEnum"
        statusUpdateDateTime:
          type: string
          format: date-time
        statusDetails:
          type: array
          items:
            $ref: "#/components/schemas/PaymentStatusDetails"
      required:
        - id
        - status
        - statusUpdateDateTime

    PaymentStatusDetails:
      type: object
      properties:
        localInstrument:
          type: string
        status:
          $ref: "#/components/schemas/PaymentStatusEnum"
        statusReason:
          type: string
        statusReasonDescription:
          type: string
      required:
        - status
      additionalProperties: false

    PaymentStatusEnum:
      type: string
      enum:
        - Pending
        - Rejected
        - AcceptedSettlementInProcess
        - AcceptedSettlementCompleted
        - AcceptedWithoutPosting
        - AcceptedCreditSettlementCompleted

    RejectionReason:
      type: object
      properties:
        code:
          type: string
          description: code that identifies the error
        detail:
          type: string
          description: message detail with information about the error

    PaymentDetailsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/PaymentDetails"
        meta:
          $ref: "#/components/schemas/Meta"

    PaymentStatusDetail:
      title: "PaymentStatusDetail"
      description: |
        This attribute SHOULD only be returned when the resource Status represents a failed state e.g. : Rejected. Only applicable for KSA
      type: "object"
      required:
        - "reason"
      properties:
        reason:
          type: "object"
          description: |
            A Placeholder for any responses that support a Status
          required:
            - "code"
          properties:
            code:
              type: string
              description: |
                The reason code that represents the downstream System Error.

                **Payments**

                |Status|Reason Code|Description|
                |----------|--|--|
                |Rejected|KSAOB.Originator.InsufficientFunds|The PASP Debtor Account does not have sufficient funds to complete the payment|
                |Rejected|KSAOB.Originator.AccountIssue|The Originator Account has an issue in sending the payment e.g. Account is inactive, locked, dormant|
                |Rejected|KSAOB.Receiver.AccountIssue|The Receiver Account has an issue in receiving the payment e.g. Account is inactive, locked, dormant|
                |Rejected|KSAOB.Originator.TransactionNotPermitted|The Originator Account is not permitted to perform the requested transaction|
                |Rejected|KSAOB.Originator.DuplicateTransaction|The requested transaction is a duplicate of a previous successfully processed transaction|
                |Rejected|KSAOB.Receiver.DuplicateTransaction|The requested transaction is a duplicate of a previous successfully processed transaction|
                |Rejected|KSAOB.Receiver.Timeout |A timeout has occurred on the payment rails|
                |Rejected|KSAOB.Receiver.SystemUnavailable|The payment rails or downstream system is unavailable|
                |Rejected|KSAOB.Originator.Other|Any other reason not specified and applicable to the Originator; details MUST be provided in the Detail field|
                |Rejected|KSAOB.Receiver.Other|Any other reason not specified and applicable to the Receiver; details MUST be provided in the Detail field|
                |Rejected|KSAOB.Originator.SuspectedFraud|The Originator Account has been suspended due to suspected fraud|
                |Rejected|KSAOB.Receiver.SuspectedFraud|The Receiver Account has been suspended due to suspected fraud|
              enum:
                - "KSAOB.Originator.InsufficientFunds"
                - "KSAOB.Originator.AccountIssue"
                - "KSAOB.Receiver.AccountIssue"
                - "KSAOB.Originator.TransactionNotPermitted"
                - "KSAOB.Originator.DuplicateTransaction"
                - "KSAOB.Receiver.DuplicateTransaction"
                - "KSAOB.Receiver.Timeout"
                - "KSAOB.Receiver.SystemUnavailable"
                - "KSAOB.Originator.Other"
                - "KSAOB.Receiver.Other"
                - "KSAOB.Originator.SuspectedFraud"
                - "KSAOB.Receiver.SuspectedFraud"
            detail:
              type: "string"
              description: "Further details that are specific to the Reason Code"
          additionalProperties: false
        message:
          $ref: "#/components/schemas/Message"
      additionalProperties: false

    Charges:
      title: "Charges"
      type: "array"
      description: |
            Applicable only for KSA
      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 Payer.
        required:
          - "Type"
          - "Amount"
        properties:
          Type:
            $ref: "#/components/schemas/ExternalPaymentChargeTypeCode"
          Amount:
            $ref: "#/components/schemas/ActiveCurrencyAmount"

    TransactionType:
      type: string
      minLength: 5
      maxLength: 6
      enum:
      - OFF-US
      - ON-US
      example: OFF-US

    DebtorAgentStatus:
      type: string
      minLength: 4
      maxLength: 4
      example: RJCT

    CreditorAgentStatus:
      type: string
      minLength: 4
      maxLength: 4
      example: ACCP

    KSAOBRequestToPayInitiationInstructionResponse:
      title: "KSAOBRequestToPayInitiationInstructionResponse"
      description: |
        (Array) of Single or Multiple Request To Pay Instructions

        * Please refer to the Business Rules, PIS Limits and Constants, Maximum RTPs per Message for the limit.
      type: "array"
      minItems: 1
      maxItems: 10
      items:
        allOf:
          - type: "object"
            required:
              - "RequestToPayStatus"
              - "RequestToPayStatusUpdateDateTime"
              - "CreationDateTime"
              - "Amount"
              - "RequestToPayPurposeCode"
              - "RequestToPayTransactionId"
              - "DebtorAccount"
            properties:
              RequestToPayTransactionId:
                $ref: "#/components/schemas/OBRequestToPayTransactionId"
              Amount:
                $ref: "#/components/schemas/OBActiveCurrencyAmount"
              RequestToPayStatus:
                $ref: "#/components/schemas/OBRequestToPayStatus"
              RequestToPayStatusUpdateDateTime:
                $ref: "#/components/schemas/OBStatusUpdateDateTime"
              RequestToPayStatusDetail:
                $ref: "#/components/schemas/OBRequestToPayStatusDetail"
              IsPendingCancellation:
                  $ref: "#/components/schemas/OBPendingCancellation"
              CreationDateTime:
                  $ref: "#/components/schemas/OBCreationDateTime"
              Charges:
                  $ref: "#/components/schemas/Charges"
              DebtorAgent:
                $ref: "#/components/schemas/OBCreditorAgent"
              DebtorAccount:
                  $ref: "#/components/schemas/OBDebtorAccount"
              RequestToPayPurposeCode:
                $ref: "#/components/schemas/OBPaymentPurposeCode"
              NoteToPayer:
                $ref: "#/components/schemas/OBRTPPayerNote"
              RequestToPayExpiryWindow:
                $ref: "#/components/schemas/OBRTPExpiryWindow"
            additionalProperties: false

    OBRTPExpiryWindow:
      title: "OBRTPExpiryWindow"
      type: "string"
      description: |
        Specifies the Requests to Pay Expiration Window.
        The time window is based on a custom time format hhh:mm:ss. e.g. 720:00:00 represents a time window of 720 hours, 00 minutes, 00 seconds (30 days).

        * Please refer to the Business Rules, PIS Limits and Constants, RTP Expiry Window for the limit.

      pattern: '^(00[0-9]|0[1-9][0-9]|[1-6][0-9]{2}|7[01][0-9]|720):[0-5][0-9]:[0-5][0-9]$'
      example: "48:00:00"
    OBRTPPayerNote:
      title: "OBRTPPayerNote"
      type: "string"
      description: |
        Notes for the Payer
      minLength: 1
      maxLength: 256

    OBDebtorAccount:
      title: "OBDebtorAccount"
      description: "Unambiguous identification of the account of the debtor to which a debit entry will be made."
      type: "object"
      required:
      - "IdentificationType"
      - "Identification"
      - "Name"
      properties:
        IdentificationType:
          $ref: "#/components/schemas/OBExternalAccountIdentificationCode"
        Identification:
          $ref: "#/components/schemas/OBIdentification"
        Name:
          $ref: "#/components/schemas/OBName"

    OBName:
      title: "OBName"
      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"
        ar:
          type: "string"
          description: "Arabic value of the string"
      additionalProperties: false
    OBIdentification:
      title: "OBIdentification"
      description: |
        Identification for the account assigned by the PASP based on the Account Scheme Name.
        This identification is known by the PSU account owner.
      type: "string"
      minLength: 1
    OBExternalAccountIdentificationCode:
      title: "OBExternalAccountIdentificationCode"
      description: "Name of the identification scheme, in a coded form as published in an external list."
      type: "string"
      enum:
        - "KSAOB.IBAN"
        - "KSAOB.AccountNumber"
        - "KSAOB.UnifiedCommercialNumber"
        - "KSAOB.Email"
        - "KSAOB.MobileNumber"
        - "KSAOB.NationalID"
        - "KSAOB.IqamaNumber"
    OBCreditorAgent:
      title: "OBCreditorAgent"
      description: |
         Refers to the Financial Institution.
      type: "object"
      required:
        - "IdentificationType"
        - "Identification"
      properties:
        IdentificationType:
          type: "string"
          description: |
            Refers to the Identification scheme for uniquely identifying the Agent.

            * KSAOB.OTHER: The ID; A Country Code followed by a Bank Code (KSAOB 4 character code). The full list of PASP names and 6 digits IDs are as follows:
          enum:
            - "KSAOB.OTHER"
        Identification:
          description: |
            The Agent is the Country Code followed by a Bank Code (KSAOB 4 character code). The full list of PASP names and 6 digits IDs are as follows"

            | PASP NAME|ID|
            |----------|--|
            |ALINMA BANK|SAINMA|
            |AL RAJHI BANK|SARJHI|
            |ARAB NATIONAL BANK|SAARNB|
            |BANK AL BILAD|SAALBI|
            |BANK AL-JAZIRA|SABJAZ|
            |BANK MUSCAT|SABMUS|
            |BANQUE SAUDI FRANSI|SABSFR|
            |BNP PARIBAS SAUDI ARABIA|SABNPA|
            |CREDIT SUISSE SAUDI ARABIA|SACRES|
            |DEUTSCHE BANK AG, RIYADH BRANCH|SADEUT|
            |EMIRATES NBD PJSC|SAEBIL|
            |FIRST ABU DHABI BANK|SAFABM|
            |GULF INTERNATIONAL BANK B.S.C., RIYADH|SAGULF|
            |INDUSTRIAL AND COMMERCIAL BANK OF CHINA RIYADH BRANCH, SA|SAICBK|
            |ISLAMIC DEVELOPMENT BANK|SAISLD|
            |J.P.MORGAN SAUDI ARABIA LIMITED|SAJPMG|
            |J.P MORGAN CHASE BANK, N.A RIYADH|SACHAS|
            |MERILL LYNCH KINGDOM OF SAUDIA ARABIA|SAMLSA|
            |NATIONAL BANK OF BAHRAIN|SANBOB|
            |NATIONAL BANK OF KUWAIT|SANBOK|
            |NATIONAL BANK OF PAKISTAN|SANBPA|
            |NEOLEAP|SANEOL|
            |RIYAD BANK|SARIBL|
            |SAUDI NATIONAL BANK|SANCBK|
            |SAUDI ARABIAN MONETARY AUTHORITY|SASAMA|
            |SAUDI BRITISH BANK|SASABB|
            |SAUDI INVESTMENT BANK|SASIBC|
            |STANDARD CHARTERED CAPITAL (SAUDI ARABIA)|SASCBL|
            |STC PAY|SASTCP|
            |STC Bank|SASTCJ|
            |T.C. ZIRAAT BANKASI A.S|SATCZB|
          type: "string"
          enum:
            - "SAINMA"
            - "SARJHI"
            - "SAALBI"
            - "SABJAZ"
            - "SABMUS"
            - "SABSFR"
            - "SABNPA"
            - "SACRES"
            - "SADEUT"
            - "SAEBIL"
            - "SAGULF"
            - "SAICBK"
            - "SAISLD"
            - "SAJPMG"
            - "SACHAS"
            - "SAMLSA"
            - "SANBOB"
            - "SANBOK"
            - "SANBPA"
            - "SANCBK"
            - "SARIBL"
            - "SASAMA"
            - "SASABB"
            - "SASIBC"
            - "SASCBL"
            - "SATCZB"
            - "SASTCP"
            - "SANEOL"
            - "SASTCJ"
            - "SAFABM"
          minLength: 6
          maxLength: 6
          example: SASAMA
    OBRequestToPayTransactionId:
      title: "OBRequestToPayTransactionId"
      type: "string"
      description: |
        The TransactionId associated with a payment generated from the Payment Rails.
      example: "oz2c8wpre1vy34tx7q"
    OBRequestToPayTypeResponse:
      type: "string"
      description: |
        The type of Request To Pay being instructed which must match against the Request To Pay Type(s) set under the Consent Schedule
      enum:
        - KSAOB.SingleRequestToPay
        - KSAOB.LongLivedRequestToPay

    OBPendingCancellation:
      type: boolean
      description: |
        This boolean flag is only set to True when:
        * The PISP initiates an RTP Cancellation with the PASP
        * The current RTP Status is: Pending
    OBRequestToPayStatus:
      title: "OBRequestToPayStatus"
      description: |
        Specifies the status of the Request To Pay information group
        * Initiated: The Request To Pay has been received by the Receiving PASP but not delivered to Payer.
        * Pending: The Request To Pay is pending a response from the Payer.
        * Cancelled: The Request To Pay Cancellation request has been accepted by the Receiving PASP.
        * Accepted: The Request To Pay has been accepted by the Payer.
        * Expired:  The Request to Pay has expired due to no action from the Payer.
        * Paid: The Payer has fulfilled and paid the Request To Pay.
        * Rejected: The Payer has rejected the Request To Pay.
        * Failed: The Request to Pay has failed (either from the Originating PASP or Receiving PASP).
        * NotSubmitted: The Sender cancels the Request To Pay before submitting it to the Payer.
      type: "string"
      enum:
        - "Initiated"
        - "Pending"
        - "Cancelled"
        - "Accepted"
        - "Expired"
        - "Paid"
        - "Rejected"
        - "Failed"
        - "NotSubmitted"
      example: Initiated
    KSAOBRefundInitiationInstructionResponse:
      title: "KSAOBRefundInitiationInstruction"
      description: |
        (Array) of Refund Instructions

        * Please refer to the Business Rules, PIS Limits and Constants, Maximum Refunds per Message for the limit.
      type: "array"
      minItems: 1
      maxItems: 500
      items:
        required:
          - "RefundStatus"
          - "RefundStatusUpdateDateTime"
          - "Type"
          - "CreationDateTime"
          - "OriginalPayment"
          - "Amount"
        properties:
          Amount:
            $ref: "#/components/schemas/OBActiveCurrencyAmount"
          OriginalPayment:
            $ref: "#/components/schemas/OBSingleRefundPayment"
          RefundPurposeCode:
            $ref: "#/components/schemas/OBPaymentPurposeCode"
          RefundStatus:
            $ref: "#/components/schemas/OBRefundStatus"
          RefundStatusUpdateDateTime:
            $ref: "#/components/schemas/OBStatusUpdateDateTime"
          RefundStatusDetail:
            $ref: "#/components/schemas/OBRefundStatusDetail"
          CreationDateTime:
              $ref: "#/components/schemas/OBCreationDateTime"
          Charges:
              $ref: "#/components/schemas/Charges"
        additionalProperties: false

    OBCreationDateTime:
      title: "OBCreationDateTime"
      description: "Date and time at which the message was created. 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:\n2023-04-05T10:43:07+00:00"
      type: "string"
      format: "date-time"

    OBStatusUpdateDateTime:
      title: "OBStatusUpdateDateTime"
      description: "Date and time at which the resource status was updated.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:\n2023-04-05T10:43:07+00:00"
      type: "string"
      format: "date-time"

    OBRefundStatusDetail:
      title: "OBRefundStatusDetail"
      description: |
        This attribute SHOULD only be returned when the resource Status represents a failed state e.g. : Rejected.
      type: "object"
      required:
        - "Reason"
      properties:
        Reason:
          type: "object"
          description: |
            A Placeholder for any responses that support a Status
          required:
            - "Code"
          properties:
            Code:
              type: string
              description: |
                The reason code that represents the downstream System Error.

                **Refunds**

                |Status|Reason Code|Description|
                |----------|--|--|
                |Rejected|KSAOB.Originator.InsufficientFunds|The PASP Debtor Account does not have sufficient funds to complete the refund|
                |Rejected|KSAOB.Originator.AccountIssue|The Originator Account has an issue in sending the refund e.g. Account is inactive, locked, dormant|
                |Rejected|KSAOB.Receiver.AccountIssue|The Receiver Account has an issue in receiving the refund e.g. Account is inactive, locked, dormant|
                |Rejected|KSAOB.Originator.TransactionNotPermitted|The Originator Account is not permitted to perform the requested transaction|
                |Rejected|KSAOB.Originator.DuplicateTransaction|The requested transaction is a duplicate of a previous successfully processed transaction|
                |Rejected|KSAOB.Receiver.DuplicateTransaction|The requested transaction is a duplicate of a previous successfully processed transaction|
                |Rejected|KSAOB.Receiver.Timeout |A timeout has occurred on the payment rails|
                |Rejected|KSAOB.Receiver.SystemUnavailable|The payment rails or downstream system is unavailable|
                |Rejected|KSAOB.Originator.Other|Any other reason not specified and applicable to the Originator; details MUST be provided in the Detail field|
                |Rejected|KSAOB.Receiver.Other|Any other reason not specified and applicable to the Receiver; details MUST be provided in the Detail field|
              enum:
                - "KSAOB.Originator.InsufficientFunds"
                - "KSAOB.Originator.AccountIssue"
                - "KSAOB.Receiver.AccountIssue"
                - "KSAOB.Originator.TransactionNotPermitted"
                - "KSAOB.Originator.DuplicateTransaction"
                - "KSAOB.Receiver.DuplicateTransaction"
                - "KSAOB.Receiver.Timeout"
                - "KSAOB.Receiver.SystemUnavailable"
                - "KSAOB.Originator.Other"
                - "KSAOB.Receiver.Other"
            Detail:
              type: "string"
              description: "Further details that are specific to the Reason Code"
          additionalProperties: false
        Message:
          $ref: "#/components/schemas/OBMessage"
      additionalProperties: false

    OBMessage:
      title: "OBMessage"
      description: "A description of the error that occurred. e.g., 'A mandatory field isn't supplied' or 'RequestedExecutionDateTime must be in future'\nKSAOB doesn't standardise this field"
      type: "object"
      required:
        - "en"
      properties:
        en:
          type: "string"
          description: "English value of the string"
          minLength: 1
          maxLength: 500
        ar:
          type: "string"
          description: "Arabic value of the string"
          minLength: 1
          maxLength: 500
      additionalProperties: false
    OBRequestToPayStatusDetail:
      title: "OBRequestToPayStatusDetail"
      description: |
        This attribute SHOULD only be returned when the resource Status represents a failed state e.g. : Rejected, Failed, Cancelled, Expired.
      type: "object"
      required:
        - "Reason"
      properties:
        Reason:
          type: "object"
          description: |
            A Placeholder for any responses that support a Status
          required:
            - "Code"
          properties:
            Code:
              type: string
              description: |
                The reason code that represents the downstream System Error.

                **Requests To Pay (RTP)**

                |Status|Reason Code|Description|
                |----------|--|--|
                |Failed|KSAOB.Originator.AccountIssue|The Originator Account has an issue in processing the RTP request e.g. Account is inactive, locked, dormant|
                |Failed|KSAOB.Receiver.AccountIssue|The Receiver Account has an issue in processing the RTP request e.g. Account is inactive, locked, dorman|
                |Rejected|KSAOB.Originator.DuplicateTransaction|The requested transaction is a duplicate of a previous successfully processed transaction|
                |Rejected|KSAOB.Receiver.DuplicateTransaction|The requested transaction is a duplicate of a previous successfully processed transaction|
                |Failed|KSAOB.Receiver.Timeout|A timeout has occurred on the payment rails|
                |Failed|KSAOB.Receiver.SystemUnavailable|The payment rails or downstream system is unavailable|
                |Failed|KSAOB.Originator.SystemUnavailable|The payment rails or downstream system is unavailable|
                |Failed, Cancelled|KSAOB.Originator.Other|Any other reason not specified and applicable to the Originator; details MUST be provided in the Detail field|
                |Rejected, Failed, Cancelled|KSAOB.Receiver.Other|Any other reason not specified and applicable to the Receiver; details MUST be provided in the Detail field|
                |Cancelled|KSAOB.Receiver.CancellationAccepted|The cancellation request has been accepted by the Receiver|
                |Expired|KSAOB.Originator.Expired|The Originator requested window for an RTP response has expired|
                |Failed|KSAOB.Originator.CancelledBeforeSubmission|The Originator PASP has not submitted the RTP request to the Receiver PASP due to invalid information|
              enum:
                - "KSAOB.Originator.AccountIssue"
                - "KSAOB.Receiver.AccountIssue"
                - "KSAOB.Originator.DuplicateTransaction"
                - "KSAOB.Receiver.DuplicateTransaction"
                - "KSAOB.Receiver.Timeout"
                - "KSAOB.Receiver.SystemUnavailable"
                - "KSAOB.Originator.SystemUnavailable"
                - "KSAOB.Originator.Other"
                - "KSAOB.Receiver.Other"
                - "KSAOB.Receiver.CancellationAccepted"
                - "KSAOB.Originator.Expired"
                - "KSAOB.Originator.CancelledBeforeSubmission"
            Detail:
              type: "string"
              description: "Further details that are specific to the Reason Code"
          additionalProperties: false
        Message:
          $ref: "#/components/schemas/OBMessage"
      additionalProperties: false

    OBRefundStatus:
      title: "OBRefundStatus"
      description: |
        Specifies the status of the Refund information group
        * Pending: Refund initiation or individual transaction included in the Refund initiation is pending. Further checks and status update will be performed.
        * Rejected: The Refund initiation has been rejected
        * AcceptedSettlementCompleted: Settlement of the Debtors account has been completed
        * AcceptedCreditSettlementCompleted: When the Payee account has been credited with the funds of the Refund initiated via the PISP
        * AcceptedWithoutPosting:  When the Recipient Bank has accepted the Refund but has not applied the credit to the Payee account yet.
      type: "string"
      enum:
        - "Pending"
        - "AcceptedSettlementCompleted"
        - "AcceptedCreditSettlementCompleted"
        - "AcceptedWithoutPosting"
        - "Rejected"
      example: Pending
    OBPaymentPurposeCode:
      title: "OBPaymentPurposeCode:"
      description: |
        A Category code, related to the type of services or goods that corresponds to the underlying purpose of the Payment, Refund, RTP.
        The Purpose Codes can be based on either:
        * The SARIE IPS Message Implementation Guide - Section 21.4 - Category Purpose Codes
        * The ISO20022 External code sets
      type: "string"
      minLength: 1
      maxLength: 4
      pattern: "^[A-Z]{3,4}$"
    OBSingleRefundPayment:
      title: "OBSingleRefundPayment"
      type: "object"
      description: |
        Placeholder for single payment Refund Data.
      required:
        - "Amount"
        - "Date"
        - "PaymentTransactionId"
      properties:
        Amount:
          $ref: "#/components/schemas/ActiveCurrencyAmount"
        Date:
          description: |
            Date of the Original Payment
          type: "string"
          format: "date"
        PaymentTransactionId:
          $ref: "#/components/schemas/OBPaymentTransactionId"
      additionalProperties: false
    OBPaymentTransactionId:
      title: "OBPaymentTransactionId"
      type: "string"
      description: |
        This is an end to end TransactionId that is associated with a payment when it is sent from an Originating PASP to a Receiving PASP.
        This identifier is also used for Refunds.

        This applies to:
        * Same Bank Transfer (Within the same bank)
        * Local Bank Transfer (Between 2 banks)

        **IPS**
        Transaction Identification field (2.4) as defined in the Payment Identification block (2.1) of the Credit Transfer pacs.008 message
        (e.g) 20201122SAABCD00002BXXX20730997766

        **ON-US**
        MUST prefix with a 6 digit bank codes (as per the OBCreditorAgent schema):
        SA + 4 char code. (e.g. SASAMA)
      minimum: 1
      maximum: 35
    ExternalPaymentChargeTypeCode:
      title: "OBExternalPaymentChargeTypeCode"
      description: "Charge type, in a coded form."
      type: "string"
      enum:
        - "VAT"
        - "Fees"

    OBActiveCurrencyAmount:
      title: "ActiveCurrencyAmount"
      description: |
        The Currency and Amount relating to the Payment, Refund or Request to Pay
      type: "object"
      required:
        - "Amount"
        - "Currency"
      properties:
        Amount:
          $ref: "#/components/schemas/ActiveOrHistoricAmount"
        Currency:
          $ref: "#/components/schemas/ActiveOrHistoricCurrencyCode"

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

    ActiveOrHistoricAmount:
      title: "ActiveOrHistoricAmount"
      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"

    ActiveOrHistoricCurrencyCode:
      title: "ActiveOrHistoricCurrencyCode"
      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: "SAR"


    Message:
      title: "Message"
      description: "A description of the error that occurred. e.g., 'A mandatory field isn't supplied' or 'RequestedExecutionDateTime must be in future'\nKSAOB doesn't standardise this field"
      type: "object"
      required:
        - "en"
      properties:
        en:
          type: "string"
          description: "English value of the string"
          minLength: 1
          maxLength: 500
        ar:
          type: "string"
          description: "Arabic value of the string"
          minLength: 1
          maxLength: 500
      additionalProperties: false

    #
    # 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

  parameters:
    aspspId:
      name: o3-aspsp-id
      in: header
      schema:
        type: string
      required: true
      description: Identifier for the LFI that the request is targetted to

    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.

    pageNumber:
      name: page
      in: query
      schema:
        type: string
      required: false
      description: Page number to be returned

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