openapi: 3.0.1
info:
  title: DCB Recurring
  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/generateToken:
    post:
      summary: Generate Access Token
      description: Token generation endpoint (client_id, client_secret, scope in headers; msisdn, charge, grant_type in body)
      parameters:
        - name: client_id
          in: header
          required: true
          description: Client ID of onboarded client.
          schema:
            type: string
          example: 67Q4itU3ivApTHRB4dJKFh4R5UAdG5RAsMeEq2NppNgd6LBH
        - name: client_secret
          in: header
          required: true
          description: Client secret of onboarded client.
          schema:
            type: string
          example: yp1CUQyGwEMNruGXtnhIbpTOuK6BGlxAFmiGlG2FQea3cHgaVqRw7rybKnWAUeKB
        - name: scope
          in: header
          required: true
          description: OAuth scope
          schema:
            type: string
            default: urn:mdv:prepaybalancemanagement:createadjustbalance:onetimedebit
        - name: transactionId
          in: header
          required: true
          description: Transaction ID
          schema:
            type: string
            default: zxq9pgoJRXVg5snSocpZ9iT9rxpp
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  default: client_credentials
                  description: OAuth grant type
                msisdn:
                  type: string
                  description: Subscriber MSISDN
                  default: 9612198
                charge:
                  type: number
                  description: Charge amount for the transaction
                  default: 1
              required:
                - msisdn
                - charge
                - 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
                  createdAt:
                    type: string
                  expiredAt:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /tmf-api/prepayBalanceManagement/v4/adjustBalance:
    post:
      summary: Create an AdjustBalance Recurring
      description: This operation creates an AdjustBalance entity.
      operationId: createAdjustBalanceRecurring
      parameters:
        - name: transactionId
          in: header
          description: |
            Unique identifier of the request message.
            Must be alphanumeric, 20–30 characters, no special symbols.
          required: true
          schema:
            maxLength: 30
            minLength: 20
            pattern: ^[A-Za-z0-9]+$
            type: string
          example: cxq9pgoJRXVg5snSocpZ9iT9rxbb
        - name: countryCode
          in: header
          description: ISO country code (e.g., MDV).
          required: true
          schema:
            maxLength: 3
            minLength: 2
            pattern: ^[A-Z]{2,3}$
            type: string
          example: MDV
      requestBody:
        description: The AdjustBalance to be created
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AdjustBalance_CreateRecurring"
        required: true
      responses:
        '201':
          description: Created
          headers:
            transactionId:
              description: Transaction Id
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdjustBalance"
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '405':
          description: Method Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '422':
          description: Business Rule Exception
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-codegen-request-body-name: adjustBalance
      security:
        - BearerAuth: []

components:
  schemas:
    ActionStatusType:
      type: string
      description: Valid values for the Action Status Type
      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_CreateRecurring:
      required: [amount, bucket, usageType]
      type: object
      properties:
        channel:
          type: string
          description: Valid values for the channel name
          example: karti
        OTP:
          type: string
          description: Valid OTP
          example: 123456
        description:
          type: string
          description: Description of the recharge operation value
          example: Charges for Subscription
        amount:
          $ref: "#/components/schemas/Quantity"
        bucket:
          $ref: "#/components/schemas/BucketRef"
        usageType:
          $ref: "#/components/schemas/UsageType"
        partyAccount:
          $ref: "#/components/schemas/PartyAccountRef"
        product:
          type: array
          items:
            $ref: "#/components/schemas/ProductRef"
    BucketRef:
      required: [id, name]
      type: object
      properties:
        id:
          type: string
          description: Unique identifier
          example: 1343241
        name:
          type: string
          description: Name of the related entity.
          example: New Subscription
    PartyAccountRef:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the party account
          example: Meena
        name:
          type: string
          description: Name of the party account
          example: TV
        partyDetails:
          type: string
          description: Details of the party account
          example: TV subscription
    ProductRef:
      required: [id]
      type: object
      properties:
        id:
          type: string
          description: Unique identifier
          example: SPORTS_WORLD_MONTHLY
        name:
          type: string
          description: Unique identifier
          example: SPORTS_WORLD_MONTHLY
        "@type":
          type: string
          description: Type identifier
          example: SPORTS_WORLD_MONTHLY
    Quantity:
      required: [amount, units]
      type: object
      properties:
        amount:
          type: number
          format: float
          description: Numeric value in a given unit.
          example: 1
        units:
          type: string
          description: Units of currency.
          enum: [DZD, OMR, TND, MVR, FILS, ILS, QAR, IQD]
          example: MVR
    UsageType:
      type: string
      description: Denotes the usage of amount
      enum: [monetary, voice, data, sms, other]
      example: monetary
    Error:
      required: [code, reason]
      type: object
      properties:
        code:
          type: string
          description: Application relevant detail
        reason:
          type: string
          description: Explanation of the reason for the error
        message:
          type: string
          description: More details and corrective actions
        status:
          type: string
          description: HTTP Error code extension
        referenceError:
          type: string
          format: uri
          description: URI of documentation describing the error
        "@baseType":
          type: string
        "@schemaLocation":
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        "@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)

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