openapi: 3.0.1 info: title: Customer Consent Validation description: "The Consent Validation API provides comprehensive consent management\ \ and validation services for customer consent operations. This service enables\ \ validation of customer consent for various operations including payment transactions,\ \ service subscriptions, and data processing activities. It supports multiple\ \ consent flow types including API consent, traditional channel consent validation,\ \ and monetization consent services." license: name: MADAPI url: https://developers.mtn.com/ version: 3.0.0 - Last updated date:2026-08-20 07:56:06 servers: - url: https://api.mtn.com/v1 description: Production Server security: - OAuth2: [] tags: - name: ConsentValidation paths: /cancelPreapproval: post: tags: - ConsentValidation summary: Cancel one or more customer preapproval records description: "Cancels existing customer preapproval agreements by resolving\ \ the target system, submitting cancellation details, logging request and\ \ response payloads, and ensuring canonical error handling for any unsuccessful\ \ downstream interaction." operationId: ConsentValidationService_post_cancelPreapproval parameters: - name: transactionId in: header required: true schema: type: string - name: x-authorization in: header required: false schema: type: string - name: x-country-code in: header required: true schema: type: string - name: x-origin-channelid in: header required: false schema: type: string - name: x-target-system in: header required: false schema: type: string requestBody: content: application/json: schema: title: CancelPreapprovalRequest type: object properties: preapprovalId: type: string customerId: type: string accountHolderId: type: string callbackUrl: type: string referenceId: type: string approvalId: type: string requestMsisdn: type: string forProduct: type: string transactionId: type: string filter: 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 customer consent validation flows. content: application/json: schema: title: CancelPreapprovalResponse type: object properties: statusCode: type: string transactionId: type: string sequenceNo: type: string statusMessage: type: string success: type: boolean code: type: integer format: int32 message: type: string data: title: CancelPreapprovalResponseData type: object properties: cancellationStatus: type: string cancellationId: type: string referenceId: type: string requestMsisdn: type: string approvalForMsisdn: type: string message: type: string duration: type: integer format: int32 callbackUrl: type: string channel: type: string product: type: integer format: int64 "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 /consent/{customerId}/generateotp: post: tags: - ConsentValidation summary: Generate consent OTP for linked identifiers description: "Generates one-time passwords across all customer identifiers by\ \ validating input attributes, deriving country-specific endpoints, logging\ \ enriched request data, and orchestrating downstream consent services for\ \ compliant OTP distribution." operationId: ConsentValidationService_post_handleCustomerRegistration_consentcustomerIdgen parameters: - name: customerId in: path required: true schema: type: string - name: language in: query required: false schema: type: string - name: message 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: x-authorization in: header required: true schema: type: string - name: x-authorization-claims in: header required: true schema: type: string - name: x-channel-id in: header required: false schema: type: string - name: x-country-code in: header required: false schema: type: string - name: x-origin-channelid in: header required: false schema: type: string requestBody: content: application/json: schema: title: CustomerIdentificationRequest type: object properties: IdNumber: type: string notificationChannel: type: string notifyUser: type: string idType: type: string segment: type: string header: type: string channel: title: Channel type: object properties: name: type: string pinLength: type: string timeToLive: 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 customer consent validation flows. content: application/json: schema: title: OtpGenerateResponse type: object properties: statusCode: type: string status: type: string statusMessage: type: string transactionId: type: string sequenceNo: type: string customerId: type: string data: title: OtpGenerateData type: object properties: IdNumber: type: string servicesCount: type: string otpKey: type: string otp: type: string language: type: string supportMessage: type: string timestamp: type: string method: type: string path: 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 /consent/{customerId}/verifyotp: post: tags: - ConsentValidation summary: Verify a consent OTP for a customer identifier description: "Verifies customer OTP submissions by enforcing mandatory parameters,\ \ validating MSISDN formats, resolving country-specific endpoints, invoking\ \ downstream verification services, and returning canonical status codes for\ \ clients." operationId: ConsentValidationService_post_verifyOtp_consentcustomerIdver parameters: - name: customerId in: path required: true schema: type: string - name: language in: query required: false schema: type: string - name: otp in: query required: false schema: type: string - name: otpKey in: query required: false schema: type: string - name: transactionId in: header required: true schema: type: string - name: x-channel-id in: header required: false schema: type: string - name: x-country-code in: header required: false schema: type: string - name: x-origin-channelid in: header required: true schema: type: string requestBody: content: application/json: schema: 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 customer consent validation flows. content: application/json: schema: title: OtpVerifyResponse type: object properties: statusCode: type: string status: type: string message: type: string customerId: type: string data: title: OtpVerifyResponseData type: object properties: otpKey: type: string verified: type: boolean language: type: string expiryDate: type: string timestamp: type: string statusMessage: type: string path: type: string transactionId: type: string sequenceNo: type: string supportMessage: type: string method: 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 /consent/{msisdn}: get: tags: - ConsentValidation summary: Retrieve customer profile data with consent verification description: "Retrieves a partner-authorized customer profile by validating\ \ consent parameters, selecting the monetization system endpoint, logging\ \ the transaction context, and returning canonical responses that reflect\ \ downstream success or error conditions." operationId: ConsentValidationService_get_customerConsentManager_consentmsisdn parameters: - name: consentType in: query required: true schema: type: string - name: msisdn in: path required: true schema: type: string - name: partnerClientId in: header required: false schema: type: string - name: reason in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string - name: x-country-code in: header 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 customer consent validation flows. content: application/json: schema: title: CustomerProfileResponse type: object properties: statusCode: type: string callbackUrl: type: string statusMessage: type: string sequenceNo: type: string transactionId: type: string data: title: CustomerProfile type: object properties: firstName: type: string middleName: type: string lastName: type: string nationality: type: string phoneNumber: type: string email: type: string city: type: string StreetAddress: type: string postalCode: type: string motherMaidenName: type: string dateOfBirth: type: string gender: type: string alternativePhoneNumber: type: string registrationDate: type: string stateOfOrigin: type: string ninStatus: 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 post: tags: - ConsentValidation summary: Validate subscriber consent across monetization and consent services description: "Validates subscriber consent for API and traditional channel flows,\ \ selecting a downstream system, logging transaction metadata, enriching sequence\ \ identifiers, and returning a canonical consent response aligned with channel\ \ requirements." operationId: ConsentValidationService_post_validateConsent_consentmsisdn parameters: - name: msisdn in: path required: true schema: type: string - name: sequenceNo in: header required: false schema: type: string - name: targetSystem in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string - name: x-origin-channelid in: header required: false schema: type: string requestBody: content: application/json: schema: title: ConsentRequest type: object properties: smsShortCode: type: string ussdShortCode: type: string flowType: type: string confirmationMessage: type: string customData: type: array items: type: string callbackUrl: type: string relatedParty: type: array items: title: RelatedParty type: object properties: id: type: string value: 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 customer consent validation flows. content: application/json: schema: title: ConsentValidationResponse type: object properties: statusCode: type: string customerId: type: string data: title: ConsentValidationData type: object properties: sent: type: boolean callbackUrl: type: string status: type: string sequenceNo: type: string transactionId: type: string supportMessage: type: string statusMessage: type: string timestamp: 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 /preapproval: post: tags: - ConsentValidation summary: Create a customer preapproval request description: "Creates customer preapproval instructions by resolving the correct\ \ downstream system, adjusting callback metadata, logging the transaction\ \ lifecycle, and registering callbacks so future debit transactions remain\ \ synchronized across parties." operationId: ConsentValidationService_post_preapproval parameters: - name: transactionId in: header required: true schema: type: string - name: x-authorization in: header required: false schema: type: string - name: x-country-code in: header required: true schema: type: string - name: x-origin-channelid in: header required: false schema: type: string - name: x-target-system in: header required: false schema: type: string requestBody: content: application/json: schema: title: PreapprovalRequest type: object properties: fromCustomerId: type: string toCustomerId: type: string fromCurrency: type: string toCurrency: type: string message: type: string duration: type: string callbackUrl: type: string referenceId: type: string requestMsisdn: type: string approvalForMsisdn: type: string channel: type: string product: type: integer format: int64 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 customer consent validation flows. content: application/json: schema: title: PreapprovalResponse type: object properties: statusCode: type: string preapprovalId: type: string sequenceNo: type: string statusMessage: type: string success: type: boolean code: type: integer format: int32 message: type: string data: title: PreapprovalResponseData type: object properties: preapprovalStatus: type: string expiryTime: type: string approvalId: type: string referenceId: type: string existingPreapproval: type: boolean requestMsisdn: type: string approvalForMsisdn: type: string message: type: string duration: type: integer format: int32 callbackUrl: type: string channel: type: string product: type: integer format: int64 "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 /preapprovalStatus: post: tags: - ConsentValidation summary: Check ACS preapproval status for a customer description: "Checks preapproval status within ACS-backed markets by routing\ \ to the correct system endpoint, logging the aggregated request details,\ \ augmenting responses with sequence numbers, and mapping downstream outcomes\ \ to canonical HTTP responses." operationId: ConsentValidationService_post_preapprovalStatus parameters: - name: x-authorization in: header required: false schema: type: string - name: x-country-code in: header required: true schema: type: string requestBody: content: application/json: schema: title: PreapprovalStatusRequest type: object properties: preApprovalId: type: string fromCustomerId: type: string toCustomerId: type: string fromCurrency: type: string transactionId: type: string xCountryCode: type: string xAuthorization: type: string requestMsisdn: type: string callbackUrl: type: string referenceId: type: string approvalId: type: string forProduct: type: string filter: 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 customer consent validation flows. content: application/json: schema: $ref: '#/components/schemas/com_mtn_aggregator_models_response_PreapprovalStatusResponse' "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 /preapprovalStatus/{preApprovalId}: get: tags: - ConsentValidation summary: Retrieve preapproval status by identifier description: "Retrieves the latest preapproval status for a customer by locating\ \ the correct downstream system, logging the request context, enriching the\ \ response with HATEOAS metadata, and mapping canonical status codes to HTTP\ \ responses." operationId: ConsentValidationService_get_getPreapprovalStatus_preapprovalStatuspre parameters: - name: fromCurrency in: query required: false schema: type: string - name: fromCustomerId in: query required: true schema: type: string - name: preApprovalId in: path required: true schema: type: string - name: toCustomerId in: query required: true schema: type: string - name: transactionId in: header required: true schema: type: string - name: x-authorization in: header required: false schema: type: string - name: x-country-code in: header required: true 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 customer consent validation flows. content: application/json: schema: title: PreapprovalStatusResponse type: object properties: statusCode: type: string transactionId: type: string preapprovalStatus: type: string sequenceNo: type: string statusMessage: type: string success: type: boolean code: type: integer format: int32 message: type: string data: title: PreapprovalStatusResponseData type: object properties: requestMsisdn: type: string approvalForMsisdn: type: string message: type: string duration: type: integer format: int32 referenceId: type: string callbackUrl: type: string channel: type: string product: type: integer format: int64 "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_CancelPreapprovalResponse: title: CancelPreapprovalResponse type: object properties: statusCode: type: string transactionId: type: string sequenceNo: type: string statusMessage: type: string success: type: boolean code: type: integer format: int32 message: type: string data: title: CancelPreapprovalResponseData type: object properties: cancellationStatus: type: string cancellationId: type: string referenceId: type: string requestMsisdn: type: string approvalForMsisdn: type: string message: type: string duration: type: integer format: int32 callbackUrl: type: string channel: type: string product: type: integer format: int64 com_mtn_aggregator_models_response_PreapprovalStatusResponseData: title: PreapprovalStatusResponseData type: object properties: requestMsisdn: type: string approvalForMsisdn: type: string message: type: string duration: type: integer format: int32 referenceId: type: string callbackUrl: type: string channel: type: string product: type: integer format: int64 com_mtn_aggregator_models_response_CustomerProfile: title: CustomerProfile type: object properties: firstName: type: string middleName: type: string lastName: type: string nationality: type: string phoneNumber: type: string email: type: string city: type: string StreetAddress: type: string postalCode: type: string motherMaidenName: type: string dateOfBirth: type: string gender: type: string alternativePhoneNumber: type: string registrationDate: type: string stateOfOrigin: type: string ninStatus: type: string com_mtn_aggregator_models_response_PreapprovalResponseData: title: PreapprovalResponseData type: object properties: preapprovalStatus: type: string expiryTime: type: string approvalId: type: string referenceId: type: string existingPreapproval: type: boolean requestMsisdn: type: string approvalForMsisdn: type: string message: type: string duration: type: integer format: int32 callbackUrl: type: string channel: type: string product: type: integer format: int64 com_mtn_aggregator_models_response_PreapprovalResponse: title: PreapprovalResponse type: object properties: statusCode: type: string preapprovalId: type: string sequenceNo: type: string statusMessage: type: string success: type: boolean code: type: integer format: int32 message: type: string data: title: PreapprovalResponseData type: object properties: preapprovalStatus: type: string expiryTime: type: string approvalId: type: string referenceId: type: string existingPreapproval: type: boolean requestMsisdn: type: string approvalForMsisdn: type: string message: type: string duration: type: integer format: int32 callbackUrl: type: string channel: type: string product: type: integer format: int64 com_mtn_aggregator_models_request_CustomerIdentificationRequest: title: CustomerIdentificationRequest type: object properties: IdNumber: type: string notificationChannel: type: string notifyUser: type: string idType: type: string segment: type: string header: type: string channel: title: Channel type: object properties: name: type: string pinLength: type: string timeToLive: type: string com_mtn_aggregator_models_response_ConsentValidationResponse: title: ConsentValidationResponse type: object properties: statusCode: type: string customerId: type: string data: title: ConsentValidationData type: object properties: sent: type: boolean callbackUrl: type: string status: type: string sequenceNo: type: string transactionId: type: string supportMessage: type: string statusMessage: type: string timestamp: type: string com_mtn_aggregator_models_response_OtpVerifyResponse: title: OtpVerifyResponse type: object properties: statusCode: type: string status: type: string message: type: string customerId: type: string data: title: OtpVerifyResponseData type: object properties: otpKey: type: string verified: type: boolean language: type: string expiryDate: type: string timestamp: type: string statusMessage: type: string path: type: string transactionId: type: string sequenceNo: type: string supportMessage: type: string method: type: string com_mtn_aggregator_models_request_ConsentRequest: title: ConsentRequest type: object properties: smsShortCode: type: string ussdShortCode: type: string flowType: type: string confirmationMessage: type: string customData: type: array items: type: string callbackUrl: type: string relatedParty: type: array items: title: RelatedParty type: object properties: id: type: string value: type: string com_mtn_aggregator_models_request_Channel: title: Channel type: object properties: name: type: string com_mtn_aggregator_models_response_CustomerProfileResponse: title: CustomerProfileResponse type: object properties: statusCode: type: string callbackUrl: type: string statusMessage: type: string sequenceNo: type: string transactionId: type: string data: title: CustomerProfile type: object properties: firstName: type: string middleName: type: string lastName: type: string nationality: type: string phoneNumber: type: string email: type: string city: type: string StreetAddress: type: string postalCode: type: string motherMaidenName: type: string dateOfBirth: type: string gender: type: string alternativePhoneNumber: type: string registrationDate: type: string stateOfOrigin: type: string ninStatus: type: string com_mtn_aggregator_models_request_PreapprovalStatusRequest: title: PreapprovalStatusRequest type: object properties: preApprovalId: type: string fromCustomerId: type: string toCustomerId: type: string fromCurrency: type: string transactionId: type: string xCountryCode: type: string xAuthorization: type: string requestMsisdn: type: string callbackUrl: type: string referenceId: type: string approvalId: type: string forProduct: type: string filter: type: string com_mtn_aggregator_models_response_CancelPreapprovalResponseData: title: CancelPreapprovalResponseData type: object properties: cancellationStatus: type: string cancellationId: type: string referenceId: type: string requestMsisdn: type: string approvalForMsisdn: type: string message: type: string duration: type: integer format: int32 callbackUrl: type: string channel: type: string product: type: integer format: int64 com_mtn_aggregator_models_response_PreapprovalStatusResponse: title: PreapprovalStatusResponse type: object properties: statusCode: type: string transactionId: type: string preapprovalStatus: type: string sequenceNo: type: string statusMessage: type: string success: type: boolean code: type: integer format: int32 message: type: string data: title: PreapprovalStatusResponseData type: object properties: requestMsisdn: type: string approvalForMsisdn: type: string message: type: string duration: type: integer format: int32 referenceId: type: string callbackUrl: type: string channel: type: string product: type: integer format: int64 com_mtn_aggregator_models_request_PreapprovalRequest: title: PreapprovalRequest type: object properties: fromCustomerId: type: string toCustomerId: type: string fromCurrency: type: string toCurrency: type: string message: type: string duration: type: string callbackUrl: type: string referenceId: type: string requestMsisdn: type: string approvalForMsisdn: type: string channel: type: string product: type: integer format: int64 com_mtn_aggregator_models_response_OtpVerifyResponseData: title: OtpVerifyResponseData type: object properties: otpKey: type: string verified: type: boolean language: type: string expiryDate: type: string com_mtn_aggregator_models_request_CancelPreapprovalRequest: title: CancelPreapprovalRequest type: object properties: preapprovalId: type: string customerId: type: string accountHolderId: type: string callbackUrl: type: string referenceId: type: string approvalId: type: string requestMsisdn: type: string forProduct: type: string transactionId: type: string filter: type: string com_mtn_aggregator_models_request_RelatedParty: title: RelatedParty type: object properties: id: type: string value: type: string com_mtn_aggregator_models_response_ConsentValidationData: title: ConsentValidationData type: object properties: sent: type: boolean callbackUrl: type: string status: 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_OtpGenerateResponse: title: OtpGenerateResponse type: object properties: statusCode: type: string status: type: string statusMessage: type: string transactionId: type: string sequenceNo: type: string customerId: type: string data: title: OtpGenerateData type: object properties: IdNumber: type: string servicesCount: type: string otpKey: type: string otp: type: string language: type: string supportMessage: type: string timestamp: type: string method: type: string path: type: string com_mtn_aggregator_models_response_OtpGenerateData: title: OtpGenerateData type: object properties: IdNumber: type: string servicesCount: type: string otpKey: type: string otp: type: string language: 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