MTN Group Registration API

openapi: 3.2.0
info:
  title: Mtn Group Registration API
  version: '1.0'
  description: 'Operations tagged Registration across 3 of this provider''s published API definitions: mtn-group-customer-billing-token-v1.yml, mtn-group-notification-production.yml, mtn-group-notification-v2.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mtn.com/v1/customer
- url: https://api.mtn.com/v1
- url: https://api.mtn.com/v2
tags:
- name: Registration
paths:
  /bill/registerToken:
    post:
      tags:
      - Registration
      summary: Register Token Service
      description: Billing Recurring Service Token Registration
      operationId: Register
      parameters:
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
          enum:
          - Pantheon
          - SOA
          default: Pantheon
      - name: allowPoll
        in: header
        required: true
        schema:
          type: boolean
          enum:
          - true
          - false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadReq'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '452':
          description: Invalid API Version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInvAPIVersion'
        '454':
          description: MSISDN Not Provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMsisdnNotProvided'
        '463':
          description: Subscription Channel Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSubChanNotFound'
        '464':
          description: Subscription Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSubNotFound'
        '466':
          description: Service Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSvcNotFound'
        '467':
          description: Active Subscription Exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorActSubsEx'
        '470':
          description: Service Not Linked To Billing Channel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSvcNotLinked'
        '473':
          description: Service ID or Service Ref Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSvcIdSvcRefNotFound'
        '478':
          description: Invalid MSISDN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInvMsisdn'
        '480':
          description: Invalid Billing Rate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInvBillRate'
        '485':
          description: Pending Subscription Exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPendingSubEx'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '515':
          description: Subscription Not Active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSubNotActive'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterTokenRequest'
        required: true
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v1/customer
  /notification/3PP:
    post:
      tags:
      - Registration
      summary: Register/Update 3PP for notification.
      description: Register/Update 3PP for notification.
      operationId: register3PPNotificationDetailsUsingPOST
      responses:
        '201':
          description: Created
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/RegisterNotificationResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
      deprecated: false
      security:
      - OAuth2: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThirdParty'
        description: thirdParty
        required: true
    servers:
    - url: https://api.mtn.com/v1
  /notification/3PP/{id}:
    get:
      tags:
      - Registration
      summary: Get 3PP notification details by id.
      description: Get 3PP notification details by id.
      operationId: get3PPNotificationDetailsByIdUsingGET
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
      deprecated: false
      security:
      - OAuth2: []
    put:
      tags:
      - Registration
      summary: Update 3PP notification.
      description: Update 3PP notification for notifications.
      operationId: register3PPNotificationDetailsUsingPUT
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThirdParty'
        description: thirdParty
        required: true
      security:
      - OAuth2: []
    delete:
      tags:
      - Registration
      summary: Delete 3PP notification registration by id.
      description: Delete 3PP notification registration by id.
      operationId: delete3PPNotificationDetailsByIdUsingDELETE
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
      deprecated: false
      security:
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v1
  /notification/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
      parameters:
      - name: notificationType
        in: path
        description: notificationType
        required: true
        schema:
          type: string
      - name: code
        in: path
        description: code
        required: true
        schema:
          type: string
      - name: targetSystem
        in: path
        description: Target System
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
      deprecated: false
      security:
      - OAuth2: []
    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
      parameters:
      - name: notificationType
        in: path
        description: notificationtype
        required: true
        schema:
          type: string
      - name: code
        in: path
        description: code
        required: true
        schema:
          type: string
      - name: targetSystem
        in: path
        description: Target System
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_2'
      deprecated: false
      security:
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v1
  /notification/register/3PP:
    post:
      tags:
      - Registration
      summary: Register/Update 3PP for notification.
      description: Register/Update 3PP for notification.
      operationId: register3PPNotificationDetailsUsingPOST
      parameters:
      - in: header
        name: transactionId
        description: A unique identifier for the transaction
        schema:
          type: string
      responses:
        '201':
          description: Created
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/RegisterNotificationResponse_2'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterNotificationRequest'
        description: This is the request used for notification registration.
        required: true
      security:
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v2
  /notification/register/3PP/{id}:
    get:
      tags:
      - Registration
      summary: Get 3PP notification details by id.
      description: Get 3PP notification details by id.
      operationId: get3PPNotificationDetailsByIdUsingGET
      parameters:
      - in: header
        name: transactionId
        description: A unique identifier for the transaction
        schema:
          type: string
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DeleteNotificationSubscriptionResponse'
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
      deprecated: false
      security:
      - OAuth2: []
    delete:
      tags:
      - Registration
      summary: Delete 3PP Notification registration by id.
      description: Delete 3PP notification registration by id.
      operationId: delete3PPNotificationDetailsByIDUsingDELETE
      parameters:
      - in: header
        name: transactionId
        description: A unique identifier for the transaction
        schema:
          type: string
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DeleteNotificationSubscriptionResponse'
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
      deprecated: false
      security:
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v2
  /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
      parameters:
      - name: notificationType
        in: path
        description: notificationType
        required: true
        schema:
          type: string
      - name: code
        in: path
        description: code
        required: true
        schema:
          type: string
      - name: targetSystem
        in: path
        description: Target System
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        description: Internal use only
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DeleteNotificationSubscriptionResponse'
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
      deprecated: false
      security:
      - OAuth2: []
    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
      parameters:
      - name: notificationType
        in: path
        description: notificationtype
        required: true
        schema:
          type: string
      - name: code
        in: path
        description: code
        required: true
        schema:
          type: string
      - name: targetSystem
        in: path
        description: Target System
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        description: Internal use only
        schema:
          type: string
      - name: x-country-code
        in: header
        description: Internal use only
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DeleteNotificationSubscriptionResponse'
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error_3'
      deprecated: false
      security:
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v2
components:
  schemas:
    RelatedParty:
      type: object
      description: Related Entity reference. A related party defines party or party role linked to a specific entity.
      required:
      - '@referredType'
      - id
      properties:
        id:
          type: string
          description: Unique identifier of a related entity eg MSISDN.
          example: 9994746
        role:
          type: string
          description: Role played by the related party
          example: Customer
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    Price:
      type: object
      description: Provides all amounts (tax included, duty free, tax rate), used currency and percentage to apply for Price Alteration.
      properties:
        taxIncludedAmount:
          $ref: '#/components/schemas/Money'
          description: All taxes included amount (expressed in the given currency)
    ErrorActSubsEx:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 1002
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Active Subscription Exists'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    ErrorInvBillRate:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 1006
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Invalid Billing Rate'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    ErrorSubNotActive:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 1003
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Subscription Not Active'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    CreateOrderResponse:
      required:
      - statusCode
      - statusMessage
      - data
      type: object
      properties:
        statusCode:
          type: string
          description: Result code. Example- '0000'
        statusMessage:
          type: string
          description: Result message. Example- 'Successfully processed'
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
        data:
          type: object
          properties:
            billingToken:
              type: object
              properties:
                msn:
                  type: string
                  minLength: 16
                  maxLength: 64
                  description: This field represents the message sequence number assigned by the CGW this can be used to uniquely track submitted requests.
                  example: '5115314911298406'
                contentToken:
                  type: string
                  minLength: 16
                  maxLength: 96
                  description: Token generated to be used for identifying the service for activation, billing, cancellation and refund.
                  example: 81B27C92607C6D47274C2859CF51B954A4EE99DFCC7DD89066F6CD41D74A10CE23CCD7C8A32B73DEDC0F2470B703F058
                allowToActivate:
                  type: boolean
                  description: Information inidicating if activation of token will be allowed.
                  example: true
                proposalIndicator:
                  type: integer
                  description: This indicates what is proposed, 0 - Nothing, 1 - Spend Limit only, 2 - Digital Limit only, 3 - Both Digital and Spend Limit, 4 - Nothing with SUL equals to SPUL and Digital Limit equal to New Monthly Committed Value
                  enum:
                  - 0
                  - 1
                  - 2
                  - 3
                  - 4
                proposedDigitalLimit:
                  type: integer
                  minimum: 1
                  maximum: 999999
                  description: This the proposed digital limit in Rxx whole rands only.
                  example: 25000
                proposedSpendLimit:
                  type: integer
                  minimum: 1
                  maximum: 999999
                  description: This the proposed digital limit in Rxx whole rands only.
                  example: 25000
                proratedBill:
                  type: integer
                  minimum: 0
                  maximum: 999999
                  description: The prorated amount in cents. Note, this field won't be returned if the token is not a monthly token, which is specified via selectedDebitOrderDate
                  example: 90
                proratedBillDate:
                  type: string
                  minLength: 10
                  maxLength: 10
                  description: The date upon which the prorated billing will be performed, in the format 'yyyy-mm-dd'. Note, this field won't be returned if the token is not a monthly token, which is specified via selectedDebitOrderDate
                  example: '2023-02-22'
            subscription:
              $ref: '#/components/schemas/ProductOrder2'
    ErrorInvMsisdn:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 1008
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Invalid MSISDN'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider s

# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-registration-api-openapi.yml