To facilitate notifications. Allows 3PPs to register and have notifications processed to them from the applicable backends.
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'