openapi: 3.0.1
info:
  title: Pin Management V2
  description: "This API provides comprehensive PIN Management capabilities for MTN\
    \ customers including PIN creation, validation, updates, resets, and profile management.\
    \ It serves as the integration layer for PIN-related operations across the MTN\
    \ ecosystem."
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: 3.0.0 - Last updated date:2026-10-12 17:26:04
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: Pin Management V2
- name: customer Pin
paths:
  /customer/{customerId}/pin:
    put:
      tags:
      - Pin Management V2
      summary: "To change Pin Details user will enter (customerId, operationType,\
        \ currentSecret, newSecret,channel,transId) Attributes"
      description: "To change Pin Details, user must enter the 'MSISDN/Service Number\
        \ of Customer'. User has to enter the 'current Secret/PIN' and 'New Secret/PIN'.\
        \ User will enter Security Answer selected during first time Secret/PIN Creation.\
        \ Finally the user will enter the 'channel id' & 'Unique Trans ID as per below\
        \ format yyyymmddhhmmss i.e 20200711123459105"
      operationId: PinManagementService_put_changeCustomerPin_customercustomerIdpi
      parameters:
      - name: X-Authorization
        in: header
        required: false
        schema:
          type: string
      - name: channel
        in: header
        required: false
        schema:
          type: string
      - name: countryCode
        in: header
        required: false
        schema:
          type: string
      - name: currentSecret
        in: header
        required: false
        schema:
          type: string
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: dateOfBirth
        in: query
        required: false
        schema:
          type: string
      - name: description
        in: query
        required: false
        schema:
          type: string
      - name: idNumber
        in: query
        required: false
        schema:
          type: string
      - name: idType
        in: query
        required: false
        schema:
          type: string
      - name: identityType
        in: query
        required: false
        schema:
          type: string
      - name: motherName
        in: query
        required: false
        schema:
          type: string
      - name: newSecret
        in: header
        required: true
        schema:
          type: string
      - name: repeatedSecret
        in: header
        required: false
        schema:
          type: string
      - name: requestType
        in: query
        required: false
        schema:
          type: string
      - name: securityAnswer
        in: header
        required: false
        schema:
          type: string
      - name: segment
        in: query
        required: false
        schema:
          type: string
      - name: stateOfOrigin
        in: query
        required: false
        schema:
          type: string
      - name: targetSystem
        in: query
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: validateAnswers
        in: query
        required: false
        schema:
          type: string
      - name: x-origin-channelid
        in: header
        required: false
        schema:
          type: string
      responses:
        "200":
          description: HTTP 200 indicating the request succeeded; the response body
            follows the documented schema for this operation and includes correlation
            identifiers where applicable for traceability across MTN MADAPI Pin Management
            flows.
          content:
            application/json:
              schema:
                title: ChangeOrResetPinResponse
                type: object
                properties:
                  statusCode:
                    type: string
                  statusMessage:
                    type: string
                  transactionId:
                    type: string
                  sequenceNo:
                    type: string
                  error:
                    title: APIError
                    type: object
                    properties:
                      statusMessage:
                        type: string
                      supportMessage:
                        type: string
                      transactionId:
                        type: string
                      timestamp:
                        type: string
                      path:
                        type: string
                      method:
                        type: string
                      statusCode:
                        type: string
                      downstreamStatusCode:
                        type: integer
                        format: int32
                      sequenceNo:
                        type: string
                  data:
                    title: ChangePinCisResponse
                    type: object
                    properties:
                      statusCode:
                        type: string
                      statusMessage:
                        type: string
                      transactionId:
                        type: string
                      supportMessage:
                        type: string
                      customerId:
                        type: string
                      data:
                        title: ChangePinResponseData
                        type: object
                        properties:
                          message:
                            type: string
                          amountCharged:
                            title: Amount
                            type: object
                            properties:
                              value:
                                type: string
                              unit:
                                type: string
                          success:
                            type: boolean
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "400"
                statusMessage: "Bad request. Invalid request parameters, missing required\
                  \ fields, or validation errors."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "401"
                statusMessage: "Unauthorized. Invalid or missing authorization credentials,\
                  \ insufficient permissions, or authentication failure."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "403":
          description: Forbidden. Access denied. The request is valid but the server
            refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "403"
                statusMessage: Forbidden. Access denied. The request is valid but
                  the server refuses to perform it.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "404"
                statusMessage: Not found. The requested resource was not found or
                  does not exist.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "500":
          description: "Internal server error. Unexpected system failure, database\
            \ connectivity issues, or external service integration problems."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "500"
                statusMessage: "Internal server error. Unexpected system failure,\
                  \ database connectivity issues, or external service integration\
                  \ problems."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "502":
          description: Bad gateway. The server acting as a gateway received an invalid
            response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "502"
                statusMessage: Bad gateway. The server acting as a gateway received
                  an invalid response from an upstream server.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "503":
          description: Service unavailable. The server is temporarily unable to handle
            the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "503"
                statusMessage: Service unavailable. The server is temporarily unable
                  to handle the request due to maintenance or overload.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
      deprecated: false
    post:
      tags:
      - Pin Management V2
      summary: "To create Pin Details will enter (countryCode, secret, repeatedSecret,\
        \ channel,customerId) Attributes"
      description: "To create Pin Details, user must enter the MSISDN/Service Number\
        \ of Customer, the PIN number, alternate mobile Number , Answer for the Security\
        \ Question and valid channel id. Finally the user will enter the Unique Trans\
        \ ID as per below format yyyymmddhhmmss i.e 20200711123459103"
      operationId: PinManagementService_post_createCustomerPin_customercustomerIdpi
      parameters:
      - name: X-Authorization
        in: header
        required: false
        schema:
          type: string
      - name: alternateNumber
        in: header
        required: false
        schema:
          type: string
      - name: channel
        in: header
        required: true
        schema:
          type: string
      - name: countryCode
        in: header
        required: true
        schema:
          type: string
      - name: currency
        in: query
        required: false
        schema:
          type: string
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: description
        in: header
        required: false
        schema:
          type: string
      - name: emailID
        in: header
        required: false
        schema:
          type: string
      - name: idType
        in: query
        required: false
        schema:
          type: string
      - name: invitationCode
        in: query
        required: false
        schema:
          type: string
      - name: repeatedSecret
        in: header
        required: false
        schema:
          type: string
      - name: secret
        in: header
        required: true
        schema:
          type: string
      - name: segment
        in: query
        required: false
        schema:
          type: string
      - name: targetSystem
        in: query
        required: false
        schema:
          type: string
      - name: tncDetails
        in: header
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: SecurityQuestionAnswers
              type: object
              properties:
                SecurityQuestionAnswer:
                  title: SecurityQuestionAnswer
                  type: object
                  properties:
                    securityQuestion:
                      type: string
                    securityAnswer:
                      type: string
        required: true
      responses:
        "200":
          description: HTTP 200 indicating the request succeeded; the response body
            follows the documented schema for this operation and includes correlation
            identifiers where applicable for traceability across MTN MADAPI Pin Management
            flows.
          content:
            application/json:
              schema:
                title: CreatePinResponse
                type: object
                properties:
                  statusCode:
                    type: string
                  statusMessage:
                    type: string
                  message:
                    type: string
                  transactionId:
                    type: string
                  customerId:
                    type: string
                  sequenceNo:
                    type: string
                  data:
                    title: CreatePinResponseData
                    type: object
                    properties:
                      message:
                        type: string
                      code:
                        type: string
                      error:
                        type: array
                        items:
                          title: Error
                          type: object
                          properties:
                            message:
                              type: string
                            code:
                              type: string
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "400"
                statusMessage: "Bad request. Invalid request parameters, missing required\
                  \ fields, or validation errors."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "401"
                statusMessage: "Unauthorized. Invalid or missing authorization credentials,\
                  \ insufficient permissions, or authentication failure."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "403":
          description: Forbidden. Access denied. The request is valid but the server
            refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "403"
                statusMessage: Forbidden. Access denied. The request is valid but
                  the server refuses to perform it.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "404"
                statusMessage: Not found. The requested resource was not found or
                  does not exist.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "500":
          description: "Internal server error. Unexpected system failure, database\
            \ connectivity issues, or external service integration problems."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "500"
                statusMessage: "Internal server error. Unexpected system failure,\
                  \ database connectivity issues, or external service integration\
                  \ problems."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "502":
          description: Bad gateway. The server acting as a gateway received an invalid
            response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "502"
                statusMessage: Bad gateway. The server acting as a gateway received
                  an invalid response from an upstream server.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "503":
          description: Service unavailable. The server is temporarily unable to handle
            the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "503"
                statusMessage: Service unavailable. The server is temporarily unable
                  to handle the request due to maintenance or overload.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
      deprecated: false
    patch:
      tags:
      - Pin Management V2
      summary: "To reset Pin Details user will enter (customerId, operationType, validateAnswers,\
        \ motherName,dateOfBirth,stateOfOrigin,channel,transId) Attributes"
      description: "To reset Pin Details, user must enter the 'MSISDN/Service Number\
        \ of Customer'. User has to enter the Y-indicates validate security answer,\
        \ N-indicates no validation for Validate Answers'. User will enter Mothers\
        \ maiden name also will enter the Date of Birth in format YYYY-MM-DD and State\
        \ of Origin code. Finally the user will enter the 'channel id' & 'Unique Trans\
        \ ID as per below format yyyymmddhhmmss i.e 20200711123459105"
      operationId: PinManagementService_patch_resetCustomerPin_customercustomerIdpi
      parameters:
      - name: X-Authorization
        in: header
        required: false
        schema:
          type: string
      - name: channel
        in: header
        required: true
        schema:
          type: string
      - name: countryCode
        in: header
        required: true
        schema:
          type: string
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: dateOfBirth
        in: query
        required: false
        schema:
          type: string
      - name: description
        in: query
        required: false
        schema:
          type: string
      - name: idNumber
        in: query
        required: false
        schema:
          type: string
      - name: identityType
        in: query
        required: false
        schema:
          type: string
      - name: motherName
        in: query
        required: false
        schema:
          type: string
      - name: stateOfOrigin
        in: query
        required: false
        schema:
          type: string
      - name: targetSystem
        in: query
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: validateAnswers
        in: query
        required: false
        schema:
          type: string
      - name: x-origin-channelid
        in: header
        required: false
        schema:
          type: string
      responses:
        "200":
          description: HTTP 200 indicating the request succeeded; the response body
            follows the documented schema for this operation and includes correlation
            identifiers where applicable for traceability across MTN MADAPI Pin Management
            flows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/com_mtn_aggregator_models_response_ChangeOrResetPinResponse'
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "400"
                statusMessage: "Bad request. Invalid request parameters, missing required\
                  \ fields, or validation errors."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "401"
                statusMessage: "Unauthorized. Invalid or missing authorization credentials,\
                  \ insufficient permissions, or authentication failure."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "403":
          description: Forbidden. Access denied. The request is valid but the server
            refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "403"
                statusMessage: Forbidden. Access denied. The request is valid but
                  the server refuses to perform it.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "404"
                statusMessage: Not found. The requested resource was not found or
                  does not exist.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "500":
          description: "Internal server error. Unexpected system failure, database\
            \ connectivity issues, or external service integration problems."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "500"
                statusMessage: "Internal server error. Unexpected system failure,\
                  \ database connectivity issues, or external service integration\
                  \ problems."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "502":
          description: Bad gateway. The server acting as a gateway received an invalid
            response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "502"
                statusMessage: Bad gateway. The server acting as a gateway received
                  an invalid response from an upstream server.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "503":
          description: Service unavailable. The server is temporarily unable to handle
            the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "503"
                statusMessage: Service unavailable. The server is temporarily unable
                  to handle the request due to maintenance or overload.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
      deprecated: false
  /customer/{customerId}/pinProfile:
    get:
      tags:
      - customer Pin
      summary: To get Pin profile Details
      description: "To get Pin Details, user must enter the 'MSISDN/Service Number\
        \ of Customer'. User will enter Security Answer to be updated. Finally the\
        \ user will enter the 'channel id'"
      operationId: PinManagementService_get_getPinProfile_customercustomerIdpi
      parameters:
      - name: channel
        in: query
        required: true
        schema:
          type: string
      - name: countryCode
        in: header
        required: true
        schema:
          type: string
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: dapSystemVersion
        in: header
        required: true
        schema:
          type: string
      - name: operationType
        in: query
        required: true
        schema:
          type: string
      - name: targetSystem
        in: query
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: true
        schema:
          type: string
      responses:
        "200":
          description: HTTP 200 indicating the request succeeded; the response body
            follows the documented schema for this operation and includes correlation
            identifiers where applicable for traceability across MTN MADAPI Pin Management
            flows.
          content:
            application/json:
              schema:
                title: QueryProfileResponse
                type: object
                properties:
                  statusCode:
                    type: string
                  statusMessage:
                    type: string
                  transactionId:
                    type: string
                  sequenceNo:
                    type: string
                  supportMessage:
                    type: string
                  timestamp:
                    type: string
                  method:
                    type: string
                  path:
                    type: string
                  data:
                    title: QueryProfileResponseData
                    type: object
                    properties:
                      message:
                        type: string
                      alternateNumber:
                        type: string
                      securityQuestion:
                        type: string
                      emailID:
                        type: string
                      tncAccepted:
                        type: array
                        items:
                          title: ValidateTncAccepted
                          type: object
                          properties:
                            Version:
                              type: string
                            AcceptedDate:
                              type: string
                      firstLogin:
                        type: string
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "400"
                statusMessage: "Bad request. Invalid request parameters, missing required\
                  \ fields, or validation errors."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "401"
                statusMessage: "Unauthorized. Invalid or missing authorization credentials,\
                  \ insufficient permissions, or authentication failure."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "403":
          description: Forbidden. Access denied. The request is valid but the server
            refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "403"
                statusMessage: Forbidden. Access denied. The request is valid but
                  the server refuses to perform it.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "404"
                statusMessage: Not found. The requested resource was not found or
                  does not exist.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "500":
          description: "Internal server error. Unexpected system failure, database\
            \ connectivity issues, or external service integration problems."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "500"
                statusMessage: "Internal server error. Unexpected system failure,\
                  \ database connectivity issues, or external service integration\
                  \ problems."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "502":
          description: Bad gateway. The server acting as a gateway received an invalid
            response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "502"
                statusMessage: Bad gateway. The server acting as a gateway received
                  an invalid response from an upstream server.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "503":
          description: Service unavailable. The server is temporarily unable to handle
            the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "503"
                statusMessage: Service unavailable. The server is temporarily unable
                  to handle the request due to maintenance or overload.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
      deprecated: false
  /customer/{id}/pin:
    get:
      tags:
      - customer Pin
      summary: To validate Pin Details
      description: "To validate Pin Details, user must enter the MSISDN/Service Number\
        \ of Customer, the PIN number, channel id. Finally the user will enter the\
        \ Unique Trans ID as per below format yyyymmddhhmmss i.e 20200711123459104"
      operationId: PinManagementService_get_validateCustomerPin_customeridpin
      parameters:
      - name: channel
        in: header
        required: true
        schema:
          type: string
      - name: countryCode
        in: header
        required: false
        schema:
          type: string
      - name: dapSystemVersion
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: secret
        in: header
        required: true
        schema:
          type: string
      - name: targetSystem
        in: query
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      responses:
        "200":
          description: HTTP 200 indicating the request succeeded; the response body
            follows the documented schema for this operation and includes correlation
            identifiers where applicable for traceability across MTN MADAPI Pin Management
            flows.
          content:
            application/json:
              schema:
                title: ValidatePinResponse
                type: object
                properties:
                  statusCode:
                    type: string
                  statusMessage:
                    type: string
                  transactionId:
                    type: string
                  sequenceNo:
                    type: string
                  data:
                    title: ValidatePinResponseData
                    type: object
                    properties:
                      code:
                        type: string
                      desc:
                        type: string
                      forcePasswordChange:
                        type: boolean
                      securityQuestionAvailable:
                        type: string
                      emailID:
                        type: string
                      tncAccepted:
                        $ref: '#/components/schemas/com_mtn_aggregator_models_response_validate_ValidateTncAccepted'
                      tncLastUpdtdate:
                        type: string
                      tncLastUpdtversion:
                        type: string
                      serviceNumber:
                        type: string
                      serviceType:
                        type: string
                      error:
                        type: array
                        items:
                          title: PinErrorData
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            failedAttempts:
                              type: string
                            remainingAttempts:
                              type: string
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "400"
                statusMessage: "Bad request. Invalid request parameters, missing required\
                  \ fields, or validation errors."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "401"
                statusMessage: "Unauthorized. Invalid or missing authorization credentials,\
                  \ insufficient permissions, or authentication failure."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "403":
          description: Forbidden. Access denied. The request is valid but the server
            refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "403"
                statusMessage: Forbidden. Access denied. The request is valid but
                  the server refuses to perform it.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "404"
                statusMessage: Not found. The requested resource was not found or
                  does not exist.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "500":
          description: "Internal server error. Unexpected system failure, database\
            \ connectivity issues, or external service integration problems."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "500"
                statusMessage: "Internal server error. Unexpected system failure,\
                  \ database connectivity issues, or external service integration\
                  \ problems."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "502":
          description: Bad gateway. The server acting as a gateway received an invalid
            response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "502"
                statusMessage: Bad gateway. The server acting as a gateway received
                  an invalid response from an upstream server.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "503":
          description: Service unavailable. The server is temporarily unable to handle
            the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "503"
                statusMessage: Service unavailable. The server is temporarily unable
                  to handle the request due to maintenance or overload.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
      deprecated: false
