swagger: "2.0" info: description: API to view users SMS, Data, Voice & Recharge usage and transaction history. version: "1.0.2" title: MTN Consumption API V2 host: api.mtn.com basePath : "/v2/consumption/" securityDefinitions: basicAuth: type: basic ApiKeyAuth: type: apiKey name: X-API-Key in: header schemes: - https consumes: - application/json produces: - application/json security: - ApiKeyAuth: [] - basicAuth: [] paths: /balance: post: tags: - Balance summary: Get Data Balance Details description: Returns customer's airtime and bundle balances. consumes: - application/json produces: - application/json parameters: - name: transactionId in: header required: false type: string description: A unique ID for tracking a particular transaction. - name: traceId in: header required: true type: string description: Unique identifier for tracing the request through the system. - name: channelName in: header required: true type: string description: Channel through which the request is made. - in: body name: body description: Balance request input required: true schema: $ref: '#/definitions/GetBalanceRequestBody' responses: 200: description: Successful balance retrieval schema: $ref: '#/definitions/GetBalanceResponse' 400: description: Bad Request schema: $ref: '#/definitions/ErrorPayload' 500: description: Internal Server Error schema: $ref: '#/definitions/ErrorPayload' /recharge/history: post: summary: Get recharge history details operationId: getRechargeHistory tags: - Recharge consumes: - application/json produces: - application/json parameters: - name: transactionId in: header description: Optional transaction ID required: false type: string - name: traceId in: header description: Trace ID for request tracking required: true type: string - name: channelName in: header description: Channel name required: true type: string - name: body in: body description: Recharge history request payload required: true schema: $ref: '#/definitions/RechargeHistoryRequestBody' responses: 200: description: Successful recharge history response schema: $ref: '#/definitions/APIResponseRechargeHistoryResponse' /recharge/airtime/summation: post: summary: Get recharge summary operationId: getRechargeSummary tags: - Recharge consumes: - application/json produces: - application/json parameters: - name: transactionId in: header description: Optional transaction ID required: false type: string - name: traceId in: header description: Trace ID for request tracking required: true type: string - name: channelName in: header description: Channel name required: true type: string - name: body in: body description: Recharge summary request payload required: true schema: $ref: '#/definitions/RechargeSummaryRequestBody' responses: 200: description: Successful recharge summary response schema: $ref: '#/definitions/APIResponseRechargeSummaryResponse' /usageHistory: post: summary: Get usage history details operationId: getUsageHistory tags: - Usage consumes: - application/json produces: - application/json parameters: - name: transactionId in: header description: Optional transaction ID required: false type: string - name: traceId in: header description: Trace ID for request tracking required: true type: string - name: channelName in: header description: Channel name required: true type: string - name: body in: body description: Usage history request payload required: true schema: $ref: '#/definitions/UsageHistoryRequestBody' responses: 200: description: Successful usage history response schema: $ref: '#/definitions/APIResponseUsageSummaryResponse' /usageSummation: post: summary: Get usage summary operationId: getUsageSummary tags: - Usage consumes: - application/json produces: - application/json parameters: - name: transactionId in: header description: Optional transaction ID required: false type: string - name: traceId in: header description: Trace ID for request tracking required: true type: string - name: channelName in: header description: Channel name required: true type: string - name: body in: body description: Usage summary request payload required: true schema: $ref: '#/definitions/UsageSummaryRequestBody' responses: 200: description: Successful usage summary response schema: $ref: '#/definitions/APIResponseUsageSummaryResponse' definitions: GetBalanceRequestBody: type: object required: - msisdn properties: msisdn: type: string pattern: ^[0-9]{3,15}$ description: Customer MSISDN in digits only. callBackUrl: type: string format: uri description: Optional callback URL in case of async processing. GetBalanceResponse: type: object properties: mainBalance: type: array items: $ref: '#/definitions/MainBalance' bundles: type: array items: $ref: '#/definitions/Bundle' MainBalance: type: object properties: amount: type: string example: "1000.00" currency: type: string example: "NGN" Bundle: type: object properties: dataAmount: type: string example: "500" unit: type: string example: "MB" RechargeHistoryRequestBody: type: object required: - msisdn - callBackUrl properties: msisdn: type: string description: MSISDN number (phone number) minLength: 3 maxLength: 15 pattern: '^[0-9]\d{2,14}$' callBackUrl: type: string description: Callback URL startDate: type: string description: Start date in yyyyMMdd format pattern: '^\d{8}$' endDate: type: string description: End date in yyyyMMdd format pattern: '^\d{8}$' pageNumber: type: integer minimum: 1 description: Page number (minimum 1) pageSize: type: integer minimum: 1 maximum: 100 description: Page size (max 100) Usage: type: object # Define properties of Usage here once available RechargeHistoryResponse: type: object properties: usage: type: array items: $ref: '#/definitions/Usage' description: Set of usage records default: [] period: type: string description: Period of the recharge history pageNumber: type: string description: Current page number totalPages: type: string description: Total number of pages RechargeSummaryRequestBody: type: object required: - msisdn - callBackUrl properties: msisdn: type: string description: MSISDN number (phone number) minLength: 3 maxLength: 15 pattern: '^[0-9]\d{2,14}$' callBackUrl: type: string description: Callback URL startDate: type: string description: Start date in yyyyMMdd format pattern: '^\d{8}$' endDate: type: string description: End date in yyyyMMdd format pattern: '^\d{8}$' pageNumber: type: integer minimum: 1 description: Page number (minimum 1) pageSize: type: integer minimum: 1 maximum: 100 description: Page size (max 100) RechargeSummaryResponse: type: object properties: summary: type: array items: $ref: '#/definitions/Summary' description: List of recharge summary items default: [] period: type: string description: Period of the recharge summary Summary: type: object properties: count: type: number format: float description: Count value totalAmount: type: number format: float description: Total amount value currency: type: string description: Currency code (e.g., USD) channels: type: array items: type: string description: List of channel names APIResponseRechargeSummaryResponse: type: object properties: status: type: string description: Status of the API response message: type: string description: Additional message data: $ref: '#/definitions/RechargeSummaryResponse' UsageHistoryRequestBody: type: object required: - msisdn - startDate properties: msisdn: type: string description: MSISDN (phone number) minLength: 3 maxLength: 15 pattern: '^[0-9]\d{2,14}$' callBackUrl: type: string description: Callback URL usageType: type: string description: Type of usage (e.g., voice, data, sms) startDate: type: string description: Start date in DD-MM-YYYY format pattern: '^(0[1-9]|[12][0-9]|3[01])-(0[1-9]|1[0-2])-\d{4}$' endDate: type: string description: End date in DD-MM-YYYY format pattern: '^(0[1-9]|[12][0-9]|3[01])-(0[1-9]|1[0-2])-\d{4}$' pageNumber: type: integer description: Page number sort: type: string description: Sort order UsageSummaryResponse: type: object properties: summary: type: array items: $ref: '#/definitions/UsageSummary' description: List of usage summaries period: type: string description: Usage period pageNumber: type: integer description: Current page number totalPages: type: integer description: Total number of pages UsageSummary: type: object properties: voice: $ref: '#/definitions/Voice' data: $ref: '#/definitions/Data' sms: $ref: '#/definitions/SMS' Voice: type: object properties: totalDuration: type: integer description: Total voice duration unit: type: integer description: Unit of duration count: type: integer description: Number of voice sessions Data: type: object properties: totalDataUsed: type: integer description: Total data used unit: type: integer description: Unit of data count: type: integer description: Number of data sessions SMS: type: object properties: count: type: integer description: Number of SMS sent APIResponseUsageSummaryResponse: type: object properties: status: type: string description: API response status message: type: string description: API response message data: $ref: '#/definitions/UsageSummaryResponse' UsageSummaryRequestBody: type: object required: - msisdn properties: msisdn: type: string description: MSISDN (phone number) minLength: 3 maxLength: 15 pattern: '^[0-9]\d{2,14}$' usageType: type: string description: Type of usage (e.g., voice, data, sms) startDate: type: string description: Start date in DD-MM-YYYY format pattern: '^(0[1-9]|[12][0-9]|3[01])-(0[1-9]|1[0-2])-\d{4}$' endDate: type: string description: End date in DD-MM-YYYY format pattern: '^(0[1-9]|[12][0-9]|3[01])-(0[1-9]|1[0-2])-\d{4}$' APIResponseRechargeHistoryResponse: type: object properties: status: type: string description: Status of the API response message: type: string description: Additional message data: $ref: '#/definitions/RechargeHistoryResponse' ErrorPayload: type: object properties: statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client supportMessage: type: string description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful) transactionId: type: string description: This is the same transactionId that is sent in the request example: "cbd4772b-d1cf-5905-be9d-7a04adedf5b2" path: type: string description: API url path to which the call was made to example: "/v2/consumption" method: type: string description: HTTP verb or method associated with the called API endpoint example: "GET" timestamp: type: string format: date-time description: Timestamp of the error example: "2019-08-23T07:29:25.593+0000"