openapi: 3.0.1 info: title: mtn-madapi-payment-aggregator 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: "2.0" servers: - url: https://api.mtn.com/v1 description: Production Server security: - OAuth2: [] tags: - name: Payment - name: Consent paths: /payments/ussd/consent: post: tags: - Consent summary: Process user consent via USSD for payment authorization description: "Receives and processes user consent for payment transactions through\ \ USSD channels. This endpoint handles consent validation, consent status\ \ updates, payment authorization workflows, and maintains comprehensive consent\ \ audit trails. Supports various consent types including payment authorization,\ \ service subscription consent, and data processing consent with robust validation,\ \ security checks, and integration with payment processing systems for seamless\ \ transaction execution." operationId: Consent_post_receiveUserConsentFromUssd_paymentsussdconsent requestBody: content: application/json: schema: title: UssdInboundRequest type: object properties: messageType: type: string serviceCode: type: string language: type: string sessionId: type: string imsi: type: string msisdn: type: string cellId: type: string ussdString: type: string required: true responses: "200": description: "User consent processed successfully. Returns comprehensive\ \ consent response including consent status, transaction ID, user confirmation\ \ details, and next steps for payment processing with support for various\ \ consent scenarios." content: application/json: schema: title: UssdInboundResponse type: object properties: data: title: UssdInboundResponseData type: object properties: inboundResponse: type: string userInputRequired: type: boolean messageType: type: string serviceCode: 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 sessionId: type: string msisdn: type: string links: type: array items: title: Link type: object properties: template: title: UriTemplate type: object properties: template: type: string variables: title: TemplateVariables type: object properties: variables: type: array items: title: TemplateVariable type: object properties: name: type: string limit: type: integer format: int32 description: type: string type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string cardinality: title: Cardinality type: object baseUri: type: string groups: title: ExpandGroups type: object properties: groupList: type: array items: title: ExpandGroup type: object properties: variables: title: TemplateVariables type: object properties: variables: type: array items: title: TemplateVariable type: object properties: name: type: string limit: type: integer format: int32 description: type: string type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string cardinality: title: Cardinality type: object type: title: VariableType type: object properties: optional: type: boolean combiner: type: string key: type: string affordances: type: array items: title: Affordance type: object properties: models: type: object additionalProperties: title: AffordanceModel type: object properties: output: title: PayloadMetadata type: object input: title: InputPayloadMetadata type: object queryMethodParameters: type: array items: title: QueryParameter type: object properties: name: type: string value: type: string required: type: boolean name: type: string link: title: Link type: object httpMethod: title: HttpMethod type: object properties: name: type: string hreflang: type: string profile: type: string rel: title: LinkRelation type: object name: type: string href: type: string media: type: string title: type: string type: type: string deprecation: type: string statusMessage: type: string transactionId: type: string statusCode: type: string "400": description: "Bad request. Invalid consent request parameters, missing required\ \ fields, validation errors in user input, or malformed USSD consent 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 "404": description: "Not found. Consent record not found for the provided session\ \ ID, expired consent session, or invalid 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. Unexpected system failure during consent\ \ processing, database connectivity issues, payment service integration\ \ problems, or external service failures." 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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /payments/sms/consent: post: tags: - Consent summary: User consent via SMS description: "Receives user consent for a payment request via sms. This endpoint\ \ processes consent confirmation received through SMS channels for payment\ \ transactions. It validates consent requests, updates consent status, triggers\ \ payment processing workflows, and maintains consent audit trails. Supports\ \ various consent types including payment authorization, service subscription\ \ consent, and data processing consent with comprehensive validation and security\ \ checks." operationId: Consent_post_receiveUserConsentFromSms_paymentssmsconsent requestBody: content: application/json: schema: title: SmsInboundRequest type: object properties: data: title: SmsInboundRequestData type: object properties: totalNumberOfPendingMessages: type: string numberOfMessagesInThisBatch: type: string inboundSMSMessage: type: array items: title: SmsInboundMessage type: object properties: dateTime: type: string senderAddress: type: string registrationID: type: string messageID: type: string message: type: string statusMessage: type: string transactionID: type: string statusCode: type: string required: true responses: "200": description: Success 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 request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Bad request. Invalid request parameters, missing\ \ required fields, or validation errors." transactionId: "1234567890" statusCode: "400" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Not found. The requested resource was not found or does not exist. transactionId: "1234567890" statusCode: "404" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Internal server error. Unexpected system failure,\ \ database connectivity issues, or external service integration\ \ problems." transactionId: "1234567890" statusCode: "500" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /payment-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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Not found. The requested resource was not found or does not exist. transactionId: "1234567890" statusCode: "404" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /payment-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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Not found. The requested resource was not found or does not exist. transactionId: "1234567890" statusCode: "404" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Not found. The requested resource was not found or does not exist. transactionId: "1234567890" statusCode: "404" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /{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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Bad request. Invalid request parameters, missing\ \ required fields, or validation errors." transactionId: "1234567890" statusCode: "400" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Bad request. Invalid request parameters, missing\ \ required fields, or validation errors." transactionId: "1234567890" statusCode: "400" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Not found. The requested resource was not found or does not exist. transactionId: "1234567890" statusCode: "404" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /{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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /payment-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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Bad request. Invalid request parameters, missing\ \ required fields, or validation errors." transactionId: "1234567890" statusCode: "400" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Not found. The requested resource was not found or does not exist. transactionId: "1234567890" statusCode: "404" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Internal server error. Unexpected system failure,\ \ database connectivity issues, or external service integration\ \ problems." transactionId: "1234567890" statusCode: "500" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false /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-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." transactionId: "1234567890" statusCode: "401" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: "1234567890" statusCode: "403" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: "1234567890" statusCode: "502" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: "20250115120000001" method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: "1234567890" statusCode: type: string description: Error status code example: "400" supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15T12:00:00Z description: Generic MADAPI error response structure example: sequenceNo: "20250115120000001" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: "1234567890" statusCode: "503" supportMessage: API_ERROR timestamp: 2025-01-15T12:00:00Z deprecated: false components: securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: https://api.mtn.com/v1/oauth/access_token scopes: {} Bearer: type: http description: Bearer token received from OAuth2.0 authentication with the MADAPI scheme: bearer bearerFormat: JWT