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: "v2.0"
title: Notifications API
schemes:
- https
host: "api.mtn.com"
basePath: "/v2"
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/register/3PP":
post:
tags:
- Registration
summary: Register/Update 3PP for notification.
description: Register/Update 3PP for notification.
operationId: register3PPNotificationDetailsUsingPOST
consumes:
- application/json
produces:
- "*/*"
parameters:
- in: header
name: transactionId
description: "A unique identifier for the transaction"
type: string
- in: body
name: RegisterNotificationRequest
description: This is the request used for notification registration.
required: true
schema:
$ref: "#/definitions/RegisterNotificationRequest"
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
"/notification/register/3PP/{id}":
get:
tags:
- Registration
summary: Get 3PP notification details by id.
description: Get 3PP notification details by id.
operationId: get3PPNotificationDetailsByIdUsingGET
produces:
- "*/*"
parameters:
- in: header
name: transactionId
description: "A unique identifier for the transaction"
type: string
- name: id
in: path
description: id
required: true
type: string
responses:
'200':
description: OK
schema:
$ref: "#/definitions/DeleteNotificationSubscriptionResponse"
'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
delete:
tags:
- Registration
summary: Delete 3PP Notification registration by id.
description: Delete 3PP notification registration by id.
operationId: delete3PPNotificationDetailsByIDUsingDELETE
produces:
- "*/*"
parameters:
- in: header
name: transactionId
description: "A unique identifier for the transaction"
type: string
- name: id
in: path
description: id
required: true
type: string
responses:
'200':
description: OK
schema:
$ref: "#/definitions/DeleteNotificationSubscriptionResponse"
'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
"/notification/3PP/{id}":
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: header
name: transactionId
description: "A unique identifier for the transaction"
type: string
- in: body
name: NotificationData
description: The request expected to trigger a notification
required: true
schema:
"$ref": "#/definitions/NotificationData"
- 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/SendNotificationResponse"
'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/register/3PP/{targetSystem}/{code}/{notificationType}":
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
- name: transactionId
in: header
description: Internal use only
type: string
responses:
'200':
description: OK
schema:
$ref: "#/definitions/DeleteNotificationSubscriptionResponse"
'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
- name: transactionId
in: header
description: Internal use only
type: string
- name: x-country-code
in: header
description: Internal use only
type: string
responses:
'200':
description: OK
schema:
$ref: "#/definitions/DeleteNotificationSubscriptionResponse"
'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
"/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:
- 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
- in: header
name: transactionId
description: "A unique identifier for the transaction"
type: string
- in: body
name: NotificationData
description: The request expected to trigger a notification
required: true
schema:
"$ref": "#/definitions/NotificationData"
responses:
'200':
description: OK
schema:
$ref: "#/definitions/SendNotificationResponse"
'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
definitions:
NotificationData:
description: The model expected to trigger a notification
type: object
properties:
data:
description: The data to be send as the notification. This must be a valid JSON request
type: object
deliveryReportUrl:
description: The delivery report url. The status/report of the notification delivery is send to this url. It expects an object of the type definitions/DeliveryReportRequest. Ex. ```{"statusCode":"","statusMessage":"","transationId":"","sequenceNo":""}```. The response is of type definitions/DeliveryReportResponse. Ex. ```{"statusCode":"","statusMessage":""}```
type: string
example: "http://deliveryreporturl.com.ng"
RegisterNotificationRequest:
description: This is the model expected for notification registration request.
type: object
properties:
notificationType:
type: string
notificationUrl:
type: string
targetSystem:
type: string
code:
type: string
Error:
type: object
description: Generic MADAPI error response
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'
sequenceNo:
type: string
description: This is a unique transaction Identifier returned to the client
example: '90dba2e7-676b-45c7-b4a0-9e82eb975596'
timestamp:
type: string
format: date-time
description: Timestamp that the error occurred
example: '2020-08-01T12:34'
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
description: This is the response expected for a notification registration request.
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'
sequenceNo:
type: string
description: This is a unique transaction Identifier returned to the client
example: '12345'
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:
type: object
properties:
href:
type: string
example: https://host:port/v1/
description: Hyperlink to access the Notification created.
DeleteNotificationSubscriptionResponse:
type: object
description: The response for deleting a notification subscription
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'
sequenceNo:
type: string
description: This is a unique transaction Identifier returned to the client
example: '12345'
timestamp:
type: string
format: date-time
description: Timestamp that the error occurred
example: '2020-08-01T12:34'
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'
createdAt:
type: string
format: date-time
description: Date and time the request is created
example: '2020-08-01T12:34:400Z'
modifiedAt:
type: string
format: date-time
description: Date and time the request was modified
example: '2020-08-01T12:34:400Z'
registrationStatus:
type: string
description: Status of the registration
example: 'Deleted'
SendNotificationResponse:
type: object
description: The response expected after triggering a notification
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'
sequenceNo:
type: string
description: This is a unique transaction Identifier returned to the client
example: '12345'
DeliveryReportRequest:
type: object
description: This the request send to the delivery report url received in the send notification urls. It is used to notify the status of a notification to the party triggering a notification.
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'
sequenceNo:
type: string
description: This is a unique transaction Identifier returned to the client
example: '12345'
DeliveryReportResponse:
type: object
description: This the response expected from the delivery report url received in the send notification request.
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'
status:
type: string
description: The final status of the nofification delivery
NotificationResponse:
type: object
description: This the response expected when the notification is delivered.
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).
example: '0000'