openapi: 3.2.0
info:
  title: Mtn Group Callback API
  version: '1.0'
  description: 'Operations tagged Callback across 2 of this provider''s published API definitions: mtn-group-kyc-consent.yml, mtn-group-mtn-subscription-api-v2.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mtn.com/v1
  description: Production Server
- url: https://api.mtn.com/v2
tags:
- name: Callback
paths:
  /callback:
    post:
      tags:
      - Callback
      summary: The user consent information posted here as a callback from consent application
      description: The user consent information posted here as a callback from consent application. This endpoint for Consent Callback with consent id. Customer id and callback data required
      operationId: Callback_post_consentCallback_callback
      parameters:
      - name: clientCallbackUrl
        in: header
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: ConsentCallbackRequest
              required:
              - msisdn
              - transId
              type: object
              properties:
                data:
                  title: ConsentCallbackData
                  required:
                  - chenosisCallBackUrl
                  - consentId
                  - status
                  type: object
                  properties:
                    consentId:
                      type: string
                    chenosisCallBackUrl:
                      type: string
                    reqBody:
                      type: string
                    errorMessage:
                      type: string
                    applicationName:
                      type: string
                    status:
                      type: string
                transId:
                  type: string
                msisdn:
                  type: string
        required: true
      responses:
        '200':
          description: Success
        '400':
          description: Bad request. Invalid request parameters, missing required fields, or validation errors.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Bad request. Invalid request parameters, missing required fields, or validation errors.
                  transactionId: '1234567890'
                  statusCode: '400'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
        '401':
          description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure.
                  transactionId: '1234567890'
                  statusCode: '401'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
        '403':
          description: Forbidden. Access denied. The request is valid but the server refuses to perform it.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it.
                  transactionId: '1234567890'
                  statusCode: '403'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
        '404':
          description: Not found. The requested resource was not found or does not exist.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Not found. The requested resource was not found or does not exist.
                  transactionId: '1234567890'
                  statusCode: '404'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
        '500':
          description: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems.
                  transactionId: '1234567890'
                  statusCode: '500'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
        '502':
          description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server.
                  transactionId: '1234567890'
                  statusCode: '502'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
        '503':
          description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload.
                  transactionId: '1234567890'
                  statusCode: '503'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
      deprecated: false
      security:
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v1
      description: Production Server
  /callback/delete-all-subscriptions:
    post:
      tags:
      - Callback
      summary: Callback service that MTN API will POST to with the result of the DELETE all subscriptions
      description: The result of the asynchronous DELETE for all a customers subscriptions will be POSTed to the callback URL that the developer must host. If there were multiple subscriptions, each result will be posted individually as it completes.
      operationId: Callback service that MTN API will POST to with the result of the DELETE all subscriptions
      responses:
        200:
          description: OK
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Unsubscribe'
        required: true
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v2
components:
  schemas:
    StatusEnum:
      type: string
      title: statusEnum
      example: Unsubscribe successful
      enum:
      - Unsubscribe successful
      - Unsubscribe unsuccessful
    Unsubscribe:
      type: object
      title: unsubscribe
      required:
      - status
      - statusCode
      - description
      properties:
        subscriptionId:
          type: integer
          description: ID for the Subscription
        subscriptionProviderId:
          type: integer
          description: Identity of the subscription provider hosting the subscription
        statusCode:
          type: integer
          description: Status Code
        status:
          $ref: '#/components/schemas/StatusEnum'
        description:
          type: string
          description: Details of the result of the unsubscribe action
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.mtn.com/v1/oauth/access_token
          scopes: {}
    Bearer:
      type: http
      description: Bearer token received from OAuth2.0 authentication with the MADAPI
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
x-refined-from:
- mtn-group-kyc-consent.yml
- mtn-group-mtn-subscription-api-v2.yml