openapi: 3.2.0 info: title: Payments v1 Consent API description: This is the Payment API for MADAPI. Handles payment use cases such as spTransfer, Debit request, Payment request, and related financial transactions. Provides comprehensive payment processing capabilities including merchant payments, customer payments, transaction status queries, payment history, and reverse payment operations. license: name: MADAPI url: https://developers.mtn.com/ version: 3.0.0 servers: - url: https://api.mtn.com/v1 description: Production Server security: - OAuth2: [] tags: - name: 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-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure. transactionId: '1234567890' statusCode: '401' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '403': description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: '1234567890' statusCode: '403' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '502': description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: '1234567890' statusCode: '502' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '503': description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: '1234567890' statusCode: '503' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 deprecated: false /payments/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-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Bad request. Invalid request parameters, missing required fields, or validation errors. transactionId: '1234567890' statusCode: '400' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '401': description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure. transactionId: '1234567890' statusCode: '401' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '403': description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. transactionId: '1234567890' statusCode: '403' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '404': description: Not found. The requested resource was not found or does not exist. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Not found. The requested resource was not found or does not exist. transactionId: '1234567890' statusCode: '404' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '500': description: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems. transactionId: '1234567890' statusCode: '500' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '502': description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. transactionId: '1234567890' statusCode: '502' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 '503': description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: title: APIError required: - statusCode - statusMessage type: object properties: path: type: string description: API endpoint path where the error occurred example: /api/v1/resource downstreamStatusCode: type: string description: Downstream service error code if applicable sequenceNo: type: string description: Sequence number for request tracking example: '20250115120000001' method: type: string description: HTTP method of the request that caused the error example: POST statusMessage: type: string description: Human-readable error message example: Bad request. Invalid parameters provided. transactionId: type: string description: Transaction identifier for tracking and correlation example: '1234567890' statusCode: type: string description: Error status code example: '400' supportMessage: type: string description: Technical support message or error code for troubleshooting example: VALIDATION_ERROR timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time example: 2025-01-15 12:00:00+00:00 description: Generic MADAPI error response structure example: sequenceNo: '20250115120000001' statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. transactionId: '1234567890' statusCode: '503' supportMessage: API_ERROR timestamp: 2025-01-15 12:00:00+00:00 deprecated: false components: securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: https://api.mtn.com/v1/oauth/access_token scopes: {} Bearer: type: http description: Bearer token received from OAuth2.0 authentication with the MADAPI scheme: bearer bearerFormat: JWT