MTN KYC Consent

openapi: 3.0.1
info:
  title: Customer Kyc Consent
  description: "The Customer KYC Consent API facilitates the consent from the customer\
    \ while capturing and retrieval of Customer Information. This aggregator service\
    \ provides comprehensive Know Your Customer (KYC) consent management capabilities,\
    \ enabling secure customer data capture, consent validation, and information retrieval\
    \ operations across various channels and use cases."
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: "2.0"
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: Callback
- name: Kyc
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-15T12:00:00Z
                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-15T12:00:00Z
        "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-15T12:00:00Z
                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-15T12:00:00Z
        "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-15T12:00:00Z
                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-15T12:00:00Z
        "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-15T12:00:00Z
                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-15T12:00:00Z
        "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-15T12:00:00Z
                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-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:
                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-15T12:00:00Z
                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-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:
                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-15T12:00:00Z
                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-15T12:00:00Z
      deprecated: false
  /{customerId}:
    post:
      tags:
      - Kyc
      summary: Endpoint for KYC with Consent.
      description: "Endpoint for KYC with Consent - This endpoint initiate Kyc With\
        \ ConsentRequest. This accept customer id, channel, callback url, expiry time\
        \ and company name"
      operationId: Kyc_post_initiateKycWithConsentRequest_customerId
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: countryCode
        in: header
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: isConsentPreApproved
        in: header
        required: false
        schema:
          type: string
      - name: isMaskedResponse
        in: header
        required: false
        schema:
          type: string
      - name: partnerCallbackUrl
        in: header
        required: true
        schema:
          type: string
      - name: lob
        in: query
        required: false
        schema:
          type: string
      - name: idType
        in: query
        required: false
        schema:
          type: string
      - name: fields
        in: query
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: InitiateKycConsentRequest
              required:
              - chenosisCallbackUrl
              - companyName
              - message
              type: object
              properties:
                application:
                  type: string
                expireInMinutes:
                  type: string
                companyName:
                  type: string
                reqBody:
                  type: string
                channel:
                  type: string
                message:
                  type: string
                chenosisCallbackUrl:
                  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-15T12:00:00Z
                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-15T12:00:00Z
        "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-15T12:00:00Z
                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-15T12:00:00Z
        "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-15T12:00:00Z
                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-15T12:00:00Z
        "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-15T12:00:00Z
                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-15T12:00:00Z
        "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
                 

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