swagger: '2.0'
info:
  description: To facilitate notifications. Allows 3PPs to register and have notifications processed to them from the applicable backends.
  version: v1.0
  title: Notifications API
schemes:
  - https
host: api.mtn.com
basePath: /v1
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: 'https://api.mtn.com/v1/oauth/access_token'
security:
  - OAuth2: []
tags:
  - name: Notifications
    description: Send Notifications
  - name: Registration
    description: 'Registration, update and delete Notifications'
paths:
  /notification/3PP:
    post:
      tags:
        - Registration
      summary: Register/Update 3PP for notification.
      description: Register/Update 3PP for notification.
      operationId: register3PPNotificationDetailsUsingPOST
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - in: body
          name: thirdParty
          description: thirdParty
          required: true
          schema:
            $ref: '#/definitions/ThirdParty'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/RegisterNotificationResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
      deprecated: false
      security:
        - OAuth2: []
  '/notification/3PP/{id}':
    get:
      tags:
        - Registration
      summary: Get 3PP notification details by id.
      description: Get 3PP notification details by id.
      operationId: get3PPNotificationDetailsByIdUsingGET
      produces:
        - '*/*'
      parameters:
        - name: id
          in: path
          description: id
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Success'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
      deprecated: false
    put:
      tags:
        - Registration
      summary: Update 3PP notification.
      description: Update 3PP notification for notifications.
      operationId: register3PPNotificationDetailsUsingPUT
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: id
          in: path
          description: id
          required: true
          type: string
        - in: body
          name: thirdParty
          description: thirdParty
          required: true
          schema:
            $ref: '#/definitions/ThirdParty'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Success'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
      deprecated: false
    delete:
      tags:
        - Registration
      summary: Delete 3PP notification registration by id.
      description: Delete 3PP notification registration by id.
      operationId: delete3PPNotificationDetailsByIdUsingDELETE
      produces:
        - '*/*'
      parameters:
        - name: id
          in: path
          description: id
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Success'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
      deprecated: false
    post:
      tags:
        - Notifications
      summary: Send notification to 3PP by id.
      description: Send notification to 3PP by id.
      operationId: notification3PPByIdUsingPOST
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: notificationData
          description: Notification data with objects and attributes that need to be passed onto the downstream system. Must be in valid JSON format.
          required: true
          schema:
            type: object
        - name: id
          in: path
          description: id that needs to be included as generated by MADAPI upon Registration
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Success'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
      deprecated: false
  '/notification/3PP/{targetSystem}/{code}/{notificationType}':
    post:
      tags:
        - Notifications
      summary: 'Send notification to 3PP by name, code and notification type.'
      description: 'Send notificaion to 3PP by name, code and notification type.'
      operationId: notification3PPByNameAndCodeAndnotificonTypeUsingPOST
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: notificationData
          description: notificationData
          required: true
          schema:
            type: object
        - name: notificationType
          in: path
          description: notificationType
          required: true
          type: string
        - name: code
          in: path
          description: code
          required: true
          type: string
        - name: targetSystem
          in: path
          description: Target System
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Success'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
      deprecated: false
    get:
      tags:
        - Registration
      summary: 'Get 3PP Notification details by target system, code and notification type.'
      description: 'Get 3PP Notification details by name, code and notification type.'
      operationId: get3PPNotificationDetailsByNameAndCodeAndNotificationTypeUsingGET
      produces:
        - '*/*'
      parameters:
        - name: notificationType
          in: path
          description: notificationType
          required: true
          type: string
        - name: code
          in: path
          description: code
          required: true
          type: string
        - name: targetSystem
          in: path
          description: Target System
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Success'
          examples:
            AYO AIRTIME Recharge Notification:
              statusCode: '0000'
              statusMessage: string
              transactionId: cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4
              timestamp: '2021-07-21T17:32:28Z'
              AdditionalData:
                id: Rec1
                targetsystem: AYO
                code: FZ-32-SFSG-1
                notificationURL: 'https://ayowebapi-team2.mmiholdings.co.za/api/v1/madapi/rechargenotification'
                notificationType: PUT
                countryCode: ZA
                created At: '2021-07-21T17:32:28Z'
                modified At: '2021-07-21T17:32:28Z'
                registration Status: Deleted
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
      deprecated: false
    delete:
      tags:
        - Registration
      summary: 'Delete 3PP Notification registration by target system, code and notification type.'
      description: 'Delete 3PP notification registration by name, code and notification type.'
      operationId: delete3PPNotificationDetailsByNameAndCodeAndNotificationTypeUsingDELETE
      produces:
        - '*/*'
      parameters:
        - name: notificationType
          in: path
          description: notificationtype
          required: true
          type: string
        - name: code
          in: path
          description: code
          required: true
          type: string
        - name: targetSystem
          in: path
          description: Target System
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Success'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
      deprecated: false
