openapi: 3.0.3
info:
  description: |
    This API allows API consumers to add loyalty points/rewards to
    their customers who are also Omantel customers. 

    # Introduction

    This API lets API Consumers pay a credit directly onto the end user’s
    bill (must be Omantel customer). Loyalty schemes can use it to reward 
    end users for making purchases with affiliated brands; retailers and 
    restaurants are among early adopters of this technology. This exciting
    new product can also help resolve end user service issues. When things 
    go wrong, brands might want to make a goodwill gesture to end users in 
    the form of a payment. Credit to Bill allows any end user with a mobile 
    phone to receive a credit in a fast, safe and trusted way.. 

    # API Functionality

    This API allows to clients to reward Omantel mobile customers,
    as well as to check eligibility.

    The API provides several endpoints/operations:
    - An endpoint to initiate the reward transaction.
    - A set of endpoints to retrieve reward details, history of rewards.
    - An endpoint to check customer's eligibility for reward.
    
  version: 1.0.0
  title: Loyalty Points/Rewards management Service
servers:
  - url: https://apigw.omantel.om
    variables:
      apiRoot:
        default: http://apigw.omantel.om
        description: API root
      basePath:
        default: /makasib/v1
        description: Base path for the Makasib API
tags:
  - name: Rewards
    description: Operations to manage rewarding procedure
  - name: Rewards Inquiry
    description: Operations to query rewards
