openapi: 3.0.1
info:
  title: TMF654 - Prepay Balance Management
  description: |-
    The DCB (Direct Carrier Billing) API enables consumers to change their balance allowing both debit (onetime debit and recurring debit) operations. Every bucket will measure balance in different units, it can be monetary or non-monetary (e.g.: number of sms that are available, number of GB of data available).
  version: 1.0.0

servers:
  - url: https://api.ooredoo.com
    description: Ooredoo API gateway

paths:
  /tmf-api/oauth/v4/token:
    post:
      summary: Generate Access Token
      description: Token generation endpoint (client_id & client_secret in headers, grant_type & scope in body)
      parameters:
        - name: client_id
          in: header
          required: true
          description: Client ID of onboarded client.
          schema:
            type: string
            format: password
            default: 67Q4itU3ivApTHRB4dJKFh4R5UAdG5RAsMeEq2NppNgd6LBH
        - name: client_secret
          in: header
          required: true
          description: Client secret of onboarded client.
          schema:
            type: string
            format: password
            default: yp1CUQyGwEMNruGXtnhIbpTOuK6BGlxAFmiGlG2FQea3cHgaVqRw7rybKnWAUeKB
        - name: scope
          in: header
          required: true
          description: OAuth scope
          schema:
            type: string
            default: urn:mdv:prepaybalancemanagement:createadjustbalance:onetimecredit
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  default: client_credentials
                  description: OAuth grant type
              required:
                - grant_type
      responses:
        '200':
          description: Successful token response
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                  expires_in:
                    type: integer
                  consented_on:
                    type: string
                  created_At:
                    type: string
                  expired_At:
                    type: string
        "401":
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'

  /tmf-api/prepayBalanceManagement/v4/adjustBalance:
    post:
      summary: Creates an AdjustBalance
      description: This operation creates an AdjustBalance entity.
      operationId: createAdjustBalance
      parameters:
        - name: transactionId
          in: header
          required: true
          schema:
            type: string
            maxLength: 30
            minLength: 20
            pattern: "^[A-Za-z0-9]+$"
            default: rSJVa4Zzxke0b5AKvz4EsjG6onG01
        - name: countryCode
          in: header
          required: true
          schema:
            type: string
            maxLength: 3
            minLength: 2
            pattern: "^[A-Z]{2,3}$"
            default: MDV
      requestBody:
        description: The AdjustBalance to be created
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/AdjustBalance_Create'
        required: true
      responses:
        "201":
          description: Created
          headers:
            transactionId:
              description: Transaction Id
              schema:
                type: string
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/AdjustBalance'
        "400":
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "403":
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "405":
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "409":
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "500":
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "422":
          description: Business Rule Exception
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []

  /tmf-api/prepayBalanceManagement/v4/adjustBalance/{debitId}:
    get:
      summary: Retrieves a AdjustBalance by ID DEBIT
      description: This operation retrieves a AdjustBalance entity.
      operationId: retrieveAdjustBalanceDebit
      parameters:
        - name: debitId
          in: path
          required: true
          schema:
            type: string
            default: 346551
        - name: adjustType
          in: query
          required: true
          schema:
            type: string
            default: DEBIT
        - name: msisdn
          in: query
          required: true
          schema:
            type: string
            default: 9612198
        - name: transactionId
          in: header
          required: true
          schema:
            type: string
            default: 44654121231231233123
        - name: countryCode
          in: header
          required: true
          schema:
            type: string
            default: MDV
      responses:
        "200":
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/AdjustBalance'
        "400":
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "403":
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "405":
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "409":
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "500":
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []

  /tmf-api/prepayBalanceManagement/v4/adjustBalance/{creditId}:
    get:
      summary: Retrieves a AdjustBalance by ID CREDIT
      description: This operation retrieves a AdjustBalance entity.
      operationId: retrieveAdjustBalanceCredit
      parameters:
        - name: creditId
          in: path
          required: true
          schema:
            type: string
            default: 346551
        - name: adjustType
          in: query
          required: true
          schema:
            type: string
            default: REFUND
        - name: msisdn
          in: query
          required: true
          schema:
            type: string
            default: 9612198
        - name: transactionId
          in: header
          required: true
          schema:
            type: string
            default: 44654123123123123123
        - name: countryCode
          in: header
          required: true
          schema:
            type: string
            default: MDV
      responses:
        "200":
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/AdjustBalance'
        "400":
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "403":
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
        "404":
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "405":
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "409":
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        "500":
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []   # ✅ fixed

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ActionStatusType:
      type: string
      description: Valid values for the Action Status Type
      example: created
      enum:
        - created
        - failed
        - cancelled
        - completed

    AdjustBalance:
      type: object
      properties:
        id:
          type: string
          description: Unique Identifier for the resource
        href:
          type: string
          description: A reference to the resource
        status:
          $ref: '#/components/schemas/ActionStatusType'
        amount:
          $ref: '#/components/schemas/Quantity'
        bucket:
          $ref: '#/components/schemas/BucketRef'
        usageType:
          $ref: '#/components/schemas/UsageType'
      description: "The AdjustBalance resource allows adjustments to be made to the original BalanceTopup."

    AdjustBalance_Create:
      required:
        - amount
        - bucket
        - logicalResource
        - usageType
      type: object
      properties:
        creditTransactionId:
          type: string
          description: Id generated from debit flow
          default: "007e25486a5341ba93a7dfd97a8959fc47302"
        channel:
          type: string
          description: Partner Channel
          default: Karti
        description:
          type: string
          description: description for refund
          default: Refund for Subscription
        amount:
          $ref: '#/components/schemas/Quantity'
        product:
          type: string
          description: Product details
          default: [{"id":"Shop2game","name":"DCB Subscription","@type":"DCB Subscription"}]
        bucket:
          $ref: '#/components/schemas/BucketRef'
        usageType:
          $ref: '#/components/schemas/UsageType'
        logicalResource:
          $ref: '#/components/schemas/LogicalResourceRef'
      description: "The AdjustBalance resource allows adjustments to be made to the original BalanceTopup."

    BucketRef:
      required:
        - id
      type: object
      properties:
        id:
          type: string
          description: unique identifier
          default: 9612104
      description: link to the resource that holds bucket information

    LogicalResourceRef:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: MSISDN
            default: 9612104
          "@type":
            type: string
            description: Free text
            default: SUBSCRIBER_NUMBER

    Quantity:
      required:
        - amount
        - units
      type: object
      properties:
        amount:
          type: number
          description: Numeric value in a given unit.
          format: float
          default: 1
        units:
          type: string
          description: "units of currency."
          enum:
            - MVR
            - OMR
            - TND
            - DZD
            - FILS
            - ILS
            - QAR
            - IQD
      description: Indicate the amount on the bucket

    UsageType:
      type: string
      description: Denotes the usage of amount
      default: monetary
      enum:
        - monetary
        - voice
        - data
        - sms
        - other

    Error:
      required:
        - code
        - reason
      type: object
      properties:
        code:
          type: string
          description: Application relevant detail, defined in the API or a common list.
        reason:
          type: string
          description: Explanation of the reason for the error which can be shown to a client user.
        message:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client user.
        status:
          type: string
          description: HTTP Error code extension
        referenceError:
          type: string
          description: URI of documentation describing the error.
          format: uri
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class.
        '@schemaLocation':
          type: string
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
          format: uri
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name.
      description: "Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)"

  parameters:
    transactionIdparam:
      name: transactionId
      in: header
      description: Unique identifier should be alphanumeric value and should have 20-30 characters. No special characters allowed.
      required: true
      schema:
        maxLength: 30
        minLength: 20
        pattern: "^[A-Za-z0-9]+$"
        type: string
    countryCodeParam:
      name: countryCode
      in: header
      description: ISO country code (e.g., DZD).
      required: true
      schema:
        maxLength: 3
        minLength: 2
        pattern: "^[A-Z]{2,3}$"
        type: string

x-original-swagger-version: "2.0"