swagger: '2.0' info: version: v.2.1 title: MTN Customer Plans API contact: name: MTN API Support email: developer-support@mtn.com description: An API to retrieve the Plan details of an MTN customer and calculate aYo premiums. Can also be used by 3rd-party partners (3PP) for airtime recharge of a prepaid subscriber host: api.mtn.com basePath: /v2 schemes: - https consumes: - application/json produces: - application/json securityDefinitions: ApiKeyAuth: type: apiKey name: X-API-Key in: header OAuth2: type: oauth2 flow: application tokenUrl: 'https://api.mtn.com/v1/oauth/access_token' security: - ApiKeyAuth: [] - OAuth2: [] paths: '/customers/{customerId}/plans': get: description: Retrieves the Billing Plan and related details of an MTN customer. summary: View customer plans tags: - Customers parameters: - name: customerId in: path description: 'ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be Eg.123' required: true type: string - name: fixedLine in: query description: Fixed line whose balances is fetched required: false type: string - name: plan in: query description: Plan type to filter list of balances required: false type: string enum: - VOICE - DATA - SMS - name: momo in: query description: Indicates whether to query balances for a MoMo Customer required: false type: boolean - name: includeReservations in: query description: Indicates whether reservations should be included in the response. This parameter goes hand in hand with the momo query parameter and will have no use if supplied when momo is not true. Default is false. required: false type: boolean - name: quoteid in: query description: Indicates whether a corresponding quote should be considered. This parameter goes hand-in-hand with the momo query parameter and will have no use if supplied when momo is not true. required: false type: string - name: x-authorization in: header description: Encrypted ECW credentials required: false type: string responses: '200': description: 'Customer Plans object. For a successful request, the response will contain all the customers details. If the customer does not have any requested data, then those fields will be null. E.g. if the customer does not have a startDate set, then it will be null. If the customer does not have any Balance set, then the Balance array will be null.' schema: $ref: '#/definitions/CustomerPlans' '207': description: 'If there was an error retrieving some part of the request, then the successful request will be shown, and the remaining failed objects will be be excluded. E.g. if there was an error retrieving Balance information, then the balance object will be empty' examples: 'Partially Successfuls Response, showing valid plan data, but balance object is null': data: type: Postpaid status: Active startDate: '2019-04-12T14:31:21.810Z' endDate: '2021-04-12T14:31:21.810Z' language: '1' balance: null '400': description: Bad Request schema: $ref: '#/definitions/Error' '401': description: Unauthorized schema: $ref: '#/definitions/Error' '403': description: Forbidden schema: $ref: '#/definitions/Error' '404': description: Customer not found examples: The data object/envelope will be null: data: null '405': description: Method Not allowed schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' post: description: Requesting a MTN customer's premium per product. summary: Request Premium tags: - Premiums parameters: - name: customerId in: path description: 'ID of the customer who is sending the transaction. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123' required: true type: string - in: body name: body description: Request body required: true schema: $ref: '#/definitions/PremiumRequest' responses: '200': description: 'Customer Plans Premium object. For a successful request, the response will contain all the customers Premium details. If the customer does not have any requested data, then those fields will be null."' schema: $ref: '#/definitions/CustomerPremium' '207': description: 'If there was an error retrieving some part of the request, then the successful request will be shown, and the remaining failed objects will be be excluded.' '400': description: Bad Request schema: $ref: '#/definitions/PremiumError' '401': description: Unauthorized schema: $ref: '#/definitions/PremiumError' '403': description: Forbidden schema: $ref: '#/definitions/PremiumError' '404': description: Customer not found examples: The data object/envelope will be null: data: null '405': description: Method Not allowed schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/PremiumError' '/customers/{customerId}/plans/{productCode}': get: description: Retrieves plans for product summary: View customer plans for product tags: - Customers security: - ApiKeyAuth: [] parameters: - name: customerId in: path description: 'ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123' required: true type: string - name: productCode in: path description: Product code for data package required: true type: string responses: '200': description: 'Customer Plans object. For a successful request, the response will contain all the plans details. If the customer does not have any requested data, then those fields will be null. E.g. if the customer does not have a startDate set, then it will be null. If the customer does not have any Balance set, then the Balance array will be null.' schema: $ref: '#/definitions/CustomerPlans' '207': description: 'If there was an error retrieving some part of the request, then the successful request will be shown, and the remaining failed objects will be be excluded. E.g. if there was an error retrieving Balance information, then the balance object will be empty' examples: 'Partially Successfuls Response, showing valid plan data, but balance object is null': data: type: Postpaid status: Active startDate: '2019-04-12T14:31:21.810Z' endDate: '2021-04-12T14:31:21.810Z' language: '1' balance: null '400': description: Bad Request schema: $ref: '#/definitions/Error' '401': description: Unauthorized schema: $ref: '#/definitions/Error' '403': description: Forbidden schema: $ref: '#/definitions/Error' '/customers/{customerId}/plans/refill': patch: tags: - Customers summary: Airtime Refill description: Will be used by 3rd-party partners (3PP) for airtime recharge of a prepaid subscriber operationId: refillAccount security: - ApiKeyAuth: [] parameters: - name: customerId in: path description: 'ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123' type: string required: true - name: transactionId in: header description: Client generated unique Id to include for tracing requests type: string required: false - name: sourceSystemId in: header description: Source system Id to include for tracing requests type: string required: false - name: refillRequest in: body required: true schema: type: object required: - refillType properties: refillType: type: string description: Specify the refill type enum: - voucher - voucherless voucherActivationCode: type: string description: 'Voucher Activation Code, Required if refillType is Voucher Base.' refillProfileId: type: string description: 'Refill Profile ID, Required if refillType is Voucherless.' transactionAmount: type: string description: Required if refillType is Voucherless responses: '200': description: OK schema: type: object properties: statusCode: type: string description: HTTP error code extension statusMessage: type: string data: type: object properties: amount: type: string description: 'The whole units of the amount. For example if currency is NGN, then 100 unit is' currencyCode: type: string description: The 3-letter currency code defined in ISO 4217. _link: type: object properties: self: type: object properties: href: type: string example: 'https://api.mtn.com/v1/customers/2348064816493/refill' '400': description: Bad Request schema: $ref: '#/definitions/Error' '401': description: Unauthorized schema: $ref: '#/definitions/Error' '403': description: Forbidden schema: $ref: '#/definitions/Error' '404': description: Not Found schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' '503': description: Service Unavailable schema: $ref: '#/definitions/Error' '999': description: Unknown Error schema: $ref: '#/definitions/Error' definitions: PremiumRequest: type: object required: - receivingCustomerId - transactionId - product - amount - transactionType properties: amount: type: string $ref: '#/definitions/Amount' transactionId: type: string description: Internal correlation ID accountHolderId: type: string description: The accountholder's ID to which the sendingCustomerId belong quoteId: type: string description: Can be provided when a quote is associated with the request. receivingCustomerId: type: string description: The beneficiary's customer ID. product: type: string description: The product for which the premium is requested transactionType: type: string description: Different transaction types can have different premiums associated with it. message: type: string description: The calling customer can populate a message intended for the back-end application. CustomerPremium: type: object required: - originReferenceId properties: originReferenceId: type: string description: Origin Reference Id statusCode: type: string description: 'This will have MADAPI response mapping, based on the value received from the downstream system' data: $ref: '#/definitions/PremiumData' link: $ref: '#/definitions/PremiumResponse__links' PremiumData: type: object description: Contains response information pertaining to the premium request. properties: message: type: string description: A message send by the back end pertaining to the premium calculation request premium: $ref: '#/definitions/Amount' loyaltyInformation: $ref: '#/definitions/LoyaltyBalances' LoyaltyBalances: type: object description: Contains all the loyalty balances associated with a customer. properties: generatedAmount: $ref: '#/definitions/Amount' consumedAmount: $ref: '#/definitions/Amount' newBalance: $ref: '#/definitions/Amount' Customer: type: object required: - customerId - _links properties: customerId: type: string plans: type: object description: The customers billing plan $ref: '#/definitions/CustomerPlans' CustomerLinks: type: object required: - self properties: self: type: object required: - href description: The link to retrieve the plans for a customer. properties: href: type: string description: The link to retrieve the plans for a customer. example: 'https://api.mtn.com/v2/customers/27832000000/plan' CustomerPlans: type: object required: - _link properties: _link: $ref: '#/definitions/CustomerLinks' data: $ref: '#/definitions/Plans' MomoBalanceDetail: type: object description: The MoMo Balance details for a requested customer. properties: balance: description: Account holder's available balance for the requested financial resource. $ref: '#/definitions/Amount' positiveReservations: description: Account holder's positive reservations (pending incoming transactions) for the requested financial resource. This value is set if the includereservations field in the request is set to true. $ref: '#/definitions/Amount' negativeReservations: description: Account holder's negative reservations (pending outgoing transactions for the requested financial resource. This value is set if the includereservations field in the request is set to true. $ref: '#/definitions/Amount' loyaltyInformation: $ref: '#/definitions/LoyaltyBalances' overdraft: $ref: '#/definitions/OverdraftInformation' OverdraftInformation: type: object description: Contains overdraft balances if available properties: balance: $ref: '#/definitions/Amount' limit: $ref: '#/definitions/Amount' accessFee: $ref: '#/definitions/Amount' interest: $ref: '#/definitions/Amount' Plans: type: object required: - type - status - startDate - endDate - language - tariffPlan - balance description: The plan details for the customer. properties: type: type: string description: The billing type of the plan. enum: - Prepaid - Postpaid - Hybrid status: type: string description: The current status of the plan. enum: - Active - Suspended - Inactive - RICA Barred - Blacklisted startDate: type: string description: The date the customer was created/provisioned format: date-time endDate: type: string description: The date the plan will be deactivated. format: date-time language: type: string description: The customers language. tariffPlan: type: string description: The customers active tariff plan. balance: type: array description: The account balance details of a customer items: $ref: '#/definitions/CustomerBalance' offers: $ref: '#/definitions/OfferDetails' CustomerBalance: type: object required: - balanceType - expiryDate - balanceDetail - wallets description: The plan balance details for the customer. properties: balanceType: type: string description: 'Identifies the type of balance. A customer plan may have multiple types of balances for different usage, for example, voice, SMS, and game services.' expiryDate: type: string format: date-time description: Expiry date of the wallet's value. category: type: string description: Identifies the category of the balance type. balanceDetail: $ref: '#/definitions/BalanceDetail' momoBalanceData: type: object $ref: '#/definitions/MomoBalanceDetail' wallets: type: array description: The different wallets used to compute the active and unused values of this balance. items: $ref: '#/definitions/Wallet' BalanceDetail: type: object required: - type - activeValue - activeUnit description: The details for a balance type. properties: type: type: string description: This is the type of the value. enum: - CURRENCY - DATA - MINUTES - SMS activeValue: type: string description: This is the aggregated formatted active value of a balance type. activeUnit: type: string description: This is the unit of the aggregated active value. enum: - ZAR - NGN - GB - MB - MINUTES - SMS unusedValue: type: string description: This is the aggregated formatted unused value of a balance type. example: '45.25' unusedUnit: type: string description: This is the unit of the aggregated unused value. enum: - ZAR - NGN - GB - MB - MINUTES - SMS example: NGN Wallet: type: object required: - name - status - expiryDate - amount description: The details for a wallet account. properties: name: type: string description: The name of a wallet account. status: type: string description: The status of a wallet's value. enum: - Active - Unused example: Active expiryDate: type: string format: date-time description: Expiry date of the wallet's value. amount: $ref: '#/definitions/Amount' Amount: type: object required: - value - type - unit description: The amount details for a wallet. properties: type: type: string description: This is the type of the wallet value. enum: - CURRENCY - DATA - MINUTES - SMS value: type: string description: This is the value of a balance wallet. unit: type: string description: This is the unit of the wallet value. enum: - ZAR - NGN - GB - MB - MINUTES - SMS - FCFA example: NGN PremiumError: type: object properties: statusCode: type: string description: 'This will have MADAPI response mapping, based on the value received from the downstream system' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client. supportMessage: type: string description: Support Message transactionId: type: string description: Message ID _links: $ref: '#/definitions/PremiumResponse__links' PremiumResponse__links_self: type: object properties: href: type: string description: Hyperlink to access the problem. PremiumResponse__links: type: object properties: self: $ref: '#/definitions/PremiumResponse__links_self' description: Relevant links to the problem. Error: type: object required: - statusCode - statusMessage properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' 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 timestamp: type: string format: date-time description: Timestamp that the error occurred path: type: string description: The path that caused the error method: type: string description: The HTTP method type that was used example: GET OfferDetails: type: object description: The Offer Details per customer. properties: offerId: type: string example: '123456' description: The Offer ID offerType: type: string example: '2' description: The type of offer startDate: type: string format: dateTime example: '20210205T16:08:08+0530' description: The start date of offer expiryDate: type: string format: dateTime example: '20210205T16:08:08+0530' description: Date at which offer will expire expiryDateValue: type: string example: '53402237800000' description: Value of the expiry date