openapi: 3.2.0
info:
  title: Taxation API
  description: This service provides comprehensive taxation management capabilities for MTN operations including tax calculation, validation, reporting, and compliance. It handles various taxation scenarios including service tax, VAT, and regulatory tax requirements, integrating with multiple tax systems across the MTN ecosystem.
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: 3.0.0 - Last updated date:2026-07-15 18:19:18
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: Taxation
paths:
  /{accountHolderId}/reserve:
    post:
      tags:
      - Taxation
      summary: Request for the taxable amount
      description: This operation retrieves the taxable amount of a transaction from the Ghana Revenue Authority. The endpoint supports e-levy calculations, MSISDN validation, country code processing, and comprehensive financial resource management with system endpoint routing.
      operationId: Taxation_post_getTaxationAmount_accountHolderIdreser
      parameters:
      - name: accountHolderId
        in: path
        required: true
        schema:
          type: string
      - name: targetSystem
        in: header
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: x-authorization
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: ElevyRequest
              type: object
              properties:
                receiverAccountNumber:
                  type: string
                receiverInstitutionId:
                  type: string
                senderIssuerId:
                  type: string
                transferAmount:
                  type: string
                senderAccountNumber:
                  type: string
                chargingPartyId:
                  type: string
                clientTimestamp:
                  type: string
                resourceId:
                  type: string
        required: true
      responses:
        '200':
          description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI TMF908-iot-Device Management flows.
          content:
            application/json:
              schema:
                title: TaxationResponse
                type: object
                properties:
                  eLevyId:
                    type: string
                  taxableAmount:
                    type: string
                  currency:
                    type: string
                  operation:
                    type: string
                  statusCode:
                    type: string
                  transactionId:
                    type: string
        '400':
          description: Bad request. Invalid request parameters, missing required fields, or validation errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '401':
          description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '403':
          description: Forbidden. Access denied. The request is valid but the server refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '404':
          description: Not found. The requested resource was not found or does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '500':
          description: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '502':
          description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '503':
          description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      deprecated: false
components:
  schemas:
    APIError:
      title: APIError
      required:
      - statusCode
      - statusMessage
      type: object
      properties:
        statusCode:
          type: string
          description: Error status code
          example: '400'
        statusMessage:
          type: string
          description: Human-readable error message
          example: Bad request. Invalid parameters provided.
        supportMessage:
          type: string
          description: Technical support message or error code for troubleshooting
          example: VALIDATION_ERROR
        transactionId:
          type: string
          description: Transaction identifier for tracking and correlation
          example: '1234567890'
        sequenceNo:
          type: string
          description: Sequence number for request tracking
          example: '20250115120000001'
        timestamp:
          type: string
          description: Error timestamp in ISO 8601 format
          format: date-time
          example: 2025-01-15 12:00:00+00:00
        path:
          type: string
          description: API endpoint path where the error occurred
          example: /api/v1/resource
        method:
          type: string
          description: HTTP method of the request that caused the error
          example: POST
        downstreamStatusCode:
          type: string
          description: Downstream service error code if applicable
      description: Generic MADAPI error response structure
      example:
        statusCode: '400'
        statusMessage: Bad request. Invalid request parameters, missing required fields, or validation errors.
        supportMessage: API_ERROR
        transactionId: '1234567890'
        sequenceNo: '20250115120000001'
        timestamp: 2025-01-15 12:00:00+00:00
  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