components:
  schemas:
    com_mtn_aggregator_models_response_QueryProfileResponseData:
      title: QueryProfileResponseData
      type: object
      properties:
        message:
          type: string
        alternateNumber:
          type: string
        securityQuestion:
          type: string
        emailID:
          type: string
        tncAccepted:
          type: array
          items:
            title: ValidateTncAccepted
            type: object
            properties:
              Version:
                type: string
              AcceptedDate:
                type: string
        firstLogin:
          type: string
    com_mtn_aggregator_models_response_validate_ValidatePinResponseData:
      title: ValidatePinResponseData
      type: object
      properties:
        code:
          type: string
        desc:
          type: string
        forcePasswordChange:
          type: boolean
        securityQuestionAvailable:
          type: string
        emailID:
          type: string
        tncAccepted:
          $ref: '#/components/schemas/com_mtn_aggregator_models_response_validate_ValidateTncAccepted'
        tncLastUpdtdate:
          type: string
        tncLastUpdtversion:
          type: string
        serviceNumber:
          type: string
        serviceType:
          type: string
        error:
          type: array
          items:
            title: PinErrorData
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              failedAttempts:
                type: string
              remainingAttempts:
                type: string
    com_mtn_aggregator_models_response_ChangeOrResetPinResponse:
      title: ChangeOrResetPinResponse
      type: object
      properties:
        statusCode:
          type: string
        statusMessage:
          type: string
        transactionId:
          type: string
        sequenceNo:
          type: string
        error:
          title: APIError
          type: object
          properties:
            statusMessage:
              type: string
            supportMessage:
              type: string
            transactionId:
              type: string
            timestamp:
              type: string
            path:
              type: string
            method:
              type: string
            statusCode:
              type: string
            downstreamStatusCode:
              type: integer
              format: int32
            sequenceNo:
              type: string
        data:
          title: ChangePinCisResponse
          type: object
          properties:
            statusCode:
              type: string
            statusMessage:
              type: string
            transactionId:
              type: string
            supportMessage:
              type: string
            customerId:
              type: string
            data:
              title: ChangePinResponseData
              type: object
              properties:
                message:
                  type: string
                amountCharged:
                  title: Amount
                  type: object
                  properties:
                    value:
                      type: string
                    unit:
                      type: string
                success:
                  type: boolean
    com_mtn_aggregator_models_response_Amount:
      title: Amount
      type: object
      properties:
        value:
          type: string
        unit:
          type: string
    com_mtn_aggregator_models_response_ChangePinCisResponse:
      title: ChangePinCisResponse
      type: object
      properties:
        statusCode:
          type: string
        statusMessage:
          type: string
        transactionId:
          type: string
        supportMessage:
          type: string
        customerId:
          type: string
        data:
          title: ChangePinResponseData
          type: object
          properties:
            message:
              type: string
            amountCharged:
              title: Amount
              type: object
              properties:
                value:
                  type: string
                unit:
                  type: string
            success:
              type: boolean
    com_mtn_madapi_commons_models_error_APIError:
      title: APIError
      type: object
      properties:
        statusMessage:
          type: string
        supportMessage:
          type: string
        transactionId:
          type: string
        timestamp:
          type: string
        path:
          type: string
        method:
          type: string
        statusCode:
          type: string
        downstreamStatusCode:
          type: integer
          format: int32
        sequenceNo:
          type: string
    com_mtn_aggregator_models_response_ChangePinResponseData:
      title: ChangePinResponseData
      type: object
      properties:
        message:
          type: string
        amountCharged:
          title: Amount
          type: object
          properties:
            value:
              type: string
            unit:
              type: string
        success:
          type: boolean
    com_mtn_aggregator_models_response_CreatePinResponseData:
      title: CreatePinResponseData
      type: object
      properties:
        message:
          type: string
        code:
          type: string
        error:
          type: array
          items:
            title: Error
            type: object
            properties:
              message:
                type: string
              code:
                type: string
    com_mtn_aggregator_models_request_SecurityQuestionAnswer:
      title: SecurityQuestionAnswer
      type: object
      properties:
        securityQuestion:
          type: string
        securityAnswer:
          type: string
    com_mtn_aggregator_models_response_Error:
      title: Error
      type: object
      properties:
        message:
          type: string
        code:
          type: string
    com_mtn_aggregator_models_response_validate_PinErrorData:
      title: PinErrorData
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        failedAttempts:
          type: string
        remainingAttempts:
          type: string
    APIError:
      title: APIError
      required:
      - statusCode
      - statusMessage
      type: object
      properties:
        statusCode:
          type: string
          description: Error status code
        statusMessage:
          type: string
          description: Human-readable error message
        supportMessage:
          type: string
          description: Technical support message or error code for troubleshooting
        transactionId:
          type: string
          description: Transaction identifier for tracking and correlation
        sequenceNo:
          type: string
          description: Sequence number for request tracking
        timestamp:
          type: string
          description: Error timestamp in ISO 8601 format
          format: date-time
        path:
          type: string
          description: API endpoint path where the error occurred
        method:
          type: string
          description: HTTP method of the request that caused the error
        downstreamStatusCode:
          type: string
          description: Downstream service error code if applicable
      description: Generic MADAPI error response structure
    com_mtn_aggregator_models_response_ValidatePinResponse:
      title: ValidatePinResponse
      type: object
      properties:
        statusCode:
          type: string
        statusMessage:
          type: string
        transactionId:
          type: string
        sequenceNo:
          type: string
        data:
          title: ValidatePinResponseData
          type: object
          properties:
            code:
              type: string
            desc:
              type: string
            forcePasswordChange:
              type: boolean
            securityQuestionAvailable:
              type: string
            emailID:
              type: string
            tncAccepted:
              $ref: '#/components/schemas/com_mtn_aggregator_models_response_validate_ValidateTncAccepted'
            tncLastUpdtdate:
              type: string
            tncLastUpdtversion:
              type: string
            serviceNumber:
              type: string
            serviceType:
              type: string
            error:
              type: array
              items:
                title: PinErrorData
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  failedAttempts:
                    type: string
                  remainingAttempts:
                    type: string
    com_mtn_aggregator_models_request_SecurityQuestionAnswers:
      title: SecurityQuestionAnswers
      type: object
      properties:
        SecurityQuestionAnswer:
          title: SecurityQuestionAnswer
          type: object
          properties:
            securityQuestion:
              type: string
            securityAnswer:
              type: string
    com_mtn_aggregator_models_response_CreatePinResponse:
      title: CreatePinResponse
      type: object
      properties:
        statusCode:
          type: string
        statusMessage:
          type: string
        message:
          type: string
        transactionId:
          type: string
        customerId:
          type: string
        sequenceNo:
          type: string
        data:
          title: CreatePinResponseData
          type: object
          properties:
            message:
              type: string
            code:
              type: string
            error:
              type: array
              items:
                title: Error
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
    com_mtn_aggregator_models_response_QueryProfileResponse:
      title: QueryProfileResponse
      type: object
      properties:
        statusCode:
          type: string
        statusMessage:
          type: string
        transactionId:
          type: string
        sequenceNo:
          type: string
        supportMessage:
          type: string
        timestamp:
          type: string
        method:
          type: string
        path:
          type: string
        data:
          title: QueryProfileResponseData
          type: object
          properties:
            message:
              type: string
            alternateNumber:
              type: string
            securityQuestion:
              type: string
            emailID:
              type: string
            tncAccepted:
              type: array
              items:
                title: ValidateTncAccepted
                type: object
                properties:
                  Version:
                    type: string
                  AcceptedDate:
                    type: string
            firstLogin:
              type: string
    com_mtn_aggregator_models_response_validate_ValidateTncAccepted:
      title: ValidateTncAccepted
      type: object
      properties:
        Version:
          type: string
        AcceptedDate:
          type: string
  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