openapi: 3.0.1 info: title: Get PUK SingleView Aggregator description: "The Get PUK SingleView Aggregator service provides a unified interface\ \ for retrieving PUK (Personal Unblocking Key) information from various backend\ \ systems. This service streamlines the process of accessing PUK data, ensuring\ \ accuracy and efficiency for customer support and self-service portals. It aggregates\ \ data from multiple sources to present a comprehensive view of PUK details, enhancing\ \ the overall customer experience." license: name: MADAPI url: https://developers.mtn.com/ version: "1.0" servers: - url: https://api.mtn.com/v1 description: Production Server security: - OAuth2: [] tags: - name: GetPukAggregator paths: /customers/{customerId}/sim/simDetails: get: tags: - GetPukAggregator summary: Retrieves the PUK (Personal Unblocking Key) details for a specified customer. description: "This endpoint is designed to securely fetch and provide the PUK\ \ details associated with a given customer ID. It integrates with backend\ \ systems to ensure the accurate retrieval of unblocking keys, which are essential\ \ for restoring access to locked SIM cards." operationId: GetPukAggregator_get_aggregateGetPuk_customerscustomerIds parameters: - name: customerId in: path required: true schema: type: string - name: x-country-code in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string - name: targetSystem in: header required: false schema: type: string 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 /payments/payment-agreement/eligibility: get: tags: - GetPukAggregator summary: Checks the eligibility status for a payment agreement for a given billing account number. description: "This endpoint assesses whether a customer is eligible to enter\ \ into a payment agreement. It evaluates various financial and historical\ \ criteria associated with the provided billing account number to determine\ \ eligibility, facilitating flexible payment solutions." operationId: GetPukAggregator_get_aggregateGetEligibilty_paymentspaymentagree parameters: - name: billingAccountNumber in: query required: true schema: type: string - name: transactionId in: header required: false schema: type: string 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 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