openapi: 3.2.0 info: title: Payments v1 Payment API description: This is the Payment API for MADAPI. Handles payment use cases such as spTransfer, Debit request, Payment request, and related financial transactions. Provides comprehensive payment processing capabilities including merchant payments, customer payments, transaction status queries, payment history, and reverse payment operations. 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: Payment paths: /payment-link: post: tags: - Payment summary: Provides the ability for a consumer to generate a payment link for account payment description: Provides the ability for a consumer to get the payment link for the requesting MSISDN so as to enable the customer to make payment to the service providers. operationId: Payment_post_generatePaymentLink_paymentlink parameters: - name: transactionId in: header required: false schema: type: string - name: offerMenuId in: query required: false schema: type: string - name: countryCode in: header required: false schema: type: string - name: targetSystem in: header required: false schema: type: string requestBody: content: application/json: schema: title: PaymentRequest type: object properties: statusDate: type: string extension: title: Extension type: object properties: bundleCode: type: string awufu: type: string bundleInput: type: string networkOperator: type: string channel: type: string language: type: string additionalInformation1: type: string additionalInformation2: type: string amountUnit: type: string transactionId: type: string iname: type: string communicationChannel: type: string notification: type: string receivingCustomerId: type: string benmsisdn: type: string serviceGroupCode: type: string lineNumber: type: string rechargeType: type: string redirectURL: type: string authorizationCode: type: string deliveryMethod: type: string scheduled: title: Scheduledtransactiondate type: object properties: date: type: string frequency: title: Frequency type: object properties: duration: type: string frequencyType: title: FrequencyType type: object properties: type: type: string durationType: title: DurationType type: object properties: plural: type: string singular: type: string type: type: string channel: type: string description: type: string payer: title: Payer type: object properties: payerRef: type: string payerSurname: type: string includePayerCharges: type: boolean payerIdType: type: string payerId: type: string payerName: type: string payerNote: type: string paymentmethods: type: array items: type: string frequency: title: Frequency type: object properties: duration: type: string frequencyType: title: FrequencyType type: object properties: type: type: string durationType: title: DurationType type: object properties: plural: type: string singular: type: string type: type: string payee: type: array items: title: Payee type: object properties: totalAmount: title: MoneyType type: object properties: amount: type: string units: type: string payeeName: type: string amount: title: MoneyType type: object properties: amount: type: string units: type: string payeeNote: type: string payeeId: type: string taxAmount: title: MoneyType type: object properties: amount: type: string units: type: string payeeIdType: type: string prefLang: type: string merchantId: type: string countryCode: type: string segment: type: string callbackURL: type: string externalTransactionId: type: string additionalInformation: type: array items: title: AdditionalInformation type: object properties: name: type: string description: type: string amount: title: MoneyType type: object properties: amount: type: string units: type: string coupon: type: string includePayerCharges: type: string itemDetails: type: array items: title: ItemDetail type: object properties: additionalInformation: type: array items: title: AdditionalInformation type: object properties: name: type: string description: type: string itemName: type: string quantity: type: string itemValue: type: string currency: type: string itemDescription: type: string transactionId: type: string targetSystem: type: string quoteId: type: string referenceid: type: string IdType: type: string transactionType: type: string totalAmount: title: MoneyType type: object properties: amount: type: string units: type: string name: type: string transferType: type: string paymentMethod: title: PaymentMethod type: object properties: name: type: string description: type: string details: title: PaymentMethodTypeDetails type: object properties: bankAccountTransfer: title: BankAccountTransfer type: object properties: owner: type: string bank: type: string accountNumberType: type: string accountNumber: type: string BIC: type: string bucket: title: Account type: object properties: name: type: string description: type: string id: type: string tokenizedCard: title: TokenizedCard type: object properties: lastFourDigits: type: string type: type: string tokenType: type: string brand: type: string issuer: type: string token: type: string digitalWallet: title: DigitalWallet type: object properties: walletUri: type: string walletId: type: string service: type: string bankCard: title: BankCard type: object properties: cvv: type: string bank: type: string pin: type: string lastFourDigits: type: string nameOnCard: type: string type: type: string brand: type: string cardNumber: type: string expirationDate: type: string voucher: title: Voucher type: object properties: code: type: string description: type: string campaign: type: string value: type: string expirationDate: type: string bankAccountDebit: title: BankAccountDebit type: object properties: owner: type: string bank: type: string accountNumberType: type: string accountNumber: type: string BIC: type: string invoice: title: Invoice type: object properties: deactivateOnFail: type: boolean retryFrequency: type: string endDate: type: string callbackUrl: type: string id: type: string type: type: string retryOnFail: type: boolean startDate: type: string frequency: type: string retryRun: type: string account: title: Account type: object properties: name: type: string description: type: string id: type: string loyaltyAccount: title: Account type: object properties: name: type: string description: type: string id: type: string validFrom: type: string type: title: PaymentMethodType type: object properties: value: type: string validTo: type: string siteId: type: string correlatorId: type: string callingSystem: type: string authenticationType: type: string partnerId: type: string paymentDate: type: string taxAmount: title: TaxMoneyType type: object properties: amount: type: string taxId: type: string units: type: string status: type: string required: true responses: '200': description: Payment link generated successfully. Returns payment link details including URL, expiration time, and payment configuration. content: application/json: schema: type: string '400': description: Bad request. Invalid MSISDN, missing required parameters, or malformed payment request. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '500': description: Internal server error. Payment link generation failure, system error, or service unavailable. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '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 '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-agreement: post: tags: - Payment summary: Generate payment agreement (Promise to Pay) description: Provides the ability for a consumer to generate a payment agreement (Promise to Pay). This endpoint allows customers to set up payment promise agreements with service providers, enabling deferred payment arrangements and payment scheduling functionality. It handles the creation of payment agreements with appropriate validation, terms and conditions, and integration with payment processing systems. operationId: Payment_post_setPaymentPromise_paymentagreement parameters: - name: transactionId in: header required: false schema: type: string requestBody: content: application/json: schema: title: PromiseToPayRequest type: object properties: promiseThreshold: type: string billingAccountNo: type: string numberOfInstallments: type: integer format: int32 promiseAmount: type: string promiseOpenDate: type: string durationUOM: type: string required: true responses: '200': description: Payment agreement created successfully. Returns confirmation of payment promise setup with agreement details, terms, and reference information. content: application/json: schema: type: string '400': description: Bad request. Invalid payment promise request parameters, missing required fields, or validation errors in payment agreement request. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '500': description: Internal server error. Payment agreement service error, database connection failure, or system exception during payment promise processing. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '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 '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 /reverse-payment: post: tags: - Payment summary: Reverse payment description: Provides the ability for a consumer to reverse a payment transaction and all of it's potential sub-transactions. This endpoint processes payment reversals including validation of reversal requests, authorization checks, balance verification, and execution of reverse transactions. It handles complete transaction rollback including all associated sub-transactions, updates account balances, triggers notifications, and maintains comprehensive audit trails for reversal operations. operationId: Payment_post_reversePayment_reversepayment parameters: - name: transactionId in: header required: true schema: type: string - name: authorizationData in: header required: true schema: type: string - name: countryCode in: header required: true schema: type: string requestBody: content: application/json: schema: title: ReversePaymentRequest type: object properties: statusDate: type: string authorizationCode: type: string channel: type: string description: type: string payer: title: Payer type: object properties: payerRef: type: string payerSurname: type: string includePayerCharges: type: boolean payerIdType: type: string payerId: type: string payerName: type: string payerNote: type: string payee: type: array items: title: Payee type: object properties: totalAmount: title: MoneyType type: object properties: amount: type: string units: type: string payeeName: type: string amount: title: MoneyType type: object properties: amount: type: string units: type: string payeeNote: type: string payeeId: type: string taxAmount: title: MoneyType type: object properties: amount: type: string units: type: string payeeIdType: type: string countryCode: type: string callbackURL: type: string externalTransactionId: type: string additionalInformation: type: array items: title: AdditionalInformation type: object properties: name: type: string description: type: string amount: title: MoneyType type: object properties: amount: type: string units: type: string financialInstructionType: title: Financialinstructiontype type: object loyaltyInformation: title: LoyaltyInformation type: object properties: newBalance: type: string generatedAmount: type: string consumedAmount: type: string reversalType: title: Transfertype type: object targetSystem: type: string quoteId: type: string transactionType: type: string totalAmount: title: MoneyType type: object properties: amount: type: string units: type: string name: type: string paymentMethod: title: PaymentMethod type: object properties: name: type: string description: type: string details: title: PaymentMethodTypeDetails type: object properties: bankAccountTransfer: title: BankAccountTransfer type: object properties: owner: type: string bank: type: string accountNumberType: type: string accountNumber: type: string BIC: type: string bucket: title: Account type: object properties: name: type: string description: type: string id: type: string tokenizedCard: title: TokenizedCard type: object properties: lastFourDigits: type: string type: type: string tokenType: type: string brand: type: string issuer: type: string token: type: string digitalWallet: title: DigitalWallet type: object properties: walletUri: type: string walletId: type: string service: type: string bankCard: title: BankCard type: object properties: cvv: type: string bank: type: string pin: type: string lastFourDigits: type: string nameOnCard: type: string type: type: string brand: type: string cardNumber: type: string expirationDate: type: string voucher: title: Voucher type: object properties: code: type: string description: type: string campaign: type: string value: type: string expirationDate: type: string bankAccountDebit: title: BankAccountDebit type: object properties: owner: type: string bank: type: string accountNumberType: type: string accountNumber: type: string BIC: type: string invoice: title: Invoice type: object properties: deactivateOnFail: type: boolean retryFrequency: type: string endDate: type: string callbackUrl: type: string id: type: string type: type: string retryOnFail: type: boolean startDate: type: string frequency: type: string retryRun: type: string account: title: Account type: object properties: name: type: string description: type: string id: type: string loyaltyAccount: title: Account type: object properties: name: type: string description: type: string id: type: string validFrom: type: string type: title: PaymentMethodType type: object properties: value: type: string validTo: type: string correlatorId: type: string callingSystem: type: string paymentDate: type: string taxAmount: title: MoneyType type: object properties: amount: type: string units: type: string status: type: string required: true responses: '200': description: Payment reversal processed successfully. Returns comprehensive reversal response including transaction ID, reversal status, and confirmation details. content: application/json: schema: title: APIResponse type: object properties: data: type: string method: type: string error: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string statusMessage: type: string transactionId: type: string timeStamp: type: string path: type: string sequenceNo: type: string httpStatus: title: HttpStatus type: object properties: series: title: Series type: object properties: value: type: integer format: int32 reasonPhrase: type: string value: type: integer format: int32 customerId: 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 statusCode: type: string supportMessage: type: string '400': description: Bad request. Invalid reversal request parameters, missing required fields, or validation errors. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '404': description: Original payment not found. No transaction exists for the provided transaction ID or payment reference. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '500': description: Internal server error. Payment reversal service error, database connection failure, or system exception during reversal processing. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '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 '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 /payments: post: tags: - Payment summary: Process payment to service providers description: Provides the ability for a consumer to make a payment to service providers. This endpoint processes payment transactions including validation of payment requests, authorization checks, balance verification, and transaction execution. It supports various payment types including direct payments, merchant payments, and service provider transfers with comprehensive error handling and transaction status reporting. operationId: Payment_post_payment parameters: - name: transactionId in: header required: false schema: type: string - name: countryCode in: header required: true schema: type: string - name: authorizationData in: header required: false schema: type: string - name: channelId in: header required: false schema: type: string - name: spPartnerName in: header required: false schema: type: string - name: autoRenew in: header required: false schema: type: string - name: x-origin-channelid in: header required: false schema: type: string - name: prefLang in: query required: false schema: type: string requestBody: content: application/json: schema: title: PaymentRequest type: object properties: statusDate: type: string extension: title: Extension type: object properties: bundleCode: type: string awufu: type: string bundleInput: type: string networkOperator: type: string channel: type: string language: type: string additionalInformation1: type: string additionalInformation2: type: string amountUnit: type: string transactionId: type: string iname: type: string communicationChannel: type: string notification: type: string receivingCustomerId: type: string benmsisdn: type: string serviceGroupCode: type: string lineNumber: type: string rechargeType: type: string redirectURL: type: string authorizationCode: type: string deliveryMethod: type: string scheduled: title: Scheduledtransactiondate type: object properties: date: type: string frequency: title: Frequency type: object properties: duration: type: string frequencyType: title: FrequencyType type: object properties: type: type: string durationType: title: DurationType type: object properties: plural: type: string singular: type: string type: type: string channel: type: string description: type: string payer: title: Payer type: object properties: payerRef: type: string payerSurname: type: string includePayerCharges: type: boolean payerIdType: type: string payerId: type: string payerName: type: string payerNote: type: string paymentmethods: type: array items: type: string frequency: title: Frequency type: object properties: duration: type: string frequencyType: title: FrequencyType type: object properties: type: type: string durationType: title: DurationType type: object properties: plural: type: string singular: type: string type: type: string payee: type: array items: title: Payee type: object properties: totalAmount: title: MoneyType type: object properties: amount: type: string units: type: string payeeName: type: string amount: title: MoneyType type: object properties: amount: type: string units: type: string payeeNote: type: string payeeId: type: string taxAmount: title: MoneyType type: object properties: amount: type: string units: type: string payeeIdType: type: string prefLang: type: string merchantId: type: string countryCode: type: string segment: type: string callbackURL: type: string externalTransactionId: type: string additionalInformation: type: array items: title: AdditionalInformation type: object properties: name: type: string description: type: string amount: title: MoneyType type: object properties: amount: type: string units: type: string coupon: type: string includePayerCharges: type: string itemDetails: type: array items: title: ItemDetail type: object properties: additionalInformation: type: array items: title: AdditionalInformation type: object properties: name: type: string description: type: string itemName: type: string quantity: type: string itemValue: type: string currency: type: string itemDescription: type: string transactionId: type: string targetSystem: type: string quoteId: type: string referenceid: type: string IdType: type: string transactionType: type: string totalAmount: title: MoneyType type: object properties: amount: type: string units: type: string name: type: string transferType: type: string paymentMethod: title: PaymentMethod type: object properties: name: type: string description: type: string details: title: PaymentMethodTypeDetails type: object properties: bankAccountTransfer: title: BankAccountTransfer type: object properties: owner: type: string bank: type: string accountNumberType: type: string accountNumber: type: string BIC: type: string bucket: title: Account type: object properties: name: type: string description: type: string id: type: string tokenizedCard: title: TokenizedCard type: object properties: lastFourDigits: type: string type: type: string tokenType: type: string brand: type: string issuer: type: string token: type: string digitalWallet: title: DigitalWallet type: object properties: walletUri: type: string walletId: type: string service: type: string bankCard: title: BankCard type: object properties: cvv: type: string bank: type: string pin: type: string lastFourDigits: type: string nameOnCard: type: string type: type: string brand: type: string cardNumber: type: string expirationDate: type: string voucher: title: Voucher type: object properties: code: type: string description: type: string campaign: type: string value: type: string expirationDate: type: string bankAccountDebit: title: BankAccountDebit type: object properties: owner: type: string bank: type: string accountNumberType: type: string accountNumber: type: string BIC: type: string invoice: title: Invoice type: object properties: deactivateOnFail: type: boolean retryFrequency: type: string endDate: type: string callbackUrl: type: string id: type: string type: type: string retryOnFail: type: boolean startDate: type: string frequency: type: string retryRun: type: string account: title: Account type: object properties: name: type: string description: type: string id: type: string loyaltyAccount: title: Account type: object properties: name: type: string description: type: string id: type: string validFrom: type: string type: title: PaymentMethodType type: object properties: value: type: string validTo: type: string siteId: type: string correlatorId: type: string callingSystem: type: string authenticationType: type: string partnerId: type: string paymentDate: type: string taxAmount: title: TaxMoneyType type: object properties: amount: type: string taxId: type: string units: type: string status: type: string required: true responses: '200': description: Payment reversal processed successfully. Returns comprehensive reversal response including transaction ID, reversal status, and confirmation details. content: application/json: schema: title: APIResponse type: object properties: data: type: string method: type: string error: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string statusMessage: type: string transactionId: type: string timeStamp: type: string path: type: string sequenceNo: type: string httpStatus: title: HttpStatus type: object properties: series: title: Series type: object properties: value: type: integer format: int32 reasonPhrase: type: string value: type: integer format: int32 customerId: 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 statusCode: type: string supportMessage: type: string '400': description: Bad request. Invalid reversal request parameters, missing required fields, or validation errors. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '404': description: Original payment not found. No transaction exists for the provided transaction ID or payment reference. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '500': description: Internal server error. Payment reversal service error, database connection failure, or system exception during reversal processing. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '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 '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 /merchant-payment: post: tags: - Payment summary: Process merchant payment transactions description: Processes payment transactions for merchant services including validation of merchant payment requests, authorization checks, balance verification, and transaction execution. This endpoint supports various merchant payment types including direct merchant payments, service provider transfers, and merchant refunds with comprehensive error handling, transaction status reporting, and audit trail maintenance. Handles complex merchant payment workflows including multi-currency support, fee calculations, and settlement processing. operationId: Payment_post_merchantPayment_merchantpayment parameters: - name: operationType in: query required: true schema: type: string - name: x-country-code in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string - name: authorizationData in: header required: false schema: type: string requestBody: content: application/json: schema: title: MerchantPaymentRequest type: object properties: receiverMessage: type: string amount: title: MoneyDetailsType type: object properties: amount: type: string currency: type: string extension: type: string quote: type: string senderNote: type: string coupon: title: Coupon type: object properties: coupon: type: string requestReferenceId: title: RequestReferenceId type: object properties: provider: type: string id: type: string callingSystem: type: string sendingFri: title: MerchantFriValue type: object properties: friValue: type: string friIdentityType: type: string targetSystem: type: string receivingFri: title: MerchantFriValue type: object properties: friValue: type: string friIdentityType: type: string required: true responses: '200': description: Merchant payment processed successfully. Returns comprehensive payment response including transaction ID, payment status, merchant details, amount processed, and confirmation details with support for various payment methods and currencies. content: application/json: schema: title: APIResponse type: object properties: data: type: string method: type: string error: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string statusMessage: type: string transactionId: type: string timeStamp: type: string path: type: string sequenceNo: type: string httpStatus: title: HttpStatus type: object properties: series: title: Series type: object properties: value: type: integer format: int32 reasonPhrase: type: string value: type: integer format: int32 customerId: 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 statusCode: type: string supportMessage: type: string '400': description: Bad request. Invalid merchant payment request parameters, missing required fields, or validation errors in payment details, merchant information, or transaction data. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '401': description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions for merchant payment processing, or authentication failure. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '500': description: Internal server error. Unexpected system failure during merchant payment processing, database connectivity issues, or external service integration problems. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '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 '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 /{correlatorId}/transactionStatus: get: tags: - Payment summary: Get payment transaction status description: Provides the status of a Payment Transaction to service providers. This endpoint enables querying the current status of payment transactions including pending, completed, failed, or cancelled states. It returns comprehensive transaction information including transaction details, status history, error messages if applicable, and associated metadata for tracking and reconciliation purposes. operationId: Payment_get_getPaymentTransactionStatus_correlatorIdtransact parameters: - name: correlatorId in: path required: true schema: type: string - name: transactionId in: header required: true schema: type: string - name: targetSystem in: header required: false schema: type: string - name: countryCode in: header required: true schema: type: string - name: amount in: query required: false schema: type: string - name: paymentType in: query required: false schema: type: string - name: customerId in: query required: false schema: type: string - name: description in: query required: false schema: type: string - name: authorizationData in: header required: false schema: type: string - name: languageCode in: header required: false schema: type: string - name: x-origin-channelid in: header required: false schema: type: string responses: '200': description: Payment transaction status retrieved successfully. Returns detailed payment status information including transaction state, payment details, processing timestamps, and relevant status metadata. content: application/json: schema: title: APIResponse type: object properties: data: type: string method: type: string error: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string statusMessage: type: string transactionId: type: string timeStamp: type: string path: type: string sequenceNo: type: string httpStatus: title: HttpStatus type: object properties: series: title: Series type: object properties: value: type: integer format: int32 reasonPhrase: type: string value: type: integer format: int32 customerId: 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 statusCode: type: string supportMessage: type: string '400': description: Bad request. Invalid transaction ID, missing required headers, or malformed request parameters. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '404': description: Payment transaction not found. No transaction exists for the provided transaction ID or correlator ID. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '500': description: Internal server error. Database connection failure, payment service error, or system exception during status retrieval. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '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 '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 /status/{transactionid}: get: tags: - Payment summary: Update payment status to processed description: Updates the payment status from pending to processed for completed transactions. This endpoint is used to mark payment transactions as successfully processed in the system database. It performs status validation, updates the payment record with processed status, timestamps the completion, and maintains audit trail information for transaction lifecycle management and reconciliation purposes. operationId: Payment_get_updatePaymentStatus_statustransactionid parameters: - name: transactionid in: path required: true schema: type: string responses: '200': description: Payment status updated successfully to processed. Returns empty response indicating successful status update operation. content: application/json: schema: type: object '404': description: Payment not found. No payment record exists for the provided transaction ID or transaction ID is invalid. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '500': description: Internal server error. Database connection failure, payment status update error, or system exception during status update processing. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: 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-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 '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 /details/{transactionid}: get: tags: - Payment summary: Get payment by transactionId description: Returns the payment object as saved in the database without the actual request json. This endpoint retrieves complete payment transaction details from the database using the transaction identifier. It returns payment information including transaction status, amounts, timestamps, customer details, and service provider information for transaction lookup and reconciliation purposes. operationId: Payment_get_getPaymentByTransactionId_detailstransactionid parameters: - name: transactionid in: path required: true schema: type: string responses: '200': description: Payment details retrieved successfully. Returns complete payment transaction information including transaction status, amounts, timestamps, customer details, and service provider data. content: application/json: schema: title: APIResponse type: object properties: data: type: string method: type: string error: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string statusMessage: type: string transactionId: type: string timeStamp: type: string path: type: string sequenceNo: type: string httpStatus: title: HttpStatus type: object properties: series: title: Series type: object properties: value: type: integer format: int32 reasonPhrase: type: string value: type: integer format: int32 customerId: 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 statusCode: type: string supportMessage: type: string '404': description: Payment not found. No payment record exists for the provided transaction ID. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '500': description: Internal server error. Database connection failure, payment retrieval error, or system exception during payment details lookup. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: 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-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 '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 /fee: post: tags: - Payment summary: Calculate payment transfer fees description: Provides the ability for a consumer to check a payment transfer fee charged by service providers. This endpoint calculates and returns the applicable fees for payment transactions based on transaction amount, payment type, service provider, and customer tier. It supports fee estimation for various payment scenarios including merchant payments, peer-to-peer transfers, and service provider transactions with detailed fee breakdown information. operationId: Payment_post_feeCheck_fee parameters: - name: transactionId in: header required: true schema: type: string - name: countryCode in: header required: true schema: type: string - name: authorizationData in: header required: false schema: type: string - name: autoRenew in: header required: false schema: type: string requestBody: content: application/json: schema: title: PaymentRequest type: object properties: statusDate: type: string extension: title: Extension type: object properties: bundleCode: type: string awufu: type: string bundleInput: type: string networkOperator: type: string channel: type: string language: type: string additionalInformation1: type: string additionalInformation2: type: string amountUnit: type: string transactionId: type: string iname: type: string communicationChannel: type: string notification: type: string receivingCustomerId: type: string benmsisdn: type: string serviceGroupCode: type: string lineNumber: type: string rechargeType: type: string redirectURL: type: string authorizationCode: type: string deliveryMethod: type: string scheduled: title: Scheduledtransactiondate type: object properties: date: type: string frequency: title: Frequency type: object properties: duration: type: string frequencyType: title: FrequencyType type: object properties: type: type: string durationType: title: DurationType type: object properties: plural: type: string singular: type: string type: type: string channel: type: string description: type: string payer: title: Payer type: object properties: payerRef: type: string payerSurname: type: string includePayerCharges: type: boolean payerIdType: type: string payerId: type: string payerName: type: string payerNote: type: string paymentmethods: type: array items: type: string frequency: title: Frequency type: object properties: duration: type: string frequencyType: title: FrequencyType type: object properties: type: type: string durationType: title: DurationType type: object properties: plural: type: string singular: type: string type: type: string payee: type: array items: title: Payee type: object properties: totalAmount: title: MoneyType type: object properties: amount: type: string units: type: string payeeName: type: string amount: title: MoneyType type: object properties: amount: type: string units: type: string payeeNote: type: string payeeId: type: string taxAmount: title: MoneyType type: object properties: amount: type: string units: type: string payeeIdType: type: string prefLang: type: string merchantId: type: string countryCode: type: string segment: type: string callbackURL: type: string externalTransactionId: type: string additionalInformation: type: array items: title: AdditionalInformation type: object properties: name: type: string description: type: string amount: title: MoneyType type: object properties: amount: type: string units: type: string coupon: type: string includePayerCharges: type: string itemDetails: type: array items: title: ItemDetail type: object properties: additionalInformation: type: array items: title: AdditionalInformation type: object properties: name: type: string description: type: string itemName: type: string quantity: type: string itemValue: type: string currency: type: string itemDescription: type: string transactionId: type: string targetSystem: type: string quoteId: type: string referenceid: type: string IdType: type: string transactionType: type: string totalAmount: title: MoneyType type: object properties: amount: type: string units: type: string name: type: string transferType: type: string paymentMethod: title: PaymentMethod type: object properties: name: type: string description: type: string details: title: PaymentMethodTypeDetails type: object properties: bankAccountTransfer: title: BankAccountTransfer type: object properties: owner: type: string bank: type: string accountNumberType: type: string accountNumber: type: string BIC: type: string bucket: title: Account type: object properties: name: type: string description: type: string id: type: string tokenizedCard: title: TokenizedCard type: object properties: lastFourDigits: type: string type: type: string tokenType: type: string brand: type: string issuer: type: string token: type: string digitalWallet: title: DigitalWallet type: object properties: walletUri: type: string walletId: type: string service: type: string bankCard: title: BankCard type: object properties: cvv: type: string bank: type: string pin: type: string lastFourDigits: type: string nameOnCard: type: string type: type: string brand: type: string cardNumber: type: string expirationDate: type: string voucher: title: Voucher type: object properties: code: type: string description: type: string campaign: type: string value: type: string expirationDate: type: string bankAccountDebit: title: BankAccountDebit type: object properties: owner: type: string bank: type: string accountNumberType: type: string accountNumber: type: string BIC: type: string invoice: title: Invoice type: object properties: deactivateOnFail: type: boolean retryFrequency: type: string endDate: type: string callbackUrl: type: string id: type: string type: type: string retryOnFail: type: boolean startDate: type: string frequency: type: string retryRun: type: string account: title: Account type: object properties: name: type: string description: type: string id: type: string loyaltyAccount: title: Account type: object properties: name: type: string description: type: string id: type: string validFrom: type: string type: title: PaymentMethodType type: object properties: value: type: string validTo: type: string siteId: type: string correlatorId: type: string callingSystem: type: string authenticationType: type: string partnerId: type: string paymentDate: type: string taxAmount: title: TaxMoneyType type: object properties: amount: type: string taxId: type: string units: type: string status: type: string required: true responses: '200': description: Fee calculation completed successfully. Returns detailed fee information including transaction fees, service charges, and total cost breakdown. content: application/json: schema: title: APIResponse type: object properties: data: type: string method: type: string error: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string statusMessage: type: string transactionId: type: string timeStamp: type: string path: type: string sequenceNo: type: string httpStatus: title: HttpStatus type: object properties: series: title: Series type: object properties: value: type: integer format: int32 reasonPhrase: type: string value: type: integer format: int32 customerId: 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 statusCode: type: string supportMessage: type: string '400': description: Bad request. Invalid payment request parameters, missing required fields, or validation errors in fee calculation request. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '500': description: Internal server error. Fee calculation service error, database connection failure, or system exception during fee processing. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '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 '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 /{id}/history: get: tags: - Payment summary: Get a list of payments made on a reference or by a customer id description: Get a list of payments made on a reference or by a customer id. This endpoint retrieves payment transaction history filtered by customer identifier or payment reference. It returns comprehensive payment lists including transaction details, status information, amounts, timestamps, and associated metadata. Supports pagination and filtering options for efficient data retrieval and transaction analysis. operationId: Payment_get_paymentHistory_idhistory parameters: - name: id in: path required: true schema: type: string - name: segment in: query required: false schema: type: string - name: pageSize in: query required: false schema: type: string - name: pageNumber in: query required: false schema: type: string - name: status in: query required: false schema: type: string - name: requestType in: query required: false schema: type: string - name: transactionId in: header required: false schema: type: string - name: offset in: query required: false schema: type: string - name: countryCode in: header required: true schema: type: string - name: authorizationData in: header required: false schema: type: string - name: x-origin-channelid in: header required: false schema: type: string - name: x-target-system in: header required: false schema: type: string - name: nodeId in: query required: false schema: type: string - name: startTime in: query required: false schema: type: string - name: startDate in: query required: false schema: type: string - name: endDate in: query required: false schema: type: string - name: registrationChannel in: query required: false schema: type: string - name: queryType in: query required: false schema: type: string - name: traceId in: query required: false schema: type: string - name: serviceId in: query required: false schema: type: string - name: serviceType in: query required: false schema: type: string responses: '200': description: Payment history retrieved successfully. Returns comprehensive list of payment transactions with detailed transaction information, status, amounts, and timestamps. content: application/json: schema: title: HistoryAPIResponse type: object properties: data: type: string error: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string statusMessage: type: string statusCode: type: string '400': description: Bad request. Invalid customer ID, missing required parameters, or malformed request. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '404': description: No payment history found. No transactions exist for the provided customer ID or reference. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '500': description: Internal server error. Database connection failure, payment history service error, or system exception during data retrieval. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '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 '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-agreement/eligibility: get: tags: - Payment summary: Get eligibilty status. description: Provides the ability for a consumer to check the eligibility status for payment agreement. This endpoint evaluates customer eligibility for payment agreement services including promise-to-pay agreements and payment plans. It performs eligibility checks based on customer account status, payment history, creditworthiness, billing account information, and service provider requirements, returning detailed eligibility assessment results. operationId: Payment_get_aggregateGetEligibilty_paymentagreementelig parameters: - name: billingAccountNumber in: query required: true schema: type: string - name: transactionId in: header required: false schema: type: string responses: '200': description: Success content: application/json: schema: title: PaymentPromiseResponseEligibilty type: object properties: path: type: string data: title: Data type: object properties: PromiseToPayEligibilityDetails: title: PromiseToPayEligibilityDetails type: object properties: eligibilityStatus: type: string minimumAmount: type: string accountBalance: type: string paymentStartDate: type: string method: type: string _links: title: Links type: object properties: self: title: Self type: object properties: href: type: string httpStatus: title: HttpStatus type: object properties: series: title: Series type: object properties: value: type: integer format: int32 reasonPhrase: type: string value: type: integer format: int32 statusMessage: type: string transactionId: type: string statusCode: type: string supportMessage: type: string timestamp: 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-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 /reverse-payment/{id}: get: tags: - Payment summary: reverse payment history description: Provides the ability for a consumer to get a reverse payment details. This endpoint retrieves detailed information about specific reverse payment transactions using transaction identifiers. It returns comprehensive reverse payment details including original transaction information, reversal amounts, status, timestamps, customer information, and associated metadata for detailed transaction analysis and reconciliation purposes. operationId: Payment_get_reversePaymentHistory_reversepaymentid parameters: - name: id in: path required: true schema: type: string - name: correlatorId in: header required: true schema: type: string - name: transactionId in: header required: true schema: type: string - name: authorizationData in: header required: true schema: type: string - name: countryCode in: header required: true schema: type: string responses: '200': description: Reverse payment details retrieved successfully. Returns comprehensive reverse payment information including original transaction details, reversal amounts, and status information. content: application/json: schema: title: APIResponse type: object properties: data: type: string method: type: string error: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string statusMessage: type: string transactionId: type: string timeStamp: type: string path: type: string sequenceNo: type: string httpStatus: title: HttpStatus type: object properties: series: title: Series type: object properties: value: type: integer format: int32 reasonPhrase: type: string value: type: integer format: int32 customerId: 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 statusCode: type: string supportMessage: type: string '400': description: Bad request. Invalid transaction ID, missing required headers, or malformed request parameters. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '404': description: Reverse payment not found. No reverse payment record exists for the provided transaction ID. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '500': description: Internal server error. Database connection failure, reverse payment service error, or system exception during details retrieval. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '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 '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 /reverse-payment/history: get: tags: - Payment summary: Get reverse payment transaction history description: Retrieves comprehensive history of reverse payment transactions for a specific customer. This endpoint processes requests for reverse payment history including validation of customer credentials, transaction filtering by date ranges, status filtering, and pagination support. It handles complex reverse payment queries including multi-system integration, transaction type filtering, and comprehensive audit trail retrieval for detailed transaction analysis and reconciliation purposes. operationId: Payment_get_reversePaymentHistory_reversepaymenthistor parameters: - name: customerId in: header required: true schema: type: string - name: correlatorId in: header required: true schema: type: string - name: transactionId in: header required: true schema: type: string - name: transactionstatus in: header required: true schema: type: string - name: authorizationData in: header required: true schema: type: string - name: countryCode in: header required: true schema: type: string - name: transactiontype in: query required: true schema: type: string - name: amount in: query required: false schema: type: string - name: nodeId in: query required: false schema: type: string - name: startDate in: query required: false schema: type: string - name: endDate in: query required: false schema: type: string - name: otherFri in: query required: false schema: type: string - name: posMsisdn in: query required: false schema: type: string - name: quoteId in: query required: false schema: type: string - name: limit in: query required: false schema: type: integer format: int32 - name: pageNo in: query required: true schema: type: string responses: '200': description: Reverse payment history retrieved successfully. Returns comprehensive list of reverse payment transactions including transaction details, amounts, status information, timestamps, and associated metadata with support for various filtering options. content: application/json: schema: title: APIResponse type: object properties: data: type: string method: type: string error: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string statusMessage: type: string transactionId: type: string timeStamp: type: string path: type: string sequenceNo: type: string httpStatus: title: HttpStatus type: object properties: series: title: Series type: object properties: value: type: integer format: int32 reasonPhrase: type: string value: type: integer format: int32 customerId: 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 statusCode: type: string supportMessage: type: string '400': description: Bad request. Invalid customer ID, missing required parameters, invalid date ranges, or malformed request parameters for reverse payment history retrieval. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '404': description: Customer not found. No reverse payment history available for the provided customer ID or customer record does not exist in the system. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '500': description: Internal server error. Database connectivity issues, system integration failures, or unexpected errors during reverse payment history processing. content: application/json: schema: title: APIError type: object properties: path: type: string downstreamStatusCode: type: integer format: int32 sequenceNo: type: string method: type: string statusMessage: type: string transactionId: type: string supportMessage: type: string timestamp: type: string statusCode: type: string '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 '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