definitions:
  NotificationStatus:
    type: object
    properties:
      active:
        type: boolean
      id:
        type: string
      name:
        type: string
    title: NotificationStatus
  ThirdParty:
    type: object
    properties:
      notificationType:
        type: string
      notificationUrl:
        type: string
      targetSystem:
        type: string
      code:
        type: string
    title: ThirdParty
  CallingSystemEnum:
    type: string
    description: CallingSystemEnum
    enum:
      - ECW
      - AYO
  Error:
    type: object
    required:
      - statusCode
      - statusMessage
    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: '1000'
      statusMessage:
        type: string
        description: More details and corrective actions related to the error which can be shown to a client
      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: This is the same transactionId that is sent in the request
        example: 'cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4'
      timestamp:
        type: string
        format: date-time
        description: Timestamp that the error occurred
        example: '2021-07-21T17:32:28Z'
      path:
        type: string
        description: The path that caused the error
        example: /subscribers/27831234567
      method:
        type: string
        description: The HTTP method type that was used
        example: 'GET'
  RegisterNotificationResponse:
    type: object
    required:
      - statusCode
      - statusMessage
    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: '1000'
      statusMessage:
        type: string
        description: More details and corrective actions related to the error which can be shown to a client
      transactionId:
        type: string
        description: This is the same transactionId that is sent in the request
        example: 'cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4'
      id:
        type: string
        description: The id generated upon registration for notifications and to be used upon processing actual notifications
        example: 'c5f80cb8-dc8b-11ea-87d0-0242ac130003'
      links:
        $ref: '#/definitions/RegisterNotificationResponse__links_self'
  RegisterNotificationResponse__links:
    type: object
    properties:
      self:
        $ref: '#/definitions/RegisterNotificationResponse__links_self'
    description: Relevant links to the Notification created.
  RegisterNotificationResponse__links_self:
    type: object
    properties:
      href:
        type: string
        example: 'https://host:port/v1/'
        description: Hyperlink to access the Notification  created.
  Success:
    type: object
    required:
      - statusCode
      - statusMessage
    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'
      statusMessage:
        type: string
        description: More details and corrective actions related to the error which can be shown to a client
      transactionId:
        type: string
        description: This is the same transactionId that is sent in the request
        example: 'cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4'
      timestamp:
        type: string
        format: date-time
        description: Timestamp that the error occurred
        example: '2021-07-21T17:32:28Z'
      AdditionalData:
        $ref: '#/definitions/Data'
  Data:
    type: object
    properties:
      id:
        type: string
        description: Id that gets generated
        example: 'Rec1'
      targetsystem:
        type: string
        description: The intended system that will receive the notification
        example: 'AYO'
      code:
        type: string
        description: Code generated
        example: 'FZ-32-SFSG-1'
      notificationURL:
        type: string
        description: The URL that will receive the notifications
        example: 'https://ayowebapi-team2.mmiholdings.co.za/api/v1/madapi/rechargenotification'
      notificationType:
        type: string
        description: The method used
        example: 'PUT'
      countryCode:
        type: string
        example: 'ZA'
      created At:
        type: string
        format: date-time
        description: Date and time the request is created
        example: '2021-07-21T17:32:28Z'
      modified At:
        type: string
        format: date-time
        description: Date and time the request was modified
        example: '2021-07-21T17:32:28Z'
      registration Status:
        type: string
        description: Status of the registration
        example: 'Deleted'