openapi: 3.0.1 info: title: Transfer Aggregator Service description: API will enable MTN customers to transfer part of their active airtime or data to another MTN customer. This service excludes special data plans 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: CustomerTransferService paths: /customers/{senderMsisdn}: post: tags: - CustomerTransferService summary: Customers description: Customers will be able to transfer airtime or data to other MTN customers using both traditional and digital channel options available to them. operationId: CustomerTransferService_post_transfer_customerssenderMsisd parameters: - name: senderMsisdn in: path required: true schema: type: string - name: network in: query required: false schema: type: string - name: x-country-code 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: CustomerTransferRequest required: - receiverMsisdn - targetSystem - type type: object properties: additionalInformation: type: array items: title: AdditionalInformation type: object properties: name: type: string description: type: string agentId: type: string productId: type: integer format: int32 dstAccountType: type: integer format: int32 transferAmount: type: string type: type: string targetSystem: type: string paysrc: type: string productCode: type: string pin: type: string srcAccountType: type: integer format: int32 callbackUrl: type: string receiverMsisdn: type: string required: true responses: "200": description: Success content: application/json: schema: title: CustomerTransferResponse type: object properties: downstreamStatusCode: type: integer format: int32 sequenceNo: type: string data: title: CustomerTransferResponseData type: object properties: agentId: type: string productId: type: string localTransactionId: type: string description: type: string productName: type: string notification: type: string unit: type: string productCode: type: string accountBalances: type: array items: title: AccountBalance type: object properties: amount: title: Amount type: object properties: value: type: string currencyCode: type: string balanceType: type: string valueCharged: type: integer format: int64 customerId: type: string receiverMsisdn: type: string transactionState: type: string productType: type: string links: type: array items: title: Link type: object properties: template: title: UriTemplate type: object properties: template: type: string variables: title: TemplateVariables type: object properties: variables: type: array items: title: TemplateVariable type: object properties: name: type: string limit: type: integer format: int32 description: type: string type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string cardinality: title: Cardinality type: object baseUri: type: string groups: title: ExpandGroups type: object properties: groupList: type: array items: title: ExpandGroup type: object properties: variables: title: TemplateVariables type: object properties: variables: type: array items: title: TemplateVariable type: object properties: name: type: string limit: type: integer format: int32 description: type: string type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string cardinality: title: Cardinality type: object type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string affordances: type: array items: title: Affordance type: object properties: models: type: object additionalProperties: title: AffordanceModel type: object properties: output: title: PayloadMetadata type: object input: title: InputPayloadMetadata type: object queryMethodParameters: type: array items: title: QueryParameter type: object properties: name: type: string value: type: string required: type: boolean name: type: string link: title: Link type: object httpMethod: title: HttpMethod type: object properties: name: type: string hreflang: type: string profile: type: string rel: title: LinkRelation type: object name: type: string href: type: string media: type: string title: type: string type: type: string deprecation: type: string statusMessage: type: string transactionId: type: string statusCode: type: string supportMessage: type: string "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 /customers/transactionStatus: get: tags: - CustomerTransferService summary: Customers description: Provides the status of a Transaction and ensures that the state of the transaction is communicated to service providers. operationId: CustomerTransferService_get_transactionStatus_customerstransaction parameters: - name: transactionId in: query required: false schema: type: string - name: operation in: query required: false schema: type: string - name: network in: query required: false schema: type: string - name: x-country-code in: header required: false schema: type: string - name: targetSystem in: header required: false schema: type: string responses: "200": description: OK content: application/json: schema: title: CustomerTransferResponse type: object properties: downstreamStatusCode: type: integer format: int32 sequenceNo: type: string data: title: CustomerTransferResponseData type: object properties: agentId: type: string productId: type: string localTransactionId: type: string description: type: string productName: type: string notification: type: string unit: type: string productCode: type: string accountBalances: type: array items: title: AccountBalance type: object properties: amount: title: Amount type: object properties: value: type: string currencyCode: type: string balanceType: type: string valueCharged: type: integer format: int64 customerId: type: string receiverMsisdn: type: string transactionState: type: string productType: type: string links: type: array items: title: Link type: object properties: template: title: UriTemplate type: object properties: template: type: string variables: title: TemplateVariables type: object properties: variables: type: array items: title: TemplateVariable type: object properties: name: type: string limit: type: integer format: int32 description: type: string type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string cardinality: title: Cardinality type: object baseUri: type: string groups: title: ExpandGroups type: object properties: groupList: type: array items: title: ExpandGroup type: object properties: variables: title: TemplateVariables type: object properties: variables: type: array items: title: TemplateVariable type: object properties: name: type: string limit: type: integer format: int32 description: type: string type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string cardinality: title: Cardinality type: object type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string affordances: type: array items: title: Affordance type: object properties: models: type: object additionalProperties: title: AffordanceModel type: object properties: output: title: PayloadMetadata type: object input: title: InputPayloadMetadata type: object queryMethodParameters: type: array items: title: QueryParameter type: object properties: name: type: string value: type: string required: type: boolean name: type: string link: title: Link type: object httpMethod: title: HttpMethod type: object properties: name: type: string hreflang: type: string profile: type: string rel: title: LinkRelation type: object name: type: string href: type: string media: type: string title: type: string type: type: string deprecation: type: string statusMessage: type: string transactionId: type: string statusCode: type: string supportMessage: type: string "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 /notification: post: tags: - CustomerTransferService summary: a User Consent Response object description: The users consent information is posted here as a callback notification once the consent action has been completed. operationId: CustomerTransferService_post_handleConsentNotification_notification parameters: - name: x-country-code 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: ConsentNotificationResponse type: object properties: sequenceNo: type: string partnerName: type: string customData: type: array items: type: string links: type: array items: title: Link type: object properties: template: title: UriTemplate type: object properties: template: type: string variables: title: TemplateVariables type: object properties: variables: type: array items: title: TemplateVariable type: object properties: name: type: string limit: type: integer format: int32 description: type: string type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string cardinality: title: Cardinality type: object baseUri: type: string groups: title: ExpandGroups type: object properties: groupList: type: array items: title: ExpandGroup type: object properties: variables: title: TemplateVariables type: object properties: variables: type: array items: title: TemplateVariable type: object properties: name: type: string limit: type: integer format: int32 description: type: string type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string cardinality: title: Cardinality type: object type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string affordances: type: array items: title: Affordance type: object properties: models: type: object additionalProperties: title: AffordanceModel type: object properties: output: title: PayloadMetadata type: object input: title: InputPayloadMetadata type: object queryMethodParameters: type: array items: title: QueryParameter type: object properties: name: type: string value: type: string required: type: boolean name: type: string link: title: Link type: object httpMethod: title: HttpMethod type: object properties: name: type: string hreflang: type: string profile: type: string rel: title: LinkRelation type: object name: type: string href: type: string media: type: string title: type: string type: type: string deprecation: type: string msisdn: type: string userResponse: type: string transactionId: type: string statusCode: type: string required: true responses: "201": description: Created content: application/json: schema: title: ConsentNotificationResponse type: object properties: sequenceNo: type: string partnerName: type: string customData: type: array items: type: string links: type: array items: title: Link type: object properties: template: title: UriTemplate type: object properties: template: type: string variables: title: TemplateVariables type: object properties: variables: type: array items: title: TemplateVariable type: object properties: name: type: string limit: type: integer format: int32 description: type: string type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string cardinality: title: Cardinality type: object baseUri: type: string groups: title: ExpandGroups type: object properties: groupList: type: array items: title: ExpandGroup type: object properties: variables: title: TemplateVariables type: object properties: variables: type: array items: title: TemplateVariable type: object properties: name: type: string limit: type: integer format: int32 description: type: string type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string cardinality: title: Cardinality type: object type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string affordances: type: array items: title: Affordance type: object properties: models: type: object additionalProperties: title: AffordanceModel type: object properties: output: title: PayloadMetadata type: object input: title: InputPayloadMetadata type: object queryMethodParameters: type: array items: title: QueryParameter type: object properties: name: type: string value: type: string required: type: boolean name: type: string link: title: Link type: object httpMethod: title: HttpMethod type: object properties: name: type: string hreflang: type: string profile: type: string rel: title: LinkRelation type: object name: type: string href: type: string media: type: string title: type: string type: type: string deprecation: type: string msisdn: type: string userResponse: type: string transactionId: type: string statusCode: type: string "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