MTN Group Customer Promotion API

openapi: 3.2.0
info:
  title: Placeholder Customer Promotion API
  description: API Documentation
  version: '0.1'
servers:
- url: https://za.api.mtn.com/customerPromotion/v1
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: Customer Promotion
paths:
  /tbd/promo:
    get:
      summary: some function here
      description: promotion description
      tags:
      - Customer Promotion
      responses:
        '200':
          description: Success
  /eligibilityCheck/{msisdn}:
    get:
      tags:
      - Customer Promotion
      summary: ELigibility check of customer.
      description: ELigibility check for recharge and Win campaign. This API is used to retreive customer profile.
      operationId: getUserProfile
      parameters:
      - name: transactionId
        in: header
        description: Unique ID for the transaction.
        required: true
        schema:
          type: string
      - name: sourceIdentifier
        in: query
        description: This field denotes the channel that is initiating request to SOA like USSD, MyMTNApp
        required: true
        schema:
          type: string
      - name: msisdn
        in: path
        description: MSISDN of the customer whose eligibility check needs to be done
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Eligibility check success Response
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/eligibilityCheckResponse'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorised
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '415':
          description: Unsupported Media Type
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error415'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
  /optin:
    post:
      summary: This API is used to optin users on campaigns
      tags:
      - Customer Promotion
      parameters:
      - name: transactionId
        in: header
        description: Unique ID for the transaction.
        required: true
        schema:
          type: string
      - name: sourceIdentifier
        in: query
        description: This field denotes the channel that is initiating request to SOA like USSD, MyMTNApp
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success response for optin
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/optinResponse'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
        '415':
          description: Unsupported Media Type
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error415'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/optinRequest'
        description: Request parameters for customer Opt-In
        required: true
