openapi: 3.0.1 info: title: TMF676 Payment Management Aggregator description: "The 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: "2.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-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 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-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 /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-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