openapi: 3.2.0 info: title: Customer Consent Kyc API 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: Kyc paths: /{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-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 /consents: post: tags: - Kyc summary: Consent By MSIDN - Customer id description: 'Customer KYC Consent Endpoint : - This endpoint fetch the consent details by customer id and msidn. This required msidn, country code and other details' operationId: Kyc_post_getConsentByMsisdn_consents parameters: - name: countryCode in: header required: true schema: type: string - name: transactionId in: header required: false schema: type: string requestBody: content: application/json: schema: title: FetchConsentRequest type: object properties: 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 components: 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