openapi: 3.2.0 info: title: TMF676 Payment Management Aggregator API description: TMF676 Payment Management Aggregator API provides comprehensive payment management capabilities following TM Forum TMF676 standards. This service enables payment processing, payment method management, payment status tracking, and payment reconciliation operations. It serves as the central aggregator for all payment-related operations, integrating with various payment systems and providers across the MTN ecosystem. license: name: MADAPI url: https://developers.mtn.com/ version: 3.0.0 servers: - url: https://api.mtn.com/v1 description: Production Server security: - OAuth2: [] tags: - name: TMF676 Payment Management Aggregator paths: /payment: get: tags: - TMF676 Payment Management Aggregator summary: Retrieve OTT tax status details description: Fetches the OTT tax status details for a specific customer from the configured CIS system, forwarding the request to downstream services while preserving the optional transaction identifier. operationId: TMF676PaymentManagementAggregatorService_get_getOTTStatus_payment parameters: - name: ottTaxStatus in: query required: true schema: type: string - name: customerId in: query required: true schema: type: string - name: clientTransactionId in: header required: false schema: type: string responses: '200': description: Success '400': description: Bad request. Invalid request parameters, missing required fields, or validation errors. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Bad request. Invalid request parameters, missing required fields, or validation errors. transactionId: '1234567890' statusCode: '400' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '401': description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure. transactionId: '1234567890' statusCode: '401' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '403': description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: '1234567890' statusCode: '403' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '404': description: Not found. The requested resource was not found or does not exist. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Not found. The requested resource was not found or does not exist. transactionId: '1234567890' statusCode: '404' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '500': description: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems. transactionId: '1234567890' statusCode: '500' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '502': description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: '1234567890' statusCode: '502' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '503': description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: '1234567890' statusCode: '503' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 deprecated: false post: tags: - TMF676 Payment Management Aggregator summary: Process customer payment via MoMo description: Initiates a customer payment using MTN MoMo channels, generating or reusing a transaction reference, logging the full request payload, and delegating downstream payment execution with comprehensive response auditing. operationId: TMF676PaymentManagementAggregatorService_post_payViaMomo_payment parameters: - name: transactionId in: header required: false schema: type: string - name: countryCode in: header required: false schema: type: string requestBody: content: application/json: schema: title: Payment type: object properties: statusDate: type: string reason: type: string amount: title: Amount type: object properties: unit: type: string amount: type: integer format: int32 units: type: string value: type: integer format: int32 code: type: string authorizationCode: type: string '@type': type: string channel: title: Channel type: object properties: '@referredType': type: string role: type: string '@baseType': type: string '@type': type: string name: type: string id: type: string href: type: string '@schemaLocation': type: string description: type: string message: type: string referenceError: type: string payer: title: Account type: object properties: '@referredType': type: string entityLevel: type: string role: type: string '@baseType': type: string '@type': type: string name: type: string description: type: string id: type: string href: type: string '@schemaLocation': type: string totalAmount: title: Amount type: object properties: unit: type: string amount: type: integer format: int32 units: type: string value: type: integer format: int32 paymentItem: type: array items: title: PaymentItem type: object properties: totalAmount: title: Amount type: object properties: unit: type: string amount: type: integer format: int32 units: type: string value: type: integer format: int32 amount: title: Amount type: object properties: unit: type: string amount: type: integer format: int32 units: type: string value: type: integer format: int32 item: title: Item type: object properties: request: title: Request type: object properties: '@referredType': type: string '@baseType': type: string id: type: string href: type: string '@schemaLocation': type: string '@referredType': type: string orderItem: type: array items: title: OrderItem type: object properties: productSpecification: title: ProductSpecification type: object properties: '@referredType': type: string '@baseType': type: string '@type': type: string name: type: string id: type: string href: type: string technology: type: array items: type: string '@schemaLocation': type: string version: type: string product: title: Product type: object properties: productSpecification: title: ProductSpecification type: object properties: '@referredType': type: string '@baseType': type: string '@type': type: string name: type: string id: type: string href: type: string technology: type: array items: type: string '@schemaLocation': type: string version: type: string xDir: type: string '@referredType': type: string customFields: title: CustomFields type: object properties: registrationType: type: string productOrderGroup: type: array items: type: string moMoFlag: type: boolean assignType: type: string '@type': type: string channel: type: array items: title: Channel type: object properties: '@referredType': type: string role: type: string '@baseType': type: string '@type': type: string name: type: string id: type: string href: type: string '@schemaLocation': type: string productOrder: type: array items: title: ProductOrder type: object properties: '@referredType': type: string orderItemActionSubType: type: string orderItemId: type: string id: type: string href: type: string '@schemaLocation': type: string orderItemAction: type: string isPrimaryMSISDN: type: boolean '@baseType': type: string id: type: string href: type: string place: type: array items: title: Place type: object properties: role: type: string '@type': type: string '@schemaLocation': type: string publicIdentifier: type: string simNumber: type: string productOffering: title: ProductOffering type: object properties: code: type: string '@type': type: string name: type: string id: type: string href: type: string '@schemaLocation': type: string category: type: array items: title: Category type: object properties: '@referredType': type: string name: type: string id: type: string href: type: string '@schemaLocation': type: string version: type: string externalSystem: type: array items: title: ExternalSystem type: object properties: system: type: string '@baseType': type: string '@type': type: string id: type: string suspensions: type: array items: title: Suspension type: object properties: reason: type: string interactionDate: title: InteractionDate type: object properties: startDateTime: type: string format: date-time endDateTime: type: string format: date-time suspensionType: type: string id: type: string technology: type: string relatedParty: type: array items: title: RelatedParty type: object properties: '@referredType': type: string role: type: string '@baseType': type: string '@type': type: string name: type: string id: type: string href: type: string '@schemaLocation': type: string engagedParty: title: EngagedParty type: object properties: '@referredType': type: string id: type: string href: type: string '@schemaLocation': type: string productTerm: type: array items: title: ProductTerm type: object properties: validFor: title: ValidFor type: object properties: startDateTime: type: string format: date-time endDateTime: type: string format: date-time '@type': type: string description: type: string status: type: string externalSystem: type: array items: title: ExternalSystem type: object properties: system: type: string '@baseType': type: string '@type': type: string id: type: string createdDate: type: string format: date-time imsiNumber: type: string name: type: string modifiedDate: type: string format: date-time productRelationship: type: array items: title: ProductRelationship type: object properties: product: title: Product type: object relationshipType: type: string type: type: string businessType: type: string activationDate: type: string format: date-time isCustomerVisible: type: boolean startDate: type: string format: date-time productPrice: type: array items: title: ProductPrice type: object properties: price: title: Price type: object properties: taxRate: type: integer format: int32 tax: type: array items: title: Tax type: object properties: unit: type: string value: type: integer format: int32 taxIncludedAmount: title: TaxIncludedAmount type: object properties: unit: type: string value: type: string dutyFreeAmount: title: DutyFreeAmount type: object properties: unit: type: string value: type: string name: type: string priceType: type: string description: type: string productOfferingPrice: type: array items: title: ProductOfferingPrice type: object properties: name: type: string id: type: string href: type: string '@schemaLocation': type: string href: type: string recurringChargePeriod: type: string '@schemaLocation': type: string LoB: type: string status: type: string productOffering: title: ProductOffering type: object properties: code: type: string '@type': type: string name: type: string id: type: string href: type: string '@schemaLocation': type: string category: type: array items: title: Category type: object properties: '@referredType': type: string name: type: string id: type: string href: type: string '@schemaLocation': type: string version: type: string externalSystem: type: array items: title: ExternalSystem type: object properties: system: type: string '@baseType': type: string '@type': type: string id: type: string action: type: string id: type: string href: type: string actionSubType: type: string modifiable: type: boolean '@schemaLocation': type: string customFields: title: CustomFields type: object properties: registrationType: type: string productOrderGroup: type: array items: type: string moMoFlag: type: boolean assignType: type: string '@type': type: string channel: type: array items: title: Channel type: object properties: '@referredType': type: string role: type: string '@baseType': type: string '@type': type: string name: type: string id: type: string href: type: string '@schemaLocation': type: string relatedParty: type: array items: title: RelatedParty type: object properties: '@referredType': type: string role: type: string '@baseType': type: string '@type': type: string name: type: string id: type: string href: type: string '@schemaLocation': type: string engagedParty: title: EngagedParty type: object properties: '@referredType': type: string id: type: string href: type: string '@schemaLocation': type: string cancellable: type: boolean requestedStartDate: type: string format: date-time externalSystem: type: array items: title: ExternalSystem type: object properties: system: type: string '@baseType': type: string '@type': type: string id: type: string createdDate: type: string format: date-time '@baseType': type: string modifiedDate: type: string format: date-time name: type: string id: type: string href: type: string state: type: string '@schemaLocation': type: string modifiable: type: boolean orderDate: type: string format: date-time '@baseType': type: string '@type': type: string id: type: string taxAmount: title: Amount type: object properties: unit: type: string amount: type: integer format: int32 units: type: string value: type: integer format: int32 '@schemaLocation': type: string '@baseType': type: string name: type: string paymentMethod: title: PaymentMethod type: object properties: statusDate: type: string '@referredType': type: string validFor: title: ValidFor type: object properties: startDateTime: type: string format: date-time endDateTime: type: string format: date-time '@type': type: string description: type: string isPreferred: type: boolean relatedParty: title: RelatedParty type: object properties: '@referredType': type: string role: type: string '@baseType': type: string '@type': type: string name: type: string id: type: string href: type: string '@schemaLocation': type: string engagedParty: title: EngagedParty type: object properties: '@referredType': type: string id: type: string href: type: string '@schemaLocation': type: string '@baseType': type: string name: type: string details: title: Details type: object properties: reference: type: string mobileNumber: type: string id: type: string href: type: string '@schemaLocation': type: string account: type: array items: title: Account type: object properties: '@referredType': type: string entityLevel: type: string role: type: string '@baseType': type: string '@type': type: string name: type: string description: type: string id: type: string href: type: string '@schemaLocation': type: string preferred: type: boolean status: type: string correlatorId: type: string id: type: string href: type: string paymentDate: type: string taxAmount: title: Amount type: object properties: unit: type: string amount: type: integer format: int32 units: type: string value: type: integer format: int32 '@schemaLocation': type: string account: title: Account type: object properties: '@referredType': type: string entityLevel: type: string role: type: string '@baseType': type: string '@type': type: string name: type: string description: type: string id: type: string href: type: string '@schemaLocation': type: string status: type: string required: true responses: '200': description: Success '400': description: Bad request. Invalid request parameters, missing required fields, or validation errors. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Bad request. Invalid request parameters, missing required fields, or validation errors. transactionId: '1234567890' statusCode: '400' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '401': description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure. transactionId: '1234567890' statusCode: '401' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '403': description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: '1234567890' statusCode: '403' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '404': description: Not found. The requested resource was not found or does not exist. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Not found. The requested resource was not found or does not exist. transactionId: '1234567890' statusCode: '404' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '500': description: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems. transactionId: '1234567890' statusCode: '500' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '502': description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: '1234567890' statusCode: '502' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '503': description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: '1234567890' statusCode: '503' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 deprecated: false /payment/{id}: get: tags: - TMF676 Payment Management Aggregator summary: Get transaction details by identifier description: Retrieves detailed information for a specific payment transaction, invoking downstream services with a generated correlation identifier and capturing the full service response for auditability and traceability. operationId: TMF676PaymentManagementAggregatorService_get_getTransactionDetails_paymentid parameters: - name: id in: path required: true schema: type: string - name: transactionId in: header required: false schema: type: string - name: requestType in: query required: false schema: type: string - name: countryCode in: header required: false schema: type: string responses: '200': description: Success '400': description: Bad request. Invalid request parameters, missing required fields, or validation errors. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Bad request. Invalid request parameters, missing required fields, or validation errors. transactionId: '1234567890' statusCode: '400' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '401': description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure. transactionId: '1234567890' statusCode: '401' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '403': description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: '1234567890' statusCode: '403' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '404': description: Not found. The requested resource was not found or does not exist. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Not found. The requested resource was not found or does not exist. transactionId: '1234567890' statusCode: '404' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '500': description: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems. transactionId: '1234567890' statusCode: '500' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '502': description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: '1234567890' statusCode: '502' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '503': description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: '1234567890' statusCode: '503' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 deprecated: false components: securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: https://api.mtn.com/v1/oauth/access_token scopes: {} Bearer: type: http description: Bearer token received from OAuth2.0 authentication with the MADAPI scheme: bearer bearerFormat: JWT