paths:
  /makasib/v1/reward-points:
    post:
      security:
        - oAuth2ClientCredentials: []
      tags:
        - Rewards
      summary: Add Reward/Loyalty points to Omantel Customer's Account 
      operationId: addRewardPoints
      description: Add specified rewards/Loyalty points to the account of the Omantel customer.
      requestBody:
        description: Reward points adding transaction
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateReward"
            examples:
              Reward1000Points:
                summary: Add 1000 Reward Points to Customer's account
                value:
                  rewardTransaction:
                    clientCorrelatorId: "ODP1234567890"
                    referenceCode: "202401437492456"
                    mobileNumber: "92xxxxxx"
                    rewardInformation:
                      rewardPoints: 1000
                      description: "1000 points for order#202401437492456"
                      characteristicList:
                        - name: "PROMOTION_TYPE"
                          value: "REASON FOR ADDING POINTS"
                        - name: "OrderNumber"
                          value: "202401437492456"
                    rewardMetaData:
                      merchantName: "Oman Data Park"
                      merchantIdentifier: "OmanDataPark"
                      channel: "MobileApp"
      callbacks:
        eventNotifications:
          "{$request.body#/webhook.notificationUrl}/eventNotifications":
            $ref: "#/paths/~1eventNotifications"
      responses:
        201:
          description: <b>Created</b>
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RewardCreated"
        400:
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic400:
                  summary: Schema validation failed
                  value:
                    code: INVALID_ARGUMENT
                    status: 400
                    message: "Schema validation failed at  ..."
                WrongCurrency:
                  summary: Currency is unknown or not authorized
                  value:
                    code: INVALID_ARGUMENT
                    status: 400
                    message: "Currency is unknown or not authorized: currency"
                DuplicateClientCorrelator:
                  summary: clientCorrelator still exist
                  value:
                    code: INVALID_ARGUMENT
                    status: 400
                    message: "clientCorrelator already exist on server"
        401:
          $ref: "#/components/responses/Generic401"
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic403:
                  summary: Forbidden
                  value:
                    status: 403
                    code: PERMISSION_DENIED
                    message: "Operation not allowed: ..."
                mobileNumberRequired:
                  summary: Phone Number not provided and cannot be obtained from Authorization context
                  value:
                    status: 403
                    code: CARRIER_BILLING.PHONE_NUMBER_REQUIRED
                    message: "Phone Number is required"
                mobileNumberMismatch:
                  summary: Phone Number provided not matching Authorization context
                  value:
                    status: 403
                    code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT
                    message: "Phone Number does not match with Authorization context"
                UnauthorizedAmount:
                  summary: Unauthorized rewardPoints requested
                  value:
                    status: 403
                    code: CARRIER_BILLING.UNAUTHORIZED_AMOUNT
                    message: "Unauthorized rewardPoints requested"
                UserMobileAccumulatedThresholdAmountOverpassed:
                  summary: Accumulated threshold rewardPoints for the user's mobile account overpassed
                  value:
                    status: 403
                    code: CARRIER_BILLING.USER_AMOUNT_THRESHOLD_OVERPASSED
                    message: "Unathorized payment request. Accumulated user mobile payments overpass account rewardPoints threshold"
        409:
          $ref: "#/components/responses/Generic409"
        500:
          $ref: "#/components/responses/Generic500"
        503:
          $ref: "#/components/responses/Generic503"
        504:
          $ref: "#/components/responses/Generic504"
    get:
      security:
        - oAuth2ClientCredentials: []
      tags:
        - Rewards Inquiry
      summary: Get a list of rewards posted to this service 
      operationId: retrieveRewards
      description: Retrieve a list of rewards posted and their details based on some filtering criteria.
      parameters:      
        - $ref: "#/components/parameters/clientCorrelatorId"
        - $ref: "#/components/parameters/fromDate"
        - $ref: "#/components/parameters/toDate"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
        - $ref: "#/components/parameters/Seek"
      responses:
        200:
          description: OK
          headers:
            Content-Last-Key:
              $ref: "#/components/headers/Content-Last-Key"
            X-Total-Count:
              $ref: "#/components/headers/X-Total-Count"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RewardArray"
        400:
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                OutOfRange:
                  summary: Request out of range
                  value:
                    status: 400
                    code: OUT_OF_RANGE
                    message: "Client specified an invalid range"
        401:
          $ref: "#/components/responses/Generic401"
        403:
          $ref: "#/components/responses/Generic403"
        500:
          $ref: "#/components/responses/Generic500"
        503:
          $ref: "#/components/responses/Generic503"
        504:
          $ref: "#/components/responses/Generic504"
  /makasib/v1/reward-points/{rewardId}:
    get:
      security:
        - oAuth2ClientCredentials: []
      tags:
        - Rewards Inquiry
      summary: Get reward details for the specified reward ID
      operationId: retrieveRewardDetail
      description: Retrieve reward details for the specified reward ID.
      parameters:
        - name: rewardId
          in: path
          description: Reward identifier that was obtained from the reward request (Omantel generated `rewardId`)
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Reward"
        401:
          $ref: "#/components/responses/Generic401"
        403:
          $ref: "#/components/responses/Generic403"
        404:
          $ref: "#/components/responses/Generic404"
        500:
          $ref: "#/components/responses/Generic500"
        503:
          $ref: "#/components/responses/Generic503"
        504:
          $ref: "#/components/responses/Generic504"
  /eventNotifications:
    post:
      tags:
        - Reward Notifications
      summary: Reward notifications
      operationId: rewardNotification
      description: |
        Important: this endpoint is to be exposed by the API client, accepting requests in the defined format.
        The Omantel will call this endpoint whenever any reward related event occurs.
      requestBody:
        description: Creates a new carrier reward notification
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EventNotification"
        required: true
      responses:
        "204":
          description: Successful notification
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
        "504":
          $ref: "#/components/responses/Generic504"
components:
  schemas:
    Characteristic:
      type: object
      description: Describes a given characteristic of an object or entity through a name/value pair.
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: Name of the characteristic
        valueType:
          type: string
          description: Data type of the value of the characteristic
        value:
          type: string
          description: Data type of the value of the characteristic
    CreateReward:
      type: object
      required:
        - rewardTransaction
      properties:
        rewardTransaction:
          $ref: "#/components/schemas/RewardTransaction"
        webhook:
          $ref: "#/components/schemas/Webhook"
    RewardCreated:
      type: object
      required:
        - rewardId
        - transactionOperationStatus
      properties:
        rewardId:
          type: string
          description: |
            Unique Identifier of the reward created in Omantel Loyalti Management System. It
            can be used to query status of the transaction 
        transactionOperationStatus:
          $ref: '#/components/schemas/TransactionOperationStatus'
        rewardCreationDate:
          type: string
          format: date-time
          description: Date time, in ISO-8601 extended local date format, when the reward is created in server database. This is a technical information. Time-offset from UTC may be used to match local OB time.
        rewardDate:
          type: string
          format: date-time
          description: Date time, in ISO-8601 extended local date format, when the reward is effectively performed. This is a business information. Time-offset from UTC may be used to match local OB time.
        webhook:
          $ref: "#/components/schemas/Webhook"
    Reward:
      type: object
      required:
        - rewardTransaction
        - rewardId
      properties:
        rewardId:
          type: string
          description: |
            Unique Identifier of the reward transaction. It can be used
            to get details of the transaction using 
            `GET/reward-points/{rewardId}` API.
        transactionOperationStatus:
          $ref: '#/components/schemas/TransactionOperationStatus'
        rewardTransaction:
          $ref: "#/components/schemas/RewardTransaction"
        rewardCreationDate:
          type: string
          format: date-time
          description: Date time, in ISO-8601 extended local date format, when the payment is created in server database. This is a technical information. Time-offset from UTC may be used to match local OB time.
        rewardDate:
          type: string
          format: date-time
          description: Date time, in ISO-8601 extended local date format, when the payment is effectively performed. This is a business information. Time-offset from UTC may be used to match local OB time.
        webhook:
          $ref: "#/components/schemas/Webhook"
    Webhook:
      type: object
      required:
        - notificationUrl
      properties:
        notificationUrl:
          type: string
          description: Callback URL to allow asynchronous delivery of payment related events
        notificationAuthToken:
          type: string
          example: "c8974e592c2fa383d4a3960714"
          description: Authentification token for callback endpoint
    RewardTransaction:
      type: object
      required:
        - clientCorrelatorId
        - mobileNumber
      properties:
        clientCorrelatorId:
          type: string
          description: |
            Uniquely identifies this transaction request. If there is
            a communication failure during the request processing, 
            using the same `clientCorrelatorId` when retrying the request 
            allows Omantel to avoid executing the transaction twice. 
            This field SHOULD be present to avoid duplicate points addition.
        referenceCode:
          type: string
          description:
            Merchant generated reward reference to uniquely identify the
            request, for instance, in the case of disputes.           
        mobileNumber:
          type: string
          description: | 
            Phone number of the customer. It must be an active Omantel mobile number.  
          example: "92xxxxxx"
        rewardInformation:
          $ref: "#/components/schemas/RewardInformation"
        rewardMetaData:
          $ref: "#/components/schemas/RewardMetaData"
    RewardInfo:
      type: object
      required:
        - rewardInformation
      properties:
        rewardInformation:
          $ref: "#/components/schemas/RewardInformation"
        rewardMetaData:
          $ref: "#/components/schemas/RewardMetaData"
    mobileNumber:
      type: object
      properties:
        mobileNumber:
          type: string
          description: Identifies the mobile account to be rewardd. Phone number in E.164 format (starting with country code). Optionally prefixed with '+'.
    RewardItem:
      type: object
      required:
        - rewardPoints
        - currency
        - description
      properties:
        rewardPoints:
          type: integer
          format: int32          
          description: Specific reward points to be charged or reserved referred to a specific item.
        description:
          type: string
          description: Description text to be used for information and billing text referred to a specific item.
    RewardInformation:
      type: object
      required:
        - rewardPoints
      properties:
        rewardPoints:
          type: number
          format: float
          description: Amount to be rewardd.
        description:
          type: string
          description: Description text to be used for information and billing text
        characteristicList:
          type: array
          description: This is a list of Characteristics for extra info, if any.
          items:
            $ref: '#/components/schemas/Characteristic'
    RewardMetaData:
      type: object
      properties:
        merchantName:
          type: string
          description: Indicates the merchant name. Allows aggregators/partners to specify the actual merchant name
        merchantIdentifier:
          type: string
          description: Indicates the merchant identifier. Allows aggregators/partners to specify the actual merchant identifier
        channel:
          type: string
          description: The channel over which the requester is interacting with the merchant (e.g. WAP, Web, SMS...)
        serviceId:
          type: string
          description: The identifier of the partner/merchant service being purchased
        productId:
          type: string
          description: The product identifier to be combined with the `serviceId` to uniquely identify the product being purchased. For example if the `serviceId` relates to a VOD service, the `productId` can specify the movie rented
        characteristicList:
          type: array
          description: This is a list of Characteristics for extra info, if any.
          items:
            $ref: '#/components/schemas/Characteristic'
    TransactionOperationStatus:
      type: string
      description: Specifies status of the transaction.
      enum:
        - processing  # The request has been accepted and is under process.
        - pending     # The transaction has been initiated but not yet processed.
        - success     # The transaction was successfully completed.
        - failed      # The transaction has failed due to an error or rejection.
        - cancelled   # The transaction was cancelled by the user or system before completion.
        - invalid     # The transaction is invalid, possibly due to incorrect data or validation failure.
        - expired     # The transaction was not completed in the required time and has expired.
        - declined    # The transaction was declined, possibly due to policy restrictions or insufficient funds.
        - reversed    # The transaction was reversed after being processed.

    ErrorInfo:
      type: object
      required:
        - code
        - message
        - status
      properties:
        code:
          type: string
          description: Code given to this error
        status:
          type: string
          description: HTTP response status code
        message:
          type: string
          description: Detailed error description
    EventNotification:
      type: object
      description: Generic data type for event notification structure
      required:
        - event
      properties:
        eventSubscriptionid:
          type: string
          description: subscription identifier
        event:
          $ref: "#/components/schemas/Event"
    Event:
      type: object
      description: Generic data type for event structure
      required:
        - eventType
        - eventTime
        - eventDetail
      properties:
        eventid:
          type: string
          format: uuid
          description: Identifier of the event from the server where the event was reported
        eventType:
          type: string
          description: |
            Type of event. Different types considered so far:
            - `PAYMENT_COMPLETED`: Notification indication about payment completion.
            - `PAYMENT_FAILED`: Notification about payment failure.
        eventTime:
          type: string
          format: date-time
          description: Date time, in ISO-8601 extended local date format, when the event occurred. Time-offset from UTC may be used to match local OB time.
        eventDetail:
          $ref: "#/components/schemas/EventDetail"
    EventDetail:
      type: object
      description: Data type to provide event detail information
      properties:
        rewardId:
          type: string
          description: Unique Identifier of the payment
        clientCorrelatorId:
          type: string
          description: Client generated Unique Identifier of the payment
        status:
          type: string
          enum:
            - succeeded
            - failed
          description: |
            Status of the procedure, according to `eventType` param. Possible status are:
            * `succeeded`: procedure was accomplished 
            * `failed`: procedure failed.
        description:
          type: string
          description: Description of the notification, both used when process was `succeeded` or `failed` indicating in the latter case human understable reason about why process failed.
        paymentDate:
          type: string
          description: Date when the payment is effectively performed, both in 1-step and 2-step scenarios. This is a business information.
          format: date-time
      required:
        - rewardId
        - status
        - description
    RewardArray:
      description: A list of payment(s)
      type: array
      minItems: 0
      items:
        $ref: "#/components/schemas/Reward"
    Customer:
      type: object
      description: Customer details of the specified input
      properties:
        customerName:
          type: string
          description: Customer Name
        customerStatus:
          type: string
          description: |
            Current status of the contract. 
            It could be any one of the following:ACTIVE, PENDING, NEW.
          example: ACTIVE
        customerType:
          type: number
          description: Customer type. Possible values are 9 - GSM POSTPAID, 11 - GSM FAX, 12 - GSM DATA, 14 - GSM PREPAID,  200/203 – PSTN
        customerAccountNumber:
          type: string
          description: Customer Account Number can be used to pay bils
        acctCategory:
          type: string
          description: Account category of the contract. Example - Business – Large, Business – Medium, Business – Small, Government, Residential, Service, Special Services, Roaming Test Cards, Residential Staff, Test Numbers, Network Support
        collectionIndicator:
          type: string
          description: Indicate whether the contract is in collections or not. ACCOUNT IN COLLECTIONS, ACCOUNT NOT IN COLLECTIONS
        custAddr1:
          type: string
          description: Customer address 1
        custAddr2:
          type: string
          description: Customer address 2
        custAddr3:
          type: string
          description: Customer address 3
        totalDues:
          type: number
          description: Total due rewardPoints (in Omani Riyals) associated with the account
          example: 25.0
  responses:
    Generic400:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: INVALID_ARGUMENT
            status: 400
            message: "Schema validation failed at  ..."
    Generic401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: UNAUTHORIZED
            status: 401
            message: "Authorization failed: ..."
    Generic403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: FORBIDDEN
            status: 403
            message: "Operation not allowed: ..."
    Generic404:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: NOT_FOUND
            status: 404
            message: "The specified resource is not found"
    Generic409:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 409
            code: ALREADY_EXISTS
            message: "A specified resource duplicate entry found"
    Generic500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: SERVER_ERROR
            status: 500
            message: "Server Error"
    Generic503:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: SERVICE_UNAVAILABLE
            status: 503
            message: "Service unavailable"
    Generic504:
      description: Request timeout exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: REQUEST_TIMEOUT_EXCEEDED
            status: 504
            message: "Request timeout exceeded"
  parameters:
    mobileNumber:
      name: mobileNumber
      in: query
      description: Phone number of the  customer
      example: "92xxxxxx"
      schema:
        type: string
    fixedlineNumber:
      name: fixedlineNumber
      in: query
      description: Fixed line number of the  customer
      example: "IA123456"
      schema:
        type: string
    internetAccount:
      name: internetAccount
      in: query
      description: Internet Account of the  customer
      example: "24xxxxxx"
      schema:
        type: string
    customerAccountNumber:
      name: customerAccountNumber
      in: query
      description: Account number of the customer
      example: "12345678"
      schema:
        type: string
    clientCorrelatorId:
      name: clientCorrelatorId
      in: query
      schema:
        type: string
      description: |
        Client call can specify it to find individual transaction by its own unque ID. 
        Service will return matching record only. If `clientCorrelatorId` 
        is specified in the request, then service will consider only 
        `clientCorrelatorId` and return matching transaction only, and will
        ignore all other parameters.
    fromDate:
      name: fromDate
      in: query
      description: Results should be taken from this transaction date
      example: "2023-01-15"
      schema:
        type: string
        format: date
    toDate:
      name: toDate
      in: query
      description: Results should be taken up-to this transaction date
      example: "2023-01-31"
      schema:
        type: string
        format: date
    Page:
      name: page
      in: query
      description: Requested index to indicate the start of the resources to be provided in the response
      schema:
        type: integer
    PerPage:
      name: perPage
      in: query
      description: Requested number of resources to be provided in response
      schema:
        type: integer
    Seek:
      name: seek
      in: query
      description: Index of last result read to create the next/previous number of results. This query parameter is used for pagination in systems with more than 1000 records. `seek` parameter offers finer control than `page` and could be used one or another as an alternative. If both are used in combination (not recommended) `seek` would mark the index starting from the page number specified by `page` and `perPage` [index = (page * perPage) + seek].
      schema:
        type: integer
  headers:
    Content-Last-Key:
      description: Indicates the index of the last result provided in the response
      schema:
        type: integer
    X-Total-Count:
      description: Total number of items matching criteria
      schema:
        type: integer
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://apigw.omantel.om/oauth2/accesstoken
          scopes: {}