components:
  schemas:
    Error400:
      properties:
        statusCode:
          type: integer
          description: Status code from target system to indicate transaction status
          example: 5000
        statusMessage:
          type: string
          description: Status message from target system to indicate transaction status.
        supportMessage:
          type: string
          description: detail message from target system to indicate transaction status.
        transactionId:
          type: string
          description: This is the same transactionId that is sent in the request
          example: 0d1e1b18-1b6d-4792-8417-72d337f42a1c
    optinRequest:
      allOf:
      - required:
        - msisdn
        properties:
          optin:
            type: boolean
            description: this is true or false for user optin.
            example: true
          campaign:
            type: string
            description: Identifies the campaign you would like to optin or optout to.
            example: RECHARGE_AND_WIN
          msisdn:
            description: MSISDN of the customer who wants to redeem their reward. This will be cross-checked against the play id as pre provision safety measure
            type: string
            example: 27605220405
    RechargeOptions:
      required:
      - optin
      - nextRechargeBefore
      properties:
        optin:
          type: boolean
          example: true
        nextRechargeBefore:
          format: date-time
    balanceType:
      required:
      - type
      - balance
      properties:
        type:
          type: string
          enum:
          - DAILY
          - LOYALTY_SPEND_1
          - LOYALTY_SPEND_2
          - LOYALTY_SPEND_3
          - LIVE_DRAW
          description: Type of the balance that the customer is having in their profile
        balance:
          type: integer
          description: The amount of plays available
      description: "status:\n * `DAILY` - Daily plays awarded\n * `LOYALTY_SPEND_1` - plays awarded for loyalty points redeptions of less than 50 points\n * `LOYALTY_SPEND_2` - plays awarded for loyalty points redeptions of less than 250 points\n * `LOYALTY_SPEND_3` - plays awarded for loyalty points redeptions of more than 250 points\n * `LIVE_DRAW` - Plays awarded for visiting the draw announcement page during the live announcement window\n"
    reward:
      properties:
        redeemId:
          type: string
          example: '922625'
          description: The redeem id of the reward
        pool:
          type: string
          example: UNCONDITIONAL_GIFT
          description: The pool of the reward
        category:
          type: string
          example: Grocery
          description: The category of the reward
        subCategory:
          type: string
          example: Checkers
          description: The subcategory of the reward
        shortDescription:
          type: string
          example: ''
          description: The short description of the reward
        description:
          type: string
          example: R5000 CHECKERS VOUCHER
          description: The description of the reward
        properties:
          type: object
          properties:
            type:
              type: string
              example: VOUCHERCHECKERS
              description: The type of the reward
            value:
              type: integer
              example: 5000
              description: The value of the reward
            valueUnit:
              type: string
              example: R
              description: The unit of the reward value
            validity:
              type: integer
              example: 60
              description: The validity of the reward
            validityUnit:
              type: string
              example: Days
              description: The unit of the reward validity
            valueCents:
              type: integer
              example: 0
              description: The cost of redeeming the reward in cents
            valueFormatted:
              type: string
              example: R0
              description: The formatted cost of redeeming the reward
            discount:
              type: string
              example: 100%
              description: The discount applied to the reward
        awardedAt:
          type: string
          format: date-time
          example: '2023-11-07T07:00:23.559Z'
          description: The time when the reward was awarded
        redeemed:
          type: boolean
          example: false
          description: Whether the reward has been redeemed or not
        redeemedAt:
          type: string
          format: date-time
          example: ''
          description: The time when the reward was redeemed
        expired:
          type: boolean
          example: true
          description: Whether the reward has expired or not
        expiresAt:
          type: string
          format: date-time
          example: '2023-11-07T07:00:40.339Z'
          description: The time when the reward expires
        source:
          type: string
          example: GIFT
          description: The source of the reward
      description: "source:\n * `DAILY` - A prize won when playing the game using daily plays\n * `LOYALTY_SPEND_1` - A prize won when playing the game using low value loyalty spend plays\n * `LOYALTY_SPEND_2` - A prize won when playing the game using medium value loyalty spend plays\n * `LOYALTY_SPEND_3` - A prize won when playing the game using high value loyalty spend plays\n * `LIVE_DRAW` - A prize won when playing the game made available during the announcement window\n * `GIFT` - A reward gifted to the user via the gigting endpoint\n * `DRAW` - A prize in the weekly/monthly draw\n"
    Recharges:
      required:
      - SOID
      - price
      - location
      - date
      properties:
        SOID:
          type: string
          example: '1234'
        price:
          type: string
          example: '49'
        location:
          type: string
          example: Randburg
        date:
          type: string
          format: date-time
    reward1:
      properties:
        redeemId:
          type: string
          example: '922625'
          description: The redeem id of the reward
        pool:
          type: string
          example: UNCONDITIONAL_GIFT
          description: The pool of the reward
        category:
          type: string
          example: Grocery
          description: The category of the reward
        subCategory:
          type: string
          example: Checkers
          description: The subcategory of the reward
        shortDescription:
          type: string
          example: ''
          description: The short description of the reward
        description:
          type: string
          example: R5000 CHECKERS VOUCHER
          description: The description of the reward
        properties:
          type: object
          properties:
            type:
              type: string
              example: VOUCHERCHECKERS
              description: The type of the reward
            value:
              type: integer
              example: 5000
              description: The value of the reward
            valueUnit:
              type: string
              example: R
              description: The unit of the reward value
            validity:
              type: integer
              example: 60
              description: The validity of the reward
            validityUnit:
              type: string
              example: Days
              description: The unit of the reward validity
            valueCents:
              type: integer
              example: 0
              description: The cost of redeeming the reward in cents
            valueFormatted:
              type: string
              example: R0
              description: The formatted cost of redeeming the reward
            discount:
              type: string
              example: 100%
              description: The discount applied to the reward
        awardedAt:
          type: string
          format: date-time
          example: '2023-11-07T07:00:23.559Z'
          description: The time when the reward was awarded
        redeemed:
          type: boolean
          example: false
          description: Whether the reward has been redeemed or not
        redeemedAt:
          type: string
          format: date-time
          example: ''
          description: The time when the reward was redeemed
        expired:
          type: boolean
          example: true
          description: Whether the reward has expired or not
        expiresAt:
          type: string
          format: date-time
          example: '2023-11-07T07:00:40.339Z'
          description: The time when the reward expires
        source:
          type: string
          example: GIFT
          description: The source of the reward
      description: "source:\n * `DAILY` - A prize won when playing the game using daily plays\n * `LOYALTY_SPEND_1` - A prize won when playing the game using low value loyalty spend plays\n * `LOYALTY_SPEND_2` - A prize won when playing the game using medium value loyalty spend plays\n * `LOYALTY_SPEND_3` - A prize won when playing the game using high value loyalty spend plays\n * `LIVE_DRAW` - A prize won when playing the game made available during the announcement window\n * `GIFT` - A reward gifted to the user via the gigting endpoint\n * `DRAW` - A prize in the weekly/monthly draw     \n"
    Error401:
      properties:
        statusCode:
          type: integer
          description: Status code from target system to indicate transaction status
          example: 4000
        statusMessage:
          type: string
          description: Status message from target system to indicate transaction status.
          example: Unauthorised
        supportMessage:
          type: string
          description: detail message from target system to indicate transaction status.
          example: Please verify token environment and key
        faultMessage1:
          type: string
          description: ''
        faultMessage2:
          type: string
          description: fault message
    optinResponse:
      allOf:
      - required:
        - statusCode
        - statusMessage
        - transactionId
        - supportMessage
        properties:
          statusCode:
            type: string
            description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
            example: '0000'
            maxLength: 30
          statusMessage:
            type: string
            description: More details and corrective actions related to the error which can be shown to a client. Success for 200.
          supportMessage:
            type: string
            description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
          transactionId:
            type: string
            description: Unique reference number
            example: '100000172429605'
    Error415:
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp that the error occurred
          example: '2021-07-21T17:32:28Z'
        status:
          type: integer
          description: Status code from target system to indicate transaction status
          example: 415
        error:
          type: string
          description: error message
          example: Unsupported Media Type
        message:
          type: string
          description: details
        path:
          type: string
          description: The path that caused the error
    eligibilityCheckResponse:
      type: object
      properties:
        statusCode:
          type: string
          description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes',
          example: '0000'
          maxLength: 30
        statusMessage:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client. Success for 200.
        supportMessage:
          type: string
          description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
        transactionId:
          type: string
          description: Unique reference number
          example: '100000172429605'
        balances:
          type: array
          items:
            $ref: '#/components/schemas/balanceType'
          description: '''The amount of plays the user has available per game type. Balances expire daily at 12AM (midnight) The balance is redeemed by using the play endpoint to win a prize. Plays are not transferable between MSISDNs or game types''  '
        wallet:
          type: array
          items:
            $ref: '#/components/schemas/category1'
          description: "The user's rewards wallet that contains a collection of awarded prizes/gifts by category (redeemed and non-redeemed).\nThese rewards may come from various sources, e.g. playing one of the games, gift campaigns or prizes won in the live draw \nRewards are not transferable between MSISDNs.\nOrdered by awardedAt in descending order.   \n"
        draws:
          type: array
          items:
            $ref: '#/components/schemas/Draw'
          description: "A breakdown of draws, past and present that shows the number of entries a customer has aquired per draw.\nIf the user has won a prize in one of the respective draws, the details pertaining to the prize awarded are included \nA maximum of three draws will be shown, ordered by entriesOpenAt in descending order.\n"
        history:
          $ref: '#/components/schemas/History'
        rechargeOptions:
          $ref: '#/components/schemas/RechargeOptions'
        recharges:
          type: array
          items:
            $ref: '#/components/schemas/Recharges'
          description: 'A breakdown of draws, past and present that shows the number of entries a customer has aquired per draw.

            If the user has won a prize in one of the respective draws, the details pertaining to the prize awarded are included

            A maximum of three draws will be shown, ordered by entriesOpenAt in descending order.

            '
    Error500:
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp that the error occurred
          example: '2021-07-21T17:32:28Z'
        status:
          type: string
          description: status code from backend
          example: '500'
        error:
          type: string
          description: Type of error
          example: Internal Server Error
        message:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client
          example: Internal Server Error
        path:
          type: string
          description: The path that caused the error
    LogHistory:
      properties:
        recharge:
          type: string
          description: The time of recharge transaction
          format: date-time
        bundle:
          type: string
          example: BUY-1-500MB-1D-R500
        value:
          type: integer
          format: int32
          description: The value will be returned cents from Infinity and will be convered to Rand
          example: 500
        valueUom:
          type: string
          format: Rand
          description: The unit of measure of the value
          example: Rand
    History:
      required:
      - anniversary
      - lastRecharges
      - firstRecharge
      - log
      properties:
        anniversary:
          type: string
          format: date-time
        lastRecharges:
          type: string
          format: date-time
        firstRecharge:
          type: string
          format: date-time
        log:
          type: array
          items:
            $ref: '#/components/schemas/LogHistory'
    Draw:
      required:
      - entries
      - drawStatus
      - entriesOpenAt
      - entriesCloseAt
      - announcementStartAt
      - announcementEndAt
      properties:
        entries:
          type: integer
          format: int32
          description: 'The number of entries that have been awarded to the customer in question (Only applicalbe to draws shown in customer profile)

            '
        winner:
          type: boolean
          description: 'Whether the customer in question has won a pize in the draw (Only applicalbe to draws shown in customer profile)

            '
        drawStatus:
          type: string
          enum:
          - OPEN
          - CLOSED
          - LIVE
        entriesOpenAt:
          type: string
          format: date-time
          description: This field defines the time when the draws open for entries
        entriesCloseAt:
          type: string
          format: date-time
          description: When the draw no longer accepts entries
        announcementStartAt:
          type: string
          format: date-time
          description: When the live draw starts
        announcementEndAt:
          type: string
          format: date-time
          description: When the live draw ends
        prizes:
          type: array
          description: 'A list of prizes that pertain to the draw


            Draws shown in customer profile will only show prizes that pertain to the customer in question

            '
          items:
            required:
            - msisdn
            - reward
            properties:
              msisdn:
                type: string
                description: The msisdn of the winner of the prize. The value will be in international format i.e., 27867583465 [MQ] - Is the msisdn of the customer querying the service or the prize winner? [SOA] This is the winner
              reward:
                $ref: '#/components/schemas/reward'
      description: "drawStatus:\n * `OPEN` - The draw is accepting entries\n * `CLOSED` - The draw is no longer accepting entries\n * `LIVE` - The draw winners are being announced     \n"
    category1:
      $ref: '#/components/schemas/reward1'
    Error404:
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp that the error occurred
          example: '2021-07-21T17:32:28Z'
        status:
          type: integer
          description: Status code from target system to indicate transaction status
          example: 404
        error:
          type: string
          description: error message
          example: Not found
        message:
          type: string
          description: details
        path:
          type: string
          description: The path that caused the error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api.mtn.com/v1/oauth/access_token