openapi: 3.0.3
info:
  description: "This API allows API consumers to redeem loyalty points. \n\n# Introduction\n\
    \nThis API lets API Consumers to redeem loyalti points (makasib points). \n \n\
    \n# API Functionality\n\nThis API allows to clients to redeem loyalty points..\n\
    \nThe API provides several endpoints/operations:\n- An endpoint to initiate redemption\
    \ transaction.\n- A set of endpoints to retrieve transaction details, history\
    \ of transactions.\n    \n "
  version: 1.0.0
  title: Loyalty/Makasib Points redemption Service
  
servers:
- url: https://apigw.omantel.om
  variables:
    apiRoot:
      default: https://apigw.omantel.om
      description: API root
    basePath:
      default: /makasibredemption/v1
      description: Base path for the Makasib Redemption API
tags:
- name: Redemptions
  description: Operations to perform redemption transaction
- name: Redemptions Inquiry
  description: Operations to query redemption transaction
paths:
  /makasibredemption/v1/redemptions:
    post:
      security:
        - oAuth2ClientCredentials: []
      tags:
      - Redemptions
      summary: Perform redemption transaction
      operationId: redeemPoints
      description: Perform redemption transaction.
      requestBody:
        description: Perform redemption transaction
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRedemption'
      responses:
        201:
          description: <b>Created</b>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionCreated'
        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
        409:
          $ref: '#/components/responses/Generic409'
        500:
          $ref: '#/components/responses/Generic500'
        503:
          $ref: '#/components/responses/Generic503'
        504:
          $ref: '#/components/responses/Generic504'
    get:
      security:
        - oAuth2ClientCredentials: []
      tags:
      - Redemptions Inquiry
      summary: Get a list of redemptions posted to this service
      operationId: retrieveRedemptions
      description: Retrieve a list of redemptions 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/RedemptionArray'
        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'
  /makasibredemption/v1/redemptions/{redemptionId}:
    get:
      security:
        - oAuth2ClientCredentials: []
      tags:
      - Redemptions Inquiry
      summary: Get redemption details for the specified redemption ID
      operationId: retrieveRedemptionDetail
      description: Retrieve redemption details for the specified redemption ID.
      parameters:
      - name: redemptionId
        in: path
        description: Redemption identifier that was obtained from the redemption request
          (Omantel generated `redemptionId`)
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Redemption'
        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'
  
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
    CreateRedemption:
      type: object
      required:
      - redemptionTransaction
      properties:
        redemptionTransaction:
          $ref: '#/components/schemas/RedemptionTransaction'
        webhook:
          $ref: '#/components/schemas/Webhook'
    RedemptionCreated:
      type: object
      required:
      - redemptionId
      - transactionOperationStatus
      properties:
        redemptionId:
          type: string
          description: "Unique Identifier of the redemption created in Omantel Loyalti\
            \ Management System. It\ncan be used to query status of the transaction\
            \ \n"
        transactionOperationStatus:
          $ref: '#/components/schemas/TransactionOperationStatus'
        redemptionDate:
          type: string
          format: date-time
          description: Date time, in ISO-8601 extended local date format, when the
            redemption 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'
    Redemption:
      type: object
      required:
      - redemptionTransaction
      - redemptionId
      properties:
        redemptionId:
          type: string
          description: "Unique Identifier of the redemption transaction. It can be\
            \ used\nto get details of the transaction using \n`GET/redemptions/{redemptionId}`\
            \ API.\n"
        transactionOperationStatus:
          $ref: '#/components/schemas/TransactionOperationStatus'
        redemptionTransaction:
          $ref: '#/components/schemas/RedemptionTransaction'
        redemptionDate:
          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
    RedemptionTransaction:
      type: object
      required:
      - clientCorrelatorId
      - mobileNumber
      properties:
        clientCorrelatorId:
          type: string
          description: "Uniquely identifies this transaction request. If there is\n\
            a communication failure during the request processing, \nusing the same\
            \ `clientCorrelatorId` when retrying the request \nallows Omantel to avoid\
            \ executing the transaction twice. \nThis field SHOULD be present to avoid\
            \ duplicate points addition.\n"
        referenceCode:
          type: string
          description: Merchant generated redemption reference to uniquely identify
            the request, for instance, in the case of disputes.
        redemptionInformation:
          $ref: '#/components/schemas/RedemptionInformation'
        redemptionMetaData:
          $ref: '#/components/schemas/RedemptionMetaData'
    RedemptionInformation:
      type: object
      required:
      - redemptionPoints
      properties:
        redemptionPoints:
          type: number
          format: float
          description: Amount to be redeemed.
        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'
    RedemptionMetaData:
      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
      - pending
      - success
      - failed
      - cancelled
      - invalid
      - expired
      - declined
      - reversed
    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
    RedemptionArray:
      description: A list of payment(s)
      type: array
      minItems: 0
      items:
        $ref: '#/components/schemas/Redemption'
  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:
    clientCorrelatorId:
      name: clientCorrelatorId
      in: query
      schema:
        type: string
      description: "Client call can specify it to find individual transaction by its\
        \ own unque ID. \nService will return matching record only. If `clientCorrelatorId`\
        \ \nis specified in the request, then service will consider only \n`clientCorrelatorId`\
        \ and return matching transaction only, and will\nignore all other parameters.\n"
    